一、起源
1.1 重复劳动的三处
| 重复劳动 | 具体内容 | 手工成本 |
|---|---|---|
| 项目骨架 | 目录结构、依赖声明、构建脚本、配置骨架 | 每次新建项目都要重复,且各项目逐渐分叉 |
| 数据访问层 | 实体、映射接口、映射文件、基础查询方法 | 表数量多时成本线性增长,且容易不一致 |
| 接口骨架 | 接口定义、请求与响应对象、客户端调用代码 | 前后端或多服务对接时重复书写且易偏差 |
1.2 生成的边界
生成适合"结构确定、内容重复、规则明确"的产物,不适合承载业务逻辑:
| 适合生成 | 不适合生成 |
|---|---|
| 结构与样板代码 | 业务规则与状态流转 |
| 由元数据推导的映射与转换 | 需要判断与取舍的编排逻辑 |
| 由契约推导的接口与客户端 | 与外部系统的交互策略 |
判断标准是"内容能否由元数据完全推导"。能推导的部分生成,需要判断的部分手写。
1.3 取舍
| 选择 | 获得 | 付出 |
|---|---|---|
| 使用生成 | 结构一致、重复劳动减少、契约与实现不易偏离 | 需要维护模板与配置,需处理生成物与手写代码的边界 |
| 完全手写 | 无额外工具依赖 | 结构随人而异,重复劳动随规模放大 |
二、原理
2.1 脚手架
脚手架解决"新项目从零到可运行"的问题,产物包含三部分:
| 产物 | 内容 | 需要固定的原因 |
|---|---|---|
| 依赖声明 | 起步依赖与版本管理 | 版本策略统一,避免各项目自行决定 |
| 构建脚本 | 插件配置、包装脚本、构建阶段 | 构建行为一致,流水线可复用 |
| 目录与配置 | 分层结构、配置文件骨架、基础约定 | 结构统一,降低理解成本 |
两种用法:直接生成到本地目录,或作为组织内部的模板仓库,由脚手架工具按模板产出并附带组织约定(代码规范配置、流水线配置、日志与异常骨架)。
2.2 数据库反向生成
从数据库结构生成数据访问层代码,产物通常为四类:
| 产物 | 内容 | 风险 |
|---|---|---|
| 数据对象 | 与表结构对应的属性集合 | 与领域模型混淆,把表结构直接当业务模型 |
| 映射接口 | 基础增删改查方法声明 | 与手写的复杂查询混在同一接口中 |
| 映射文件 | 基础语句的映射定义 | 与手写语句位于同一文件时被覆盖 |
| 条件对象 | 由条件构造器生成的查询条件类 | 容易被误用为业务查询的唯一手段 |
核心冲突是重新生成会覆盖手写内容。四种处理方式按推荐度排列:
| 方式 | 做法 | 适用 |
|---|---|---|
| 生成与手写分离 | 生成物放独立目录与独立文件,手写扩展放在扩展文件或子接口中 | 长期维护的项目 |
| 仅生成一次 | 首次生成后纳入手写范围,后续手工维护 | 表结构稳定、数量少 |
| 模板扩展 | 定制生成模板,使产物自带扩展点(如继承基类) | 有统一约定的组织 |
| 增量生成 | 生成器跳过已存在文件 | 表陆续新增的场景 |
推荐组合是"生成与手写分离加模板扩展":生成物只包含结构性内容且每次可安全覆盖,业务查询写在手写文件中,两者通过继承或组合关联。
2.3 契约驱动生成
由接口描述文件(契约)同时生成服务端接口骨架与客户端调用代码:
接口描述文件(唯一事实来源)
|-- 生成服务端接口与请求响应对象(服务提供方实现业务逻辑)
|-- 生成客户端 SDK(调用方直接使用,避免手写请求代码)
|-- 生成文档与测试用例骨架
价值在于消除"文档与实现不一致":契约变更会同时反映到两侧代码,编译期即可发现不匹配。约束是接口描述文件必须作为唯一来源受版本管理,且变更需按兼容性规则评审。
2.4 编译期生成与运行期生成的差别
| 维度 | 编译期生成 | 运行期生成 |
|---|---|---|
| 实现方式 | 注解处理器 | 反射与动态代理 |
| 产物 | 真实的源码或字节码 | 运行期代理对象 |
| 性能 | 无额外反射开销 | 存在反射与代理开销 |
| 排查 | 可查看生成的代码 | 只能看代理类名与栈 |
| IDE 支持 | 需要开启注解处理,否则误报 | 无需额外配置 |
| 适用 | 映射、静态元模型、不可变对象 | 需要运行期决定的场景 |
映射类工具的取舍依据即在此:编译期生成的映射代码在性能与可排查性上优于运行期反射,代价是构建与 IDE 需要正确配置注解处理。
2.5 生成物的归属
| 方式 | 做法 | 优点 | 代价 |
|---|---|---|---|
| 提交到版本库 | 生成物纳入版本管理 | 构建无需生成步骤,评审可见 | 仓库体积增大,差异噪音多,可能与源定义不同步 |
| 不提交 | 构建时生成,忽略生成目录 | 仓库干净,强制以定义为准 | 每次构建都需生成,IDE 需要标记生成目录 |
选择依据是生成是否稳定与生成成本:生成结果稳定且成本低时不提交;生成依赖外部元数据(数据库、契约文件)且结果需要评审时提交。
无论哪种方式,生成目录都需要从格式检查、覆盖率统计与静态分析中排除,并在目标中标记为生成来源,避免把生成物的风格问题计入质量指标。
三、实现
3.1 项目骨架生成
# 通过接口生成项目骨架(参数含义见接口文档)
curl -G https://start.spring.io/starter.zip \
-d type=maven-project \
-d language=java \
-d bootVersion=3.3.4 \
-d javaVersion=21 \
-d groupId=com.example \
-d artifactId=order-service \
-d name=order-service \
-d packageName=com.example.order \
-d dependencies=web,validation,data-jpa,mysql,actuator,lombok \
-o order-service.zip
unzip order-service.zip -d order-service
ls -R order-service | head -30
# 组织内统一约定的做法:以模板仓库为骨架,生成后替换占位符
git clone --depth 1 git@internal:platform/service-template.git order-service
cd order-service
find . -type f \( -name '*.java' -o -name '*.xml' -o -name '*.yml' \) \
-exec sed -i 's/__ARTIFACT__/order-service/g; s/__PACKAGE__/com.example.order/g' {} +
# 模板中已包含:分层结构、统一响应与异常、日志与链路标识、规范与质量配置文件、流水线配置
要点:模板的价值在于把组织约定一次性固化,避免新项目在规范、流水线与质量配置上各自摸索。
3.2 映射框架生成器
<!-- generatorConfig.xml:映射生成器配置要点 -->
<generatorConfiguration>
<context id="mysql" targetRuntime="MyBatis3">
<!-- 生成物目录分离:结构产物与手写内容不放在同一处 -->
<property name="javaModelGenerator"
value="target/generated-sources/mybatis/model"/>
<property name="javaClientGenerator"
value="target/generated-sources/mybatis/mapper"/>
<property name="sqlMapGenerator"
value="target/generated-sources/mybatis/xml"/>
<jdbcConnection driverClass="com.mysql.cj.jdbc.Driver"
connectionURL="jdbc:mysql://127.0.0.1:3306/app"
userId="${env.DB_USER}" password="${env.DB_PASSWORD}"/>
<!-- 表与字段的命名与类型映射:统一按团队约定覆盖,避免默认推导结果不一致 -->
<javaTypeResolver>
<property name="forceBigDecimals" value="true"/> <!-- 小数统一按精确类型 -->
</javaTypeResolver>
<table tableName="order" domainObjectName="OrderPO">
<generatedKey column="id" sqlStatement="MySql" identity="true"/>
<!-- 生成后只保留基础方法,复杂查询写在手写扩展文件中 -->
<property name="enableSelectByExample" value="false"/>
</table>
</context>
</generatorConfiguration>
# 执行生成(生成到 target 下,构建时清理,不进入版本库)
./mvnw mybatis-generator:generate -Dmybatis.generator.configurationFile=config/generatorConfig.xml
# 核对生成结果
find target/generated-sources/mybatis -name '*.java' | head -20
find target/generated-sources/mybatis -name '*.xml' | head -10
# 增量场景:只生成新增表(把新表名作为参数传入,避免重新覆盖既有表)
./mvnw mybatis-generator:generate -Dmybatis.generator.configurationFile=config/generatorConfig.xml \
-Dmybatis.generator.overwrite=false
// 手写内容放在扩展文件中:生成物只提供结构,业务查询独立维护
public interface OrderMapperExt extends OrderMapper {
List<OrderView> selectViewsByCondition(@Param("condition") OrderQuery query);
}
3.3 契约生成服务端与客户端
# openapi.yaml:接口描述文件作为唯一事实来源
openapi: 3.0.3
info:
title: Order Service API
version: 1.0.0
paths:
/orders/{id}:
get:
operationId: getOrder
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200':
description: 订单详情
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
components:
schemas:
Order:
type: object
required: [id, amount, currency]
properties:
id: { type: string }
amount: { type: string, description: 金额以字符串传输 }
currency: { type: string }
# 生成服务端接口骨架(接口由契约生成,实现由开发者填写)
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml -g spring \
-o target/generated-sources/openapi/server \
--additional-properties=interfaceOnly=true,useSpringBoot3=true
# 生成客户端 SDK(供调用方直接使用,避免手写请求代码)
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml -g java \
-o target/generated-sources/openapi/client \
--additional-properties=library=webclient,useSpringBoot3=true
# 生成结果与服务端实现的一致性由编译期保证:契约变更后实现类编译失败
./mvnw -q clean compile
要点:接口描述文件中金额以字符串声明,与金额精度要求一致,原因见 数值精度与金额处理。
3.4 生成目录的构建集成
<!-- 把生成目录加入构建的源码路径,并从质量检查范围中排除 -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-generated-sources</id>
<phase>generate-sources</phase>
<goals><goal>add-source</goal></goals>
<configuration>
<sources>
<source>target/generated-sources/openapi/server/src/main/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<configuration>
<!-- 生成物不参与格式与规范检查 -->
<excludes>**/generated-sources/**</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<configuration>
<!-- 生成物不参与覆盖率统计,避免虚高 -->
<excludes>
<exclude>**/generated/**</exclude>
<exclude>**/*PO.class</exclude>
</excludes>
</configuration>
</plugin>
# .gitignore:生成目录不提交(选择"不提交"方式时)
target/generated-sources/
src/main/generated/
# 核对生成目录是否被正确排除(质量报告中不应出现生成物路径)
./mvnw clean verify
grep -c 'generated' target/site/jacoco/index.html || echo "覆盖率报告未包含生成物"
3.5 避免覆盖手写代码的四种做法
| 做法 | 具体方式 | 适用 |
|---|---|---|
| 目录分离 | 生成物在生成目录,手写代码在源码目录,两者不重叠 | 通用做法 |
| 接口继承 | 生成的映射接口作为父接口,手写查询放在子接口中 | 数据访问层 |
| 模板预留扩展点 | 定制模板使产物继承指定的基类或包含扩展文件引用 | 有统一约定的组织 |
| 增量与跳过 | 生成器设置为不覆盖已存在文件 | 表陆续新增 |
# 生成前先确认目标目录,避免误覆盖源码目录
grep -rE 'value="src/main/java' config/generatorConfig.xml && echo "配置指向源码目录,需改为生成目录"
# 生成后核对差异:若出现非预期的源码目录变更,说明生成位置配置有误
git status --porcelain | grep -v '^?? target/' || echo "源码目录未受影响"
3.6 生成代码的评审原则
| 原则 | 说明 |
|---|---|
| 不修改生成物 | 修改会在下次生成时丢失,应从模板或契约侧修正 |
| 不评审生成物细节 | 评审对象是模板、配置与契约,而不是逐行生成的代码 |
| 关注生成物的一致性 | 命名与类型映射是否统一,是否与既有代码风格冲突 |
| 关注变更影响面 | 契约变更会影响调用方,需按兼容性规则评审 |
| 控制生成范围 | 生成内容越多,模板维护成本越高,只生成能完全推导的部分 |
四、总结
- 项目骨架、数据访问层与接口骨架是三处主要重复劳动,生成适合结构确定且能由元数据推导的内容,业务逻辑仍应手写。
- 脚手架解决新项目从零到可运行的问题,组织内以模板仓库方式使用时可以把规范、流水线与质量配置一次性固化。
- 数据库反向生成的产物包含数据对象、映射接口、映射文件与条件对象,核心冲突是重新生成会覆盖手写内容。
- 处理覆盖冲突的推荐组合是"生成与手写分离加模板扩展",使生成物可安全覆盖而业务查询独立维护。
- 契约驱动生成由同一份接口描述文件产出服务端骨架与客户端 SDK,消除文档与实现不一致,且契约变更在编译期即可暴露。
- 编译期生成在性能与可排查性上优于运行期反射,代价是构建与 IDE 必须正确配置注解处理。
- 生成物的归属按"生成是否稳定与成本高低"决定,但生成目录都应从格式检查、覆盖率统计与静态分析中排除。
- 避免覆盖手写代码的四类做法是目录分离、接口继承、模板预留扩展点与增量跳过,其中目录分离是通用前提。
- 生成代码的评审对象是模板、配置与契约,而不是逐行生成的产物;修改生成物的行为会在下次生成时丢失。
- 生成范围的扩大意味着模板维护成本上升,判断标准是"该内容能否被元数据完全推导"。