OpenAPI-TS 项目中实验性解析器对 PascalCase 配置的兼容性问题分析

问题背景

在 OpenAPI-TS 项目中，开发者经常需要将 OpenAPI/Swagger 规范转换为 TypeScript 类型定义。一个常见的需求是控制生成类型的命名风格，特别是当后端 API 规范使用 camelCase 而前端项目倾向于 PascalCase 时。

配置与预期行为

项目提供了 @hey-api/types 插件，通过 style: 'PascalCase' 配置可以将生成的类型名称转换为帕斯卡命名法。例如：

// 原始规范中的类型
commandMsg: {...}

// 期望生成的类型
export type CommandMsg = {...}

这种转换在标准解析器下工作正常，满足了前端项目对类型命名风格的要求。

实验性解析器的问题

当开发者启用实验性解析器功能时（通过 experimentalParser: true 配置），发现 PascalCase 的命名转换不再生效。生成的类型名称会保持与 OpenAPI 规范中完全一致的命名风格，忽略 style 配置。

技术影响分析

这个问题会影响以下场景：

1. 项目代码风格一致性：前后端命名规范不统一时，前端代码会出现混合命名风格
2. 类型引用体验：开发者需要记忆两种不同的命名风格
3. 代码可读性：混合命名风格降低代码可读性和维护性

解决方案建议

对于遇到此问题的开发者，可以采取以下临时解决方案：

1. 暂时禁用实验性解析器功能
2. 手动添加类型别名转换层
3. 等待官方修复后升级版本

最佳实践

在使用 OpenAPI-TS 项目时，建议：

1. 明确项目命名规范要求
2. 在启用实验性功能前进行全面测试
3. 关注项目更新日志，及时获取修复信息

这个问题反映了实验性功能与核心功能之间的兼容性挑战，也提醒我们在采用新技术时需要平衡创新与稳定性。