3.1.3 注释驱动代码生成

在实际开发中，很多重复性代码可以通过注释（Annotation） + 处理器自动生成，从而减少手写样板代码、降低出错率，并保持项目代码风格统一。这一节介绍两种最常见的注释驱动代码生成方式，并给出可以直接使用的示例。

1. 场景与原理

典型应用场景包括：

为实体类自动生成 getter/setter、构造方法、toString 等
根据接口定义自动生成 API 文档和客户端 SDK
根据数据库表结构注解自动生成实体类和 Mapper 文件

基本原理是：在源码中标记注释 → 编译期或工具链扫描注释 → 按模板生成目标代码。这一过程不会修改你的手写代码，新增文件通常放在独立的生成目录中，便于维护。

2. 实用示例一：Lombok 自动生成 Java Bean 代码

问题：一个数据类需要手写几十行 getter/setter、构造器、equals 和 hashCode，修改字段时容易漏改。

解决：使用 Lombok 提供的注释，编译时自动生成这些方法。

步骤：

在项目中引入 Lombok（已在 Maven/Gradle 中添加依赖）。
在实体类上添加 Lombok 注释：

import lombok.Data;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Long id;
    private String name;
    private String email;
}

效果：编译后，User 类自动拥有：

所有字段的 getter/setter
无参构造方法和全参构造方法
toString、equals 和 hashCode 方法

你完全不需要维护这些机械代码，字段变动时也无需额外修改。

3. 实用示例二：OpenAPI 注释生成客户端代码

问题：写了一个 REST 接口，需要为前端或第三方提供调用代码，手工编写 API 文档和 SDK 既耗时又容易与实现不一致。

解决：在 Controller 上使用 Swagger/OpenAPI 注释，然后利用生成工具自动产出客户端代码（如 TypeScript、Java SDK）。

步骤：

在 Controller 中添加 Springdoc-OpenAPI 注释（Spring Boot 项目）：

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @Operation(summary = "根据ID查询用户")
    @GetMapping("/{id}")
    public User getUserById(
            @Parameter(description = "用户ID") @PathVariable Long id) {
        // 实际查询逻辑
        return userService.findById(id);
    }
}

在 pom.xml 中配置生成插件（例如 openapi-generator-maven-plugin），指定输入为 /v3/api-docs，输出目标语言为 typescript-axios。
运行 mvn generate-sources，即可在指定目录下获得可直接调用的 TypeScript API 客户端代码。

效果：接口注释成为单一事实来源，任何接口变更只需重新生成即可得到更新的客户端代码，无需手动同步。

4. 实用建议

注释要保持准确和完整：生成器依赖注释中的类型、描述等信息，写注释时尽量提供具体的说明和示例，避免生成代码过于模糊。
生成代码不要手动修改：将生成的文件放在独立目录（如 target/generated-sources），并在版本控制中忽略它们，确保任何时候都可以重新生成。
结合项目需求选择合适的工具：
Java 项目常用 Lombok、MapStruct（对象转换代码生成）
数据库相关可用 MyBatis-Plus 的代码生成器或 JPA 注解
API 驱动项目推荐 OpenAPI Generator 或 gRPC 的 protoc 插件

注释驱动代码生成的核心价值在于用一份准确的声明，换掉大量重复且易出错的实现。当你发现团队在反复写同样结构的代码时，就是引入这类自动化机制的最佳时机。