本文探讨为何不建议通过修改 mustache 模板来移除 openapi generator 生成的 java 模型类中的 getter/setter 等访问方法，而是推荐利用 vendor extensions（如 x-class-extra-annotation）安全集成 lombok，兼顾标准兼容性与开发效率。
OpenAPI Generator 的核心设计目标是生成开箱即用、语义完备、生态兼容的模型类。默认生成的 POJO 包含符合 Java Bean 规范的字段、getter/setter、构造器、equals()/hashCode()/toString()，以及对 Jackson 序列化、Bean Validation（如 @NotNull）、JAXB 等主流框架的原生支持。这些能力并非冗余，而是构建可维护 API 客户端与服务端契约的关键基础。
直接删除访问方法（例如通过覆盖 pojo.mustache 模板移除 {{#hasGetter}}...{{/hasGetter}} 块），虽技术上可行，但会引发一系列隐性成本：
- ❌ 破坏序列化兼容性：Jackson 默认依赖标准 getter/setter；若仅靠 @Data 注解替代，需额外配置 @JsonAutoDetect 或全局 ObjectMapper 设置，否则反序列化可能失败；
- ❌ 丢失校验上下文：@Valid 嵌套校验、分组校验（groups = {Create.class}）等高级特性依赖标准 Bean 结构，Lombok 生成的方法无法自动继承 OpenAPI 中定义的 x-validation 或 nullable: false 元信息；
- ❌ Vendor extension 失效：OpenAPI Generator 支持的 x-field-extra-annotation、x-class-extra-annotation 等扩展字段，其注入逻辑深度耦合于标准模板流程——一旦模板被大幅裁剪，这些注解将无法正确渲染到字段或类上。
✅ 正确实践：保留标准生成逻辑 + 声明式注入 Lombok
推荐使用官方支持的 vendor extensions，在 OpenAPI YAML/Swagger 文件中为模型添加 Lombok 注解，无需修改模板：
components:
schemas:
User:
x-class-extra-annotation: "@lombok.Data @lombok.Builder"
x-field-extra-annotation:
id: "@lombok.Generated"
email: "@javax.validation.constraints.Email"
properties:
id:
type: integer
format: int64
email:
type: string配合 Maven 插件配置启用扩展支持：
org.openapitools openapi-generator-maven-plugin 7.8.0 java true @lombok.NoArgsConstructor
⚠️ 注意事项：additionalModelTypeAnnotations 是全局注入，适用于所有模型类；而 x-class-extra-annotation 可实现按 Schema 精准控制，更灵活；若需 @Builder 的细粒度配置（如 builderClassName），应通过 x-class-extra-annotation 字符串拼接实现，例如 "@lombok.Builder(builderClassName = \"UserBuilder\")"；务必在项目中引入 Lombok 依赖及编译插件（如 lombok-maven-plugin 或 IDE 对应插件），确保注解处理器生效；避免混合使用 @Data 与手动 getter/setter —— 这会导致编译错误或行为不一致。
总结而言，OpenAPI Generator 不是“代码片段生成器”，而是契约驱动的全栈建模工具。与其投入大量精力定制模板以适配 Lombok，不如善用其原生扩展机制，在保持标准兼容的前提下，优雅叠加现代 Java 工具链能力。这既降低了维护复杂度，也保障了团队协作中 API 模型的一致性与可演进性。
