OpenAPI-TS 项目：如何仅生成类型定义文件

在 OpenAPI-TS 项目中，开发者有时可能只需要生成类型定义文件（types.gen.ts），而不需要完整的 SDK 生成文件（sdk.gen.ts）。这种情况通常出现在开发者希望使用自定义的 API 请求实现，而不是项目默认生成的 SDK 时。

为什么需要仅生成类型定义

许多开发者选择仅生成类型定义文件的主要原因包括：

1. 框架集成需求：当开发者使用的框架已经内置了完善的请求处理类（如 Axios 封装），且这些封装包含了拦截器、Token 刷新等业务逻辑时，直接使用框架的请求类可能比使用生成的 SDK 更符合项目架构。

2. 自定义请求逻辑：某些项目可能有特殊的请求处理需求，如特定的错误处理机制、请求重试策略等，这些可能无法通过生成的 SDK 直接实现。

3. 减少代码体积：如果项目只需要类型定义来保证类型安全，而不需要额外的 SDK 功能，仅生成类型文件可以减少最终打包体积。

实现方法

在 OpenAPI-TS 项目中，要实现仅生成类型定义文件非常简单：

1. 在配置文件中，只保留 @hey-api/typescript 插件
2. 移除其他可能生成 SDK 的插件配置

这种配置方式确保了项目只会生成类型定义文件，而不会生成完整的 SDK 实现。

自定义客户端实现

对于希望使用自定义请求实现的开发者，OpenAPI-TS 项目提供了创建自定义客户端的能力。开发者可以：

1. 基于现有框架的请求类（如 Vue-Vben-Admin 中的请求封装）创建适配器
2. 实现与 OpenAPI 规范兼容的请求接口
3. 利用生成的类型定义确保 API 调用的类型安全

这种方式既保留了框架原生请求类的优势（如拦截器、Token 刷新等），又能享受 OpenAPI 规范带来的类型安全好处。

最佳实践建议

1. 评估需求：在决定是否仅生成类型定义前，应评估项目对 SDK 功能的需求程度
2. 类型安全优先：即使使用自定义请求实现，也应确保利用生成的类型定义来保证代码质量
3. 考虑扩展性：如果未来可能需要切换回完整 SDK，应保持代码结构的一致性

通过合理配置 OpenAPI-TS 项目，开发者可以灵活地选择最适合自己项目的代码生成策略，在类型安全和实现灵活性之间取得平衡。