乐于分享
好东西不私藏

一个能自己写代码的 Java 项目模板:从「初始化到上线」全交给 AI

一个能自己写代码的 Java 项目模板:从「初始化到上线」全交给 AI

我花了点时间,把整套 Spring Boot 开发规范塞进了一个 Claude Code 模板仓库。现在新人 clone 完项目,在 Claude Code 里打一句 /scaffold full,十几秒后整套 Java 项目骨架就位——编译直接过,测试直接绿。

封面图:一位开发者面对满屏代码的 silhouette,右侧浮现 Claude Code 的对话框界面,打出 /scaffold full 命令后,项目骨架如光束般逐一点亮

一、问题:每次新建项目都有「初始化地狱」

做过 Java 后端的人都知道,新建一个 Spring Boot 项目有多痛苦:

  1. pom.xml —— 版本号对齐到天亮 :Spring Boot 3.2.5、MyBatis-Plus 3.5.7、Oracle 19c、Lombok、Hutool、MapStruct、Knife4j……少一个就编译报错
  2. 统一返回体 —— 每个项目都要写一遍 R<T> 类,刚写出来的还会和公司的 eking-common-doc 包冲突
  3. 异常体系 —— BaseException、ErrorCode 接口、GlobalExceptionHandler……每次从零实现,每次漏掉几个方法
  4. Oracle 主键策略 —— @KeySequence、@JsonSerialize(using = ToStringSerializer.class)、NUMBER(19) 映射,新人不踩三次坑记不住
  5. 测试骨架 —— Service 测试、Controller 测试、Mapper 测试,光是把框架搭好就要半天

更糟的是:这些「初始化模板」每一份都不一样。张三的项目用的是 3 月的那版脚手架,李四的项目用的 6 月的那版,中间改了什么东西——完全不可追溯。

想象一下这个场景:你满怀期待地打开 IDE,准备大展身手,结果前三天都在修 pom.xml 的版本冲突和补 BaseException 的构造器签名。代码一行没写,体力已经耗尽。


二、解法:把规范写成 Claude Code 的配置

我们的核心想法很简单:

代码 = SOP(团队),模板 = 能自动生成代码的配置。

不是写一个需要人来阅读的 Wiki 文档,而是写一套 Claude Code 每次干活都要读的配置文件。具体结构:

项目结构概念图:以树状图展示 java-claudecode-template 的目录层级,左侧标注 CLAUDE.md 为"团队大脑",.claude/rules/ 为"红线守卫",agents/ 为"5位AI员工",整体以蓝色科技风格呈现
java-claudecode-template/├── CLAUDE.md                  ← 团队共享指令(架构分层、命名规范、红线规则)├── CLAUDE.local.md            ← 个人本地配置(Maven 路径、Oracle 连接)├── .claude/│   ├── commands/scaffold.md   ← /scaffold 命令的参数定义│   ├── skills/scaffold/SKILL.md ← 代码生成工作流(4 Step + 5 Phase)│   ├── rules/                 ← 全局规则(代码风格、API 规范、测试规范)│   ├── agents/                ← 5 个 AI 子代理(产品架构师/后端/运维/审查/安全)│   └── skills/pipeline/SKILL.md ← 需求流水线工作流├── pom.xml                    ← 14 个依赖已配齐├── src/main/resources/        ← 4 环境配置(dev/test/prod + springdoc)├── sql/                       ← SQL 模板└── .mcp.json                  ← MCP 工具配置

设计哲学:这不是一个「示例项目」,这是一个零代码的生成器。仓库里没有一行 Java 源码——所有代码都通过 /scaffold 按需生成。

打个比方:你不会往模具里放一个成品零件当参考。模具本身就是规则——只要注入正确的参数,出来的东西天然合规。我们的模板就是这个模具。


三、核心能力:打一句命令,生成全套骨架

# 三步上手cp -r java-claudecode-template/ my-projectcd my-project# 编辑 CLAUDE.local.md 中的数据库连接# 打开 Claude Code 执行:/scaffold full

Claude Code 会先做三件事:

scaffold 工作流程图:从左到右展示 4 个 Step 的流水线——Step 0 人机确认(对话框+参数表格)→ Step 0.3 参数守卫(红绿灯图标)→ Step 2 五 Phase 生成(5个齿轮依次转动)→ Step 3 编译测试验证(打勾图标),整体横向布局

Step 0 — 人机确认

Claude Code 先从配置文件读取参数,生成一份确认清单让你审核:

从 CLAUDE.local.md 读取到配置生成确认清单| 参数        | 值                    ||------------|-----------------------|| 基础包      | cn.eking.smc.mdm       || Spring Boot | 3.2.5                 || 序列号模块  | 是                     || JDBC 工具   | 是                     |是否继续? (y/n)

这一步的意义不只是「让你再看一眼」。更重要的是——把生成行为的输入参数固定下来,后续追溯时你可以清楚知道:这套代码是在什么配置下生成的。

Step 0.3 — 参数守卫

程序化校验,拒绝一切「看起来能跑但实际是默认值」的参数:

if [ -z "$BASE_PKG" ]; then exit 1; fi   # 缺包名直接中止if echo "$BASE_PKG" | grep -qi "com.company"; then exit 1; fi  # 模板默认值拒绝执行

🔒 这是模板的安全底线。很多人 clone 完模板后懒得改默认值,直接跑——出来的代码包名是 com.company,接上真实环境就出问题。参数守卫就是在这一步拦住你。

Step 2 — 按 5 个 Phase 生成文件

确认无误后,Claude Code 进入核心生成阶段,按 5 个 Phase 依次产出:

Phase 1: 基础设施   → Application.java + R<T> + Exception + Config (8 files)Phase 2: 业务模块   → User 模块完整 CRUD (9 files)Phase 3: 测试 + SQL → 单元测试 + Oracle DDLPhase S: 序列号     → BusinessSequence 编号生成器 (4 files)Phase U: JDBC 工具  → OracleJdbcHelper 纯 JDBC 验证工具 (1 file)

💡 注意 Phase 的编号方式:1/2/3 是必选基础流程,S/U 是可选扩展模块。序列号和 JDBC 工具只在 CLAUDE.local.md 里声明了才生成,不会污染不需要的项目。

Step 3 — 编译 + 测试验证

生成完毕后自动跑三轮验证,确保不是「看着能跑但实际不行」的代码:

mvn -s $MVN_SETTINGS clean compile -q      # 编译mvn test-compile -q                         # 测试编译(确认 ErrorCode 接口全部实现)mvn test -Dtest="*ServiceImplTest" -q      # 运行测试rg "System\.(out|err)" src/main/java/      # 安全检查

十几秒后输出:

生成完成| 基础包   | cn.eking.smc.mdm  || 生成文件 | 12 个             || 编译状态 | ✅ 通过            || 测试状态 | ✅ 全部通过        |

而且参数自动写入 CLAUDE.local.md,下次再生成新模块时不再重复提问。

从 clone 到项目骨架就位,整个过程不需要你写一行代码。只需要回答一次「是」——然后等十几秒。


四、设计亮点:解决真实踩过的坑

这套模板不是凭空设计的,而是在 cn.eking.smc.mdm 项目上用 /scaffold full 实际跑了一遍后,把所有踩过的坑都修了:

踩坑修复对照图:左侧暗色背景的"坑"列表(红色标记),右侧亮色背景的"修复"列表(蓝色标记),中间用箭头连线,形成"问题→解决"的视觉叙事
坑
修复
eking-common-doc 缺版本号
pom.xml 填入 3.0.0-SNAPSHOT
ErrorCode 接口缺 7 个方法
生成模板补充完整实现
BaseException 构造器签名不匹配
改为 super(code, message)
@MockitoBean 在 Boot 3.2 不存在
版本适配:<3.4 用 @MockBean
any()
 泛型歧义
测试模板指定 any(UserEntity.class)
getDeleted() == 1
 NPE
全局红线:强制 Objects.equals()
SpringDoc 自动配置冲突
application.yml 预置 springdoc/knife4j 配置
旧包目录残留
Step 1 自动清理
参数没有程序化校验
Step 0.3 增加 exit 1 守卫

💬 这不是一个「理论上正确」的模板,这是一个实际跑通、编译能过、测试全绿的模板。

每一个修复背后都是一次真实的编译失败或测试报红。我们把「踩坑」变成了「填坑」——而且填完之后,坑不会再出现,因为生成器每次都会自动绕过它。


五、扩展到更多场景

当前模板面向 Java 后端(Spring Boot 3 + Oracle + MyBatis-Plus),但架构完全可平移到其他技术栈。

5.1 扩展到前端项目

前端项目也可以建立同样结构的元仓库:

frontend-template/├── CLAUDE.md                      ← 团队共享(组件规范、路由约定、状态管理)├── .claude/│   ├── rules/│   │   ├── component-style.md     ← 组件写法规范(Vue SFC 或 React Hooks)│   │   ├── api-layer.md           ← 与后端的接口对齐规范│   │   └── design-tokens.md       ← Figma 设计令牌 → Tailwind/SCSS 变量映射│   ├── commands/generate.md       ← /generate page:xxx 生成页面│   ├── agents/│   │   ├── frontend-engineer.md   ← 前端工程师(页面+组件+状态)│   │   └── ui-reviewer.md         ← UI 审查(对齐设计稿)│   └── skills/│       └── scaffold/SKILL.md      ← Phase: layout → page → component → test├── package.json                    ← 依赖模板├── vite.config.ts                  ← 构建模板└── src/                            ← 空壳,由 scaffold 生成

使用方式完全相同。新人 clone 后在 Claude Code 里执行 /generate page:user-list,根据后端的接口定义(可以用 OpenAPI JSON 作为输入)自动生成完整的页面、组件、API 调用层、状态管理代码。

关键:前后端通过接口契约对齐。后端 /scaffold module:order 生成接口后,前端 /generate page:order-list 读取同一份 OpenAPI 定义来生成展示页面。两套模板通过共享的 .mcp.json 引用同一个文档源。

5.2 扩展到数据产品(数仓/BI/ETL)

数据产品通常涉及 DDL 建表、数据清洗 SQL、调度配置、监控告警。同样可以用 Claude Code 模板管理:

data-template/├── CLAUDE.md                      ← 数据团队共享(表命名/分区策略/血缘规范)├── .claude/│   ├── rules/│   │   ├── ddl-convention.md      ← DDL 规范(字段类型/注释/分区)│   │   ├── etl-style.md           ← ETL SQL 风格(CTE/窗口函数/物化视图)│   │   └── quality-check.md       ← 数据质量校验规则│   ├── commands/│   │   └── generate.md            ← /generate ddl:xxx 生成建表语句│   └── agents/│       ├── data-modeler.md        ← 数据建模师(维度/事实表设计)│       └── etl-engineer.md        ← ETL 工程师(SQL 生成+优化)├── ddl/                           ← 建表语句模板├── etl/                           ← ETL SQL 模板└── config/                        ← 调度配置模板

使用方式:

# 根据业务描述自动生成 DDL/generate ddl:用户行为日志表,按天分区,字段包括 user_id, action, timestamp, metadata# 根据源表和目标表生成 ETL/generate etl:从 behavior_log_ods → behavior_log_dwd,清洗规则是过滤 status=0 并提取 JSON 中的 device_id

这套模式下,数据产品的「规范」不再是一篇没人更新的 Confluence Wiki,而是 Claude Code 每次生成 SQL 时自动遵守的 rules/ 规则文件。表名用不用下划线、分区键用不用 dt、字段注释是不是必须写——全部由配置约束,不靠人记。

5.3 多模板协作:用元仓库统一管理

当团队同时有 Java 后端、Vue 前端、数据 ETL 三套模板时,可以用一个元仓库(meta-repo)统一收编:

多模板扩展全景图:中央为元仓库 team-workspace,向三个方向辐射出 java/vue/data 子模板,每个子模板上方悬浮对应的 AI agents 图标,底部标注"规范即配置"的核心理念
team-workspace/              ← 元仓库:只装配置,不装业务代码├── CLAUDE.md                ← 跨项目大图景├── java/                    ← 子目录:Java 模板│   ├── CLAUDE.md│   └── .claude/...├── vue/                     ← 子目录:Vue 前端模板│   ├── CLAUDE.md│   └── .claude/...└── data/                    ← 子目录:数据产品模板    ├── CLAUDE.md    └── .claude/...

新人入职 clone 元仓库、跑一个脚本拉齐业务子项目,打开 Claude Code 后 5 个 AI 角色自动就位——不管是写 Java 还是写 SQL,规范都在。

这才是「团队基础设施」应有的样子:不是散落在各处的文档和口头约定,而是一套人人克隆、人人可用、人人遵守的配置体系。


六、总结

这套模板的核心可以归结为三句话:

1 规范不是文档,是配置。 红线、命名、架构分层不再躺在 Wiki 里等人看,而是写进了 Claude Code 的 rules/——它每次干活都会读,读完了就遵守。

2 模板不是示例代码,是代码生成器。src/ 目录是空的,所有 Java 代码都是 /scaffold 按 5 个 Phase 生成的。换一个项目,换一个包名,同一套模板再生成一次——质量一致,风格统一。

3 新人不是靠文档上手,是靠环境就位。 Clone 完仓库,Maven 路径、Oracle 连接、AI 角色、MCP 工具全部从 CLAUDE.local.md 自动加载。不再是「你去找 Wiki 看看」,而是「你打开 Claude Code,打一句命令,代码就来了」。

曾经:「先把框架搭好,把 SSM 的那一堆 XML 配通,你这周就算没白过。」 后来:有了 Spring Boot,自动配置把 XML 消灭了大半。 现在:有了 Claude Code,也许**「配通框架」这件事本身,也可以交给 AI 了** 。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料