OpenAPI Generator 中 operationId 过滤器的空格处理问题解析

在 OpenAPI Generator 项目中，operationId 过滤器是一个常用的功能，它允许开发者通过配置来筛选特定的 API 操作。然而，在实际使用过程中，我们发现当配置文件中使用换行符来美化格式时，会导致意外的空格被包含在过滤条件中，从而影响最终的代码生成结果。

问题背景

在 Maven 插件配置中，开发者通常会使用 <openapiNormalizer> 标签来设置过滤器规则。为了提高配置文件的可读性，开发者可能会将多个 operationId 用换行符分隔，例如：

<openapiNormalizer>
    FILTER=operationId: addPet|
    getPetById
</openapiNormalizer>

按照直觉理解，这样的配置应该会生成两个过滤条件："addPet" 和 "getPetById"。然而实际上，第二个条件会包含换行符和缩进字符，导致过滤条件变为 "addPet" 和 "\n\t\t\t\t\t\t\tgetPetById"。

技术分析

这个问题的根源在于 OpenAPI Generator 在处理过滤器字符串时，直接使用了 split("[|]") 方法进行分割，而没有对分割后的字符串进行任何修剪（trim）操作。这种处理方式会导致以下问题：

1. 当使用换行符分隔多个 operationId 时，后续行的缩进空格会被保留
2. 这些额外的空白字符会被包含在最终的过滤条件中
3. 由于 operationId 通常不包含前导空格，这会导致过滤条件无法匹配实际的 API 操作

解决方案

针对这个问题，我们可以通过以下方式改进字符串处理逻辑：

1. 使用 Java 8 的 Stream API 来处理分割后的字符串数组
2. 对每个分割后的字符串应用 trim() 方法去除前后空格
3. 过滤掉可能存在的空字符串
4. 最终收集为一个 Set 集合

改进后的代码示例如下：

operationIdFilters = Arrays.stream(filterStrs[1].split("[|]"))
    .filter(Objects::nonNull)
    .map(String::trim)
    .collect(Collectors.toSet());

这种处理方式具有以下优势：

1. 自动去除字符串前后的空白字符
2. 能够处理各种格式的输入（单行、多行、混合格式）
3. 提高了代码的健壮性和可维护性
4. 保持了原有功能的同时增加了对用户友好的格式支持

最佳实践建议

为了避免类似问题，开发者在配置 OpenAPI Generator 时可以考虑以下建议：

1. 如果使用单行配置，确保没有多余的空格：

   <openapiNormalizer>FILTER=operationId:addPet|getPetById</openapiNormalizer>
   

2. 如果确实需要使用多行配置以提高可读性，可以在行末使用管道符：

   <openapiNormalizer>
       FILTER=operationId:addPet|
       getPetById
   </openapiNormalizer>
   

3. 在复杂的配置场景下，考虑使用属性文件或外部配置文件来管理这些规则

总结

OpenAPI Generator 中的 operationId 过滤器空格处理问题虽然看似简单，但它反映了配置解析过程中对用户友好性的重要性。通过改进字符串处理逻辑，我们不仅解决了当前的问题，还为未来的扩展性打下了基础。这种改进使得开发者能够更灵活地组织配置文件，而不必担心格式问题影响最终的代码生成结果。