一、起源

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 生成代码的评审原则

原则 说明
不修改生成物 修改会在下次生成时丢失,应从模板或契约侧修正
不评审生成物细节 评审对象是模板、配置与契约,而不是逐行生成的代码
关注生成物的一致性 命名与类型映射是否统一,是否与既有代码风格冲突
关注变更影响面 契约变更会影响调用方,需按兼容性规则评审
控制生成范围 生成内容越多,模板维护成本越高,只生成能完全推导的部分

四、总结

  1. 项目骨架、数据访问层与接口骨架是三处主要重复劳动,生成适合结构确定且能由元数据推导的内容,业务逻辑仍应手写。
  2. 脚手架解决新项目从零到可运行的问题,组织内以模板仓库方式使用时可以把规范、流水线与质量配置一次性固化。
  3. 数据库反向生成的产物包含数据对象、映射接口、映射文件与条件对象,核心冲突是重新生成会覆盖手写内容。
  4. 处理覆盖冲突的推荐组合是"生成与手写分离加模板扩展",使生成物可安全覆盖而业务查询独立维护。
  5. 契约驱动生成由同一份接口描述文件产出服务端骨架与客户端 SDK,消除文档与实现不一致,且契约变更在编译期即可暴露。
  6. 编译期生成在性能与可排查性上优于运行期反射,代价是构建与 IDE 必须正确配置注解处理。
  7. 生成物的归属按"生成是否稳定与成本高低"决定,但生成目录都应从格式检查、覆盖率统计与静态分析中排除。
  8. 避免覆盖手写代码的四类做法是目录分离、接口继承、模板预留扩展点与增量跳过,其中目录分离是通用前提。
  9. 生成代码的评审对象是模板、配置与契约,而不是逐行生成的产物;修改生成物的行为会在下次生成时丢失。
  10. 生成范围的扩大意味着模板维护成本上升,判断标准是"该内容能否被元数据完全推导"。