git:20260907.6966012 to git:20260907.7f64c1a

---

name: java-codegen-from-db

description: 从 MySQL/PostgreSQL/SQLite 数据库表反向生成 Spring Boot Java 工程代码(Entity/DAO/Service/Controller/Mapper)。当用户提到"生成 Java 代码"、"反向工程"、"按数据库建模"、"从表生成 Spring Boot"等需求,且能提供数据库连接信息或已有连接时使用。

when_to_use:

- 用户提供了数据库连接(host/port/user/pwd/database)并要求生成 Java 代码

- 用户已经通过 db_connect_test 建立了连接,提到具体表名要"生成代码"/"做反向工程"

- 用户提到 Spring Boot 项目"从数据库建模"或要求把表结构转成 Entity/Repository/Service

when_not_to_use:

- 用户只是想"看一下表结构" → 直接用 db_table_describe,不要走完整 skill

- 用户在做 Spring Boot 版本升级(2.x → 3.x)→ 使用 springboot-migration skill

- 用户在调试现有代码 → 不需要生成

---

# java-codegen-from-db

## 工作流总览

本 skill 把"从数据库表生成 Java 代码"拆为 **5 个显式阶段**,每个阶段调用具体的 MCP 工具,关键决策点会暂停让用户确认。**不允许跳步**——前一步的输出是后一步的输入。

```

[1] 预检查项目 → [2] schema 分析 → [3] 语义增强(可选)

↓

[5] 写盘 ← [4] 分层渲染(等待用户确认)

```

---

## 阶段 1: 预检查项目(必做)

**目的**: 在生成代码前确认目标 Spring Boot 项目结构合法、依赖大致齐全。否则生成出来也编译不过。

### 1.1 验证项目结构

调用 **`springboot_validate_project`**:

- 参数: `{ "check_dependencies": true, "create_missing_dirs": true, "template_category": "<用户选定的分类>" }`

- 期待返回中包含 `Project Structure: ✅ OK` 或 `✅ Project Root`

- 如果失败 → 告诉用户具体缺什么,**不要继续**

### 1.2 分析依赖健康度

调用 **`springboot_analyze_dependencies`**:

- 参数:

```json

{

"template_category": "<同上>",

"database_type": "mysql|postgresql|sqlite",

"include_swagger": true,

"include_lombok": true,

"include_mapstruct": true

}

```

- 返回中提取 `Missing Dependencies: N`:

- N == 0 → health = 100,继续

- N ≤ 2 → health = 80,继续但提醒用户

- N ≤ 5 → health = 60,**暂停让用户决定是否继续**

- N > 5 → health = 40,**强烈建议先修依赖**,问用户是否要看具体清单

### 1.3 渲染依赖健康仪表盘(MCP App)

如果客户端支持 MCP Apps(`_meta` 渲染),返回值中应附加:

```json

{

"_meta": {

"mcp-apps/component": "dashboard",

"mcp-apps/data": { "score": <health>, ... }

}

}

```

现阶段如未支持,用文本表格代替。

---

## 阶段 2: schema 分析(必做)

**目的**: 拿到目标表的列、主键、外键、索引,这是模板渲染的输入。

### 2.1 建立或复用连接

如果用户尚未连接:

- 调用 **`db_connect_test`** with `{host, port, username, password, database, database_type}`

- 拿到 `connection_id`,记住它,后续所有调用都要带

### 2.2 列出表名(可选)

当用户没指明表,先列出来让用户选:

- 调用 **`db_query_tables`** with `{connection_id, database}`

- 把表名列给用户,等用户选

### 2.3 描述目标表

对每张目标表:

- 调用 **`db_table_describe`** with `{connection_id, database, table, include_java_types: true}`

- 这一步会返回列定义 + 推断的 Java 类型

### 2.4 获取外键关系

- 调用 **`db_table_foreign_keys`** with `{connection_id, database, table}`

- 多张表时一起调,然后给用户渲染 ER 图(MCP App `mermaid` 组件)

### 2.5 渲染 ER 图(MCP App)

当用户选了 ≥ 2 张表,构造 Mermaid `erDiagram` 字符串,放进 `_meta["mcp-apps/source"]`。

---

---

## 阶段 4: 分层代码生成(★ 用原子工具,而不是大工具)

**重要**: Phase 2.2 之后,我们用 7 个原子工具替代旧的 `db_codegen_generate`。**优先用原子工具**。

### 4.1 构建上下文

调用 **`codegen_build_context`**:

```json

{

"connection_id": "<...>",

"table_name": "<...>",

"database": "<...>",

"template_category": "Default | MybatisPlus | MybatisPlus-Mixed | sb35-java21",

"author": "<...>",

"package_name": "com.example.xxx",

"include_swagger": true,

"include_lombok": true,

"include_mapstruct": true,

"project_path": "test_project"

}

```

返回值: 完整的 `context` 对象(JSON,**不写盘**)。LLM 把这个对象作为后续 render 工具的输入。

### 4.2 分层渲染

按顺序对**每个层**调用对应工具,每次都传 `context`:

| 工具 | 渲染层 | 模板文件 |

|------|--------|----------|

| `codegen_render_entity` | 实体类 | entity.mustache |

| `codegen_render_dao` | DAO/Repository | dao.mustache |

| `codegen_render_service` | Service 接口 | service.mustache + serviceImpl.mustache |

| `codegen_render_controller` | REST Controller | controller.mustache |

| `codegen_render_mapper` | MyBatis XML | mapper.mustache(仅 MybatisPlus/Mixed) |

| `codegen_render_dto` | DTO(sb35-java21 record) | dto.mustache(可选) |

每次返回:

```json

{

"code": "<完整 Java 源码字符串>",

"file_path": "<相对路径,如 com/example/entity/SysUser.java>",

"_meta": {

"mcp-apps/component": "code-diff",

"mcp-apps/language": "java",

"mcp-apps/before": "<目标位置已存在文件的内容,无则 null>",

"mcp-apps/after": "<同 code>"

}

}

```

### 4.3 用户确认点 ★

渲染完所有层后,**先不要写盘**。让用户:

1. review 每个文件的内容(MCP App diff 渲染)

2. 修改 `context`(如包名、字段类型)

3. 重新调用对应的 `codegen_render_*`

确认无误后才进阶段 5。

### 4.4 兼容退路: 单体工具

如果某些环境只有旧版工具:

- 调用 **`db_codegen_generate`** (单次完成 2.1~4.4 + 写盘)

- 仅当用户明确要"一步到位"时使用,**默认走原子工具路径**

---

## 阶段 5: 写盘

### 5.1 调用写盘工具

> Phase 2.2 引入: 现阶段写盘逻辑在原子工具或 `db_codegen_generate` 内部。后续会拆出独立 `file_write_to_project` 工具。

### 5.2 渲染包结构树(MCP App)

写盘前/后用 `tree` 组件展示新生成文件的目录结构,让用户最后确认。

### 5.3 备份与回滚

如果目标文件已存在,生成 `*.codegen.bak` 备份,告诉用户怎么回滚(`mv x.bak x`)。

---

## 错误处理与重试规则

- **连接失败**: 不要无限重试,告诉用户检查 host/port/credentials

- **表不存在**: 调用 `db_query_table_exists` 二次确认,**不要假设**

- **依赖严重缺失** (health < 60): 暂停,问用户是否要看 `springboot_analyze_dependencies` 详细报告

- **写盘失败**: 报告具体 IO 错误,不要静默吞掉

- **模板渲染失败**: 检查 `template_context` 字段完整性(常见: `className`、`columns`、`primaryKeyType` 缺失)

## 工具调用清单速查

按调用顺序:

```

[预检] springboot_validate_project

springboot_analyze_dependencies

[schema] db_connect_test (若未连接)

db_query_tables (若未指定表)

db_table_describe (×N 张表)

db_table_foreign_keys (×N 张表)

[生成] codegen_build_context (×1 per 表)

codegen_render_entity (×1 per 表)

codegen_render_dao (×1 per 表)

codegen_render_service (×1 per 表)

codegen_render_controller (×1 per 表)

codegen_render_mapper (×1 per 表, 仅 MybatisPlus)

codegen_render_dto (×1 per 表, 仅 sb35-java21)

[写盘] (内置于上述工具,Phase 3 后拆出 file_write_to_project)

```

## 设计原则

1. **显式编排** > 黑盒自动: skill 把"做什么、按什么顺序、何时停"写死,LLM 不要自由发挥

2. **原子工具** > 大而全: 每个工具职责单一,返回值清晰

3. **用户决策点不可绕过**: 语义推断、模板选择、写盘三处必须 pause

4. **context 显式传递**: 工具间通过参数传 `context`,不依赖 server 内部状态

5. **失败要说人话**: 不要把堆栈直接糊给用户

## 与 iteration-plan 的对应