DBJavaGenix

把"用 LLM 看着数据库做反向工程"做成一件可重复、可审计的事。 Skills 定义"怎么做" · MCP 提供"能做什么" · MCP Apps 让结果"看得见"。

graph LR
    Client[Claude Desktop / Cursor / Cherry] -->|Skill 加载| Skills
    Skills[".claude/skills/<br/>java-codegen-from-db<br/>springboot-migration"]
    Skills -->|按需调用| MCP

    subgraph MCP[MCP Server 29 工具]
        direction TB
        DB[db_* 连接 / 查询 / 描述]
        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/mapper]
        AI[ai_infer_business_names<br/>ai_recommend_template<br/>ai_summarize_schema]
        Vis[db_render_er_diagram]
        Obs[server_metrics / server_health<br/>ai_metrics / search_tools]
    end

    MCP -->|返回 _meta| Apps[MCP Apps 渲染]
    Apps -->|mermaid / dashboard / code-diff / tree| Client
    MCP -->|读取| Data[MySQL / SQLite + Mustache templates]

它解决什么问题

把数据库表反向生成成 Spring Boot 工程 (Entity/DAO/Service/Controller/Mapper) 不是新东西 —— EasyCode、MyBatis-Plus Generator、Renren-generator 都做了多年。LLM 时代的区别在于:

维度	老工具	DBJavaGenix v0.2
工作流谁定	用户在 IDE 点配置面板	Skill 文件显式编排 (LLM 不会乱调)
调用粒度	一个大按钮一步到位	6 个原子工具 (build_context + 5 个 render_*),LLM 可中途让用户改 context 重渲
启动开销	(插件,常驻)	默认 ~3300 tok / 渐进模式 ~985 tok (节省 70%)
命名	表前缀机械映射	15 条规则 + Claude API,识别 RBAC/电商/CMS 模式
输出可视化	IDE 内文本	MCP Apps: Mermaid ER 图 / 依赖仪表盘 / code-diff / 包结构树
可观测性	无	server_metrics + ai_metrics + server_health

快速开始

Docker (推荐)

docker build -t dbjavagenix:latest .

在 claude_desktop_config.json 添加:

{
  "mcpServers": {
    "dbjavagenix": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "DBJAVAGENIX_PROGRESSIVE=1",
               "-e", "ANTHROPIC_API_KEY",
               "dbjavagenix:latest"]
    }
  }
}

本地 dev

git clone https://github.com/ZhaoXingPeng/DBJavaGenix.git
cd DBJavaGenix
uv venv && uv pip install -e ".[dev]"
PYTHONPATH=src python -m dbjavagenix.cli server

第一次使用

在 LLM 客户端里说 "从数据库 myapp 的 sys_user / sys_role / sys_user_role 三张表生成 Spring Boot 代码",Claude 会:

1. 加载 java-codegen-from-db Skill,按 5 阶段工作流推进
2. 调用 db_connect_test → db_table_describe → db_table_foreign_keys 收集 schema
3. 调用 db_render_er_diagram → 客户端渲染 Mermaid ER 图
4. 调用 ai_infer_business_names 推断 → sys_user_role 应是 UserRoleAssignment
5. 调用 ai_recommend_template 推荐 → 检测到 RBAC,推 MybatisPlus-Mixed
6. 用 codegen_build_context + 5 个 codegen_render_* 分层生成,每层返回 code-diff
7. 用户确认后写盘

核心能力 (Phase 1 → 5)

Phase 1 现代化基础

• Python ≥ 3.11 / mcp ≥ 1.6 / Spring Boot 3.5 + Java 21 模板
• 单元测试 360+,GitHub Actions CI 三 Job (lint / template-render / docker-build)
• 多阶段 Dockerfile (python:3.11-slim + 非 root 用户)

Phase 2 Skills 层与原子工具

• .claude/skills/java-codegen-from-db/SKILL.md 显式定义 5 阶段工作流
• db_codegen_generate 拆为 6 原子工具,context 显式传递
• search_tools 工具实现 progressive discovery,启动 token 节省 70.2%
• 第二个 Skill springboot-migration (2.7→3.x 升级 checklist)
• token usage benchmark

Phase 3 MCP Apps 集成

4 个交互式 UI 组件:

组件	类型	来源工具
ER 图	mermaid	db_render_er_diagram
依赖健康仪表盘	dashboard	springboot_analyze_dependencies
代码预览 + Diff	code-diff	codegen_render_* (6 个)
包结构树	tree	db_codegen_generate

客户端兼容性 + headless 验证。

Phase 4 AI 语义增强

• ai_infer_business_names: 15 条规则 + 可选 Claude API (Anthropic SDK + prompt caching)
• ai_recommend_template: 检测 RBAC / 电商 / CMS / 工单 4 种模式
• ai_summarize_schema: 整库自然语言概述
• ai_metrics: 暴露 cache_hit_rate / tokens_saved
• 设计取舍: 规则先于 LLM,无 ANTHROPIC_API_KEY 也能跑

Phase 5 可观测性与生产就绪

• server_metrics: 每个工具的 calls / avg_duration / error_rate
• server_health: Python / mcp / anthropic SDK 版本 + 模块导入状态
• 结构化日志: DBJAVAGENIX_LOG_FORMAT=json 可输出单行 JSON,适合 Loki/ELK
• 部署手册: 3 种部署模式 + 6 个排障场景

工具总览 (29 个)

类别	工具
连接 / 查询	db_connect_test / db_query_databases / db_query_tables / db_query_table_exists / db_query_execute
表结构	db_table_describe / db_table_columns / db_table_primary_keys / db_table_foreign_keys / db_table_indexes
代码生成 (atomic)	codegen_build_context / codegen_render_entity / codegen_render_dao / codegen_render_service / codegen_render_controller / codegen_render_mapper
代码生成 (legacy)	db_codegen_analyze / db_codegen_generate
Spring Boot 项目	springboot_validate_project / springboot_analyze_dependencies / springboot_read_config
可视化	db_render_er_diagram
AI 语义	ai_infer_business_names / ai_recommend_template / ai_summarize_schema / ai_metrics
可观测	server_metrics / server_health
元工具	search_tools (渐进发现)

与同类工具对比

维度	DBJavaGenix v0.2	EasyCode	MyBatis-Plus generator	Renren-generator
驱动方式	LLM + MCP	IDEA 插件	命令行 / Maven plugin	Web UI
工作流编排	Skill 显式 5 阶段	配置面板	一次性代码	表单
工具粒度	6 原子 (可中途让用户改)	单按钮	单命令	单按钮
AI 命名	✅ 15 规则 + 可选 LLM	❌ 纯模板	❌	❌
模板扩展	✅ Mustache + 4 分类 (sb35-java21 含)	✅ Velocity	⚠️ 仅 MybatisPlus	⚠️ 仅 freemarker
ER 图渲染	✅ Mermaid (MCP App)	❌	❌	⚠️ 静态
依赖适配	✅ 智能档案 + 健康分	❌	❌	❌
可观测性	✅ in-process metrics + health	❌	❌	❌
客户端兼容	Claude Desktop / Cursor / Cherry / ...	仅 IDEA	CLI	浏览器

技术架构

详见 iteration-plan/01-target-architecture.md。三层职责:

[ Skills 层 ]  定义"怎么做" — .claude/skills/*.md  显式 5 阶段工作流
       ↓
[ MCP 层 ]     提供"能做什么" — 29 个原子工具  context 显式传递
       ↓
[ Apps 层 ]    让结果"看得见" — 4 个 UI 组件 (mermaid/dashboard/code-diff/tree)

每层都做"工程克制":

• 不引入向量数据库 (schema 是结构化数据,LLM 直接读更准)
• 不引入 LangChain (Skill 已显式编排,不需要 chain 抽象)
• 不引入 prometheus_client / opentelemetry-sdk (stdio 单进程过度设计)

文档

文档	内容
iteration-plan/	6 阶段重构方案 (目标架构 / 路线图 / 决策记录 / 演示故事)
docs/deployment.md	部署模式 / 环境变量 / 健康检查 / 排障
docs/benchmarks/token-usage.md	tool schema token 测量
docs/screenshots/README.md	MCP Apps 4 组件客户端兼容性
docs/algorithms-overview.md	v0.2.1 schema 图算法 (topo / cluster / cycle)
docs/design-patterns-catalog.md	生成器与生成代码中的设计模式
docs/adr/	10 个 ADR (架构 / 原子 / 渐进 / 规则 / 不引依赖 / schema 算法 / 规范配置 / MCP v3 / 1h 缓存 / agentic)
.claude/skills/java-codegen-from-db/SKILL.md	主 Skill: 代码生成 5 阶段工作流
.claude/skills/springboot-migration/SKILL.md	第二 Skill: Spring Boot 2.7→3.x 迁移

路线图

• [x] Phase 1: 基础设施现代化 (Python 3.11 / mcp 1.6 / Spring Boot 3.5 模板 / CI / Docker)
• [x] Phase 2: Skills 层抽离 + 原子工具 + Progressive Discovery (token -70%)
• [x] Phase 3: MCP Apps 集成 (4 个 UI 组件)
• [x] Phase 4: AI 语义增强 (规则 + 可选 LLM)
• [x] Phase 5: 可观测性 + 生产就绪
• [x] Phase 6: 文档与演示
• [x] v0.2.1: Java 工程补完 (schema 算法 3 个 / 工程规范配置生成器 / 设计模式 catalog)
• [x] v0.2.2: MCP v3 + AI 工程化 (elicitation 表单 / sampling 借 LLM / 1h prompt caching / agentic-runner)

下一步 (v0.3 候选):

• DB 后端扩展: PostgreSQL / Oracle 完整支持
• 抓取 Claude Desktop / Cursor 截图入仓 (P3.5 收尾)
• 集成测试: 用 Testcontainers 把 MySQL 拉起跑端到端
• 性能: 把规则推断与 LLM 路径合并为同一返回 schema (current LLM 路径输出格式与规则略不同)
• agentic-runner 加 subagent 支持 (Agent SDK 已就绪)

启动模式

模式	入口	触发	依赖	适用场景
MCP server	dbjavagenix server	客户端连接 (Claude Desktop / Cursor 等)	无额外	探索 / 多轮交互 / 默认
Agentic runner	server.agentic_runner.run_agentic()	CLI 单次启动	claude-agent-sdk + ANTHROPIC_API_KEY	批处理 / CI / 一次性任务

两种模式共用同一 database.mcp_tools 注册表 (ADR-010)。

调试技巧

# 启用 progressive 模式 (仅暴露 6 个 always_visible 工具)
DBJAVAGENIX_PROGRESSIVE=1 PYTHONPATH=src python -m dbjavagenix.cli server

# JSON 日志 (适合 Loki / ELK)
DBJAVAGENIX_LOG_FORMAT=json DBJAVAGENIX_LOG_LEVEL=DEBUG \
  PYTHONPATH=src python -m dbjavagenix.cli server

# headless 验证所有 MCP App 组件
PYTHONPATH=src python scripts/verify_mcp_apps.py

贡献

1. Fork → 创建 feature/* 分支
2. 写测试 (tests/unit/),pytest tests/unit/ 应保持 360+ 全过
3. ruff check src/ tests/ 通过 (CI 会跑)
4. 提 PR,链接到对应的 iteration-plan 阶段

许可证

MIT — 见 LICENSE。

致谢

• EasyCode — 早期模板设计灵感
• Model Context Protocol — Anthropic / Linux Foundation
• Anthropic Claude — AI 语义层

联系

• 作者: ZXP · 邮箱: 2638265504@qq.com
• 仓库: https://github.com/ZhaoXingPeng/DBJavaGenix
• Issues: https://github.com/ZhaoXingPeng/DBJavaGenix/issues