OpenAPI Generator生成无null的toString方法

本文详细阐述了如何利用OpenAPI Generator的自定义模板功能，生成排除null字段的toString()方法。通过配置Gradle插件并指定自定义模板目录，开发者可以修改pojo.mustache文件，从而在模型类生成时实现对toString()方法的精细控制，确保输出更简洁、无冗余的类对象表示。

在基于OpenAPI规范生成代码时，我们经常需要对生成的模型类进行定制，其中一个常见需求是修改默认的toString()方法，使其在输出对象信息时忽略值为null的字段。这有助于提升日志的可读性，并减少不必要的输出。OpenAPI Generator提供了强大的模板机制，允许开发者通过自定义Mustache模板来实现这一目标。

1. 理解问题与解决方案核心

默认情况下，OpenAPI Generator生成的模型类中的toString()方法会包含所有字段，即使它们的值为null。为了避免这种情况，我们需要干预生成过程，修改生成toString()方法的模板逻辑。核心思路是：

1. 配置OpenAPI Generator使用自定义模板目录。
2. 在自定义模板目录中提供一个修改过的pojo.mustache文件，该文件负责生成Java POJO类，包括其toString()方法。
3. 在pojo.mustache中，加入条件逻辑，仅当字段不为null时才将其包含在toString()的输出中。

2. 配置OpenAPI Generator Gradle插件

首先，确保你的项目中已集成OpenAPI Generator Gradle插件，并配置其指向你的自定义模板目录。

// build.gradle 文件示例
plugins {
    // 引入OpenAPI Generator Gradle插件
    id "org.openapitools.openapigenerator" version "7.10.0" 
}

repositories {
    mavenCentral()
}

dependencies {
    // 声明插件依赖，确保插件能够正常工作
    implementation 'org.openapitools:openapi-generator-gradle-plugin:7.10.0'
}

openApiGenerate {
    // 指定生成器名称，例如 "spring"
    generatorName = "spring" 
    // 指定OpenAPI规范文件路径
    inputSpec = "$rootDir/path/to/your/openapi.yaml" 
    // 指定生成代码的输出目录
    outputDir = "${buildDir}/generated-src/main/java" 
    // 指定模型类的包名
    modelPackage = "com.example.model" 
    // 关闭模型测试生成
    generateModelTests = false 
    // 全局属性配置，例如关闭模型文档和API生成，只生成模型
    globalProperties = [
            modelDocs: "false",
            apis: "false",
            models: ""
    ]
    // 配置选项，例如选择Spring Boot库和Java 8日期库
    configOptions = [
            library: "spring-boot",
            dateLibrary: "java8"
    ]

    // 关键配置：指定自定义Mustache模板的目录
    // 确保该目录存在，例如：项目根目录/src/main/resources/templates
    templateDir = "$rootDir/src/main/resources/templates" 
}

在上述配置中，templateDir = "$rootDir/src/main/resources/templates"是核心，它告诉OpenAPI Generator在生成代码时，优先从src/main/resources/templates目录加载模板文件。

3. 创建与修改自定义Mustache模板

接下来，你需要创建指定的模板目录（例如src/main/resources/templates），并在其中放置你希望自定义的Mustache模板文件。对于修改POJO类的toString()方法，你需要关注pojo.mustache文件。

3.1 获取原始模板

要开始修改，最安全和推荐的做法是获取OpenAPI Generator当前版本对应的原始pojo.mustache文件。你可以从OpenAPI Generator的GitHub仓库中找到它们。例如，对于Java生成器，模板通常位于： https://github.com/OpenAPITools/openapi-generator/tree/v7.10.0/modules/openapi-generator/src/main/resources/Java

下载（或复制）pojo.mustache文件到你的src/main/resources/templates目录下。

3.2 修改pojo.mustache文件

打开你复制到自定义目录的pojo.mustache文件。你需要找到负责生成toString()方法的代码块。通常，它会包含类似以下结构的Mustache逻辑：

  @Override
  public String toString() {
    StringBuilder sb = new StringBuilder();
    sb.append("class {{classname}} {\n");
    {{#vars}}
    sb.append("    {{name}}: ").append(toIndentedString({{name}})).append("\n");
    {{/vars}}
    sb.append("}");
    return sb.toString();
  }

为了实现排除null字段，你需要修改{{#vars}}循环内部的逻辑，加入条件判断。Mustache模板支持简单的条件渲染，例如使用{{#variable}} ... {{/variable}}来判断variable是否存在或非空（对于Java对象通常意味着非null）。

以下是一个概念性的修改示例，具体实现可能需要根据pojo.mustache的实际内容和OpenAPI Generator版本进行调整：

  @Override
  public String toString() {
    StringBuilder sb = new StringBuilder();
    sb.append("class {{classname}} {\n");
    {{#vars}}
    {{^isContainer}} {{! 非容器类型字段，例如String, Integer等 }}
    {{#getter}} {{! 确保有getter方法，才能安全调用 }}
    if (get{{nameInPascalCase}}() != null) {
        sb.append("    {{name}}: ").append(toIndentedString(get{{nameInPascalCase}}())).append("\n");
    }
    {{/getter}}
    {{/isContainer}}
    {{#isContainer}} {{! 容器类型字段，例如List, Map等 }}
    {{#getter}}
    if (get{{nameInPascalCase}}() != null && !get{{nameInPascalCase}}().isEmpty()) { // 对于集合类型，可以进一步判断是否为空
        sb.append("    {{name}}: ").append(toIndentedString(get{{nameInPascalCase}}())).append("\n");
    }
    {{/getter}}
    {{/isContainer}}
    {{/vars}}
    sb.append("}");
    return sb.toString();
  }

注意事项：

• {{#vars}}：遍历模型中的所有字段。
• {{^isContainer}} 和 {{#isContainer}}：这些是OpenAPI Generator模板提供的辅助变量，用于判断字段是否为集合类型。你可以根据实际pojo.mustache中提供的变量进行调整。
• {{#getter}}：确保字段有对应的getter方法，以便在toString()中安全地访问其值。
• get{{nameInPascalCase}}()：这是假设的getter方法调用方式，实际模板中可能会使用{{name}}直接访问字段，或者通过this.{{name}}。你需要根据原始模板的实现来决定如何获取字段值。
• toIndentedString()：这是一个辅助方法，通常在生成的类中提供，用于格式化输出。

4. 重新生成代码

完成模板修改后，运行你的Gradle生成任务：

./gradlew clean generateRbsModel

OpenAPI Generator将使用你的自定义pojo.mustache文件来生成模型类，其中toString()方法将根据你定义的逻辑，只包含非null的字段。

5. 总结与最佳实践

通过自定义Mustache模板，OpenAPI Generator提供了极大的灵活性，远不止修改toString()方法。你可以定制整个代码生成过程，以适应项目的特定需求和编码规范。

• 版本兼容性： 不同的OpenAPI Generator版本可能会有不同的模板结构和可用的辅助变量。在升级OpenAPI Generator版本时，务必检查并更新你的自定义模板。
• 模板依赖： 某些模板可能会依赖其他模板或内部辅助函数。在修改一个模板时，了解其上下文和依赖关系至关重要。
• 逐步修改： 建议从原始模板开始，进行小范围的修改，并逐步验证，以避免引入难以调试的问题。
• 测试验证： 生成代码后，编写单元测试来验证toString()方法的行为是否符合预期，特别是对于包含null值的对象。

通过以上步骤，你将能够成功配置OpenAPI Generator，生成满足特定需求的、排除null字段的toString()方法，从而提升代码质量和可维护性。