OpenAPI-TS 项目中 void 类型与 undefined 类型的正确使用

在 OpenAPI-TS 项目生成的 services.gen.ts 文件中，开发者可能会遇到一个常见的 TypeScript 类型检查问题：ESLint 规则 @typescript-eslint/no-invalid-void-type 报错。这个问题涉及到 API 响应类型定义的最佳实践。

问题背景

当 OpenAPI 规范定义的接口没有返回体时，OpenAPI-TS 生成器默认会使用 void 类型来表示无返回值的响应。这在 TypeScript 中虽然语法上是合法的，但根据 TypeScript ESLint 的严格规则，void 类型应该仅用作函数返回类型或泛型类型参数。

技术分析

void 和 undefined 在 TypeScript 中都表示"无值"的概念，但它们的语义和使用场景有所不同：

1. void 表示函数没有返回值
2. undefined 表示一个变量确实具有 undefined 值

在 API 响应上下文中，当端点确实不返回任何内容时，使用 undefined 类型更为准确，因为它明确表示了"没有返回值"这一事实，而 void 更适合描述函数不返回任何值的情况。

解决方案

OpenAPI-TS 项目的最新实验性解析器已经解决了这个问题。在生成的服务代码中，无返回值的 API 端点现在会正确地使用 undefined 类型而非 void 类型。

例如，原来的代码：

post<void, unknown, ThrowOnError>

现在会生成：

post<undefined, unknown, ThrowOnError>

升级建议

对于遇到此问题的开发者：

1. 可以考虑升级到包含实验性解析器的最新版本
2. 在升级前，建议在测试环境中验证新解析器的行为
3. 如果暂时无法升级，可以通过 ESLint 配置暂时禁用该规则，但这只是临时解决方案

最佳实践

在定义 OpenAPI 规范时，如果端点确实不返回任何内容，建议：

1. 在规范中明确声明响应体为空
2. 避免使用 void 作为响应类型
3. 考虑使用 204 No Content 状态码来表示无返回值的响应

OpenAPI-TS 项目的这一改进使得生成的代码更加符合 TypeScript 的类型系统最佳实践，同时也提高了与严格 ESLint 配置的兼容性。