@hey-api/openapi-ts 中处理数字风格属性名的技术挑战

在 TypeScript 生态系统中，@hey-api/openapi-ts 是一个用于生成 OpenAPI 客户端的重要工具。近期发现了一个有趣的边界情况：当 OpenAPI 规范中包含类似数字的属性名（如"-1"、"+1"）时，会导致 TypeScript 编译器内部断言失败。

问题本质

这个问题的根源在于 TypeScript 编译器对数字字面量的处理机制。当属性名以"-"或"+"开头时，工具内部尝试将其作为数字字面量处理，而 TypeScript 编译器要求负数字面量必须通过 createPrefixUnaryExpression 方式创建。

技术细节分析

在 TypeScript 的编译器实现中，createNumericLiteral 函数包含了一个严格的断言检查：

Debug.assert(text.charCodeAt(0) !== 45 /* minus */, 
  "Negative numbers should be created in combination with createPrefixUnaryExpression");

当遇到类似"-1"这样的字符串属性名时，工具错误地将其视为数字字面量而非字符串键名，从而触发了这个断言失败。

实际影响场景

这种情况特别容易出现在以下场景：

1. 处理 GitHub API 等使用特殊属性名的接口
2. 处理包含投票/评分系统的 API（如"+1"表示赞同，"-1"表示反对）
3. 处理包含数学表达式作为键名的数据结构

解决方案思路

要解决这个问题，可以考虑以下技术路线：

1. 键名转义处理：在生成 TypeScript 类型时，对特殊键名进行适当的转义或引号包裹
2. 类型生成策略调整：识别数字风格的字符串键名，确保它们被正确处理为字符串而非数字
3. 编译器 API 使用优化：在调用 TypeScript 编译器 API 时，明确区分真正的数字字面量和字符串键名

最佳实践建议

对于使用 @hey-api/openapi-ts 的开发者，如果遇到类似问题，可以：

1. 在 OpenAPI 规范设计阶段避免使用纯数字或数字风格的属性名
2. 如果必须使用特殊属性名，考虑添加前缀或后缀使其更明显地成为字符串键
3. 关注工具更新，确保使用了包含此问题修复的版本

这个案例展示了 TypeScript 类型系统与 OpenAPI 规范交互时可能遇到的微妙边界情况，也提醒我们在 API 设计时需要考虑工具链的兼容性问题。