OpenAPI-TS 项目中 DTO 命名大小写转换问题分析

在 OpenAPI-TS 项目中，当开发者使用 Kotlin 编写控制器方法时，如果方法名中包含 DTO 字样（如 getFooBarDTOById 或 getFooBarDTOs），生成的 TypeScript 类型和服务客户端函数会出现大小写不一致的问题。

问题现象

在 Kotlin 控制器中，开发者可能这样定义方法：

@GetMapping("/foo")
fun getFooBarDTOById(@PathVariable id: Long) = FooBarDTO(id)

@GetMapping("/bar")
fun getFooBarDTOs() = listOf(FooBarDTO(1), FooBarDTO(2))

但生成的 TypeScript 代码会出现以下异常：

1. 当 DTO 后接 "ById" 时，会转换为 "Dto"
2. 当 DTO 后接 "s" 复数形式时，会转换为 "DtO"

技术背景

这个问题涉及到 OpenAPI 规范转换过程中的命名约定处理。在 API 开发中，数据传输对象（DTO）是一个常见概念，通常开发者会保持命名一致性。OpenAPI-TS 作为类型生成工具，需要正确处理各种命名约定转换。

问题根源

经过分析，这个问题可能源于以下几个方面：

1. 驼峰命名转换规则：在将方法名转换为 TypeScript 命名时，可能应用了过于简单的驼峰转换规则，没有考虑到特殊缩写（如DTO）的情况。

2. 复数处理逻辑：当遇到复数形式时，转换逻辑可能错误地将"DTOs"拆分为"Dt"和"Os"，而不是保持"DTO"的完整性。

3. 后缀处理：对于"ById"这样的常见后缀，转换规则可能强制应用了小写字母开头的约定，导致"DTO"被错误地转换为"Dto"。

解决方案建议

要解决这个问题，可以考虑以下改进方向：

1. 特殊缩写识别：在命名转换过程中，应该识别并保留常见的缩写形式，如DTO、API等。

2. 上下文感知转换：根据命名上下文（如是否在方法名中、是否作为类型名等）应用不同的转换规则。

3. 配置选项：提供配置选项，允许开发者指定哪些缩写应该保持原样。

最佳实践

在等待官方修复的同时，开发者可以采取以下临时解决方案：

1. 统一使用小写"dto"命名，避免大小写问题。

2. 在OpenAPI规范生成阶段，手动调整operationId，确保其符合预期。

3. 使用后处理脚本，对生成的TypeScript代码进行修正。

总结

命名约定的一致性对于API开发至关重要，特别是在跨语言环境中。OpenAPI-TS项目需要完善其命名转换逻辑，以正确处理各种缩写和特殊情况。这个问题虽然看起来是小问题，但对于注重代码风格一致性的团队来说，可能会造成不小的困扰。