OpenAPI-TS 项目中 Axios 客户端 Cookie 传递问题解析

在 OpenAPI-TS 项目中，开发者可能会遇到使用 Axios 客户端时 Cookie 无法正确传递的问题。本文将从技术角度深入分析这一现象的原因和解决方案。

问题现象

当开发者使用 OpenAPI-TS 生成基于 Axios 的客户端代码时，可能会发现生成的函数虽然包含了 cookies 参数，但实际请求中却没有携带相应的 Cookie 头信息。具体表现为：

1. 生成的客户端函数中正确包含了 cookies 配置
2. 请求发送时 Wireshark 抓包显示缺少 Cookie 头
3. 即使设置了 WITH_CREDENTIALS 参数为 true，问题依然存在

根本原因

经过分析，这个问题主要源于两个关键因素：

1. 客户端版本混淆：OpenAPI-TS 项目提供了两种 Axios 客户端实现：

   • 传统版（legacy/axios）
   • 新版（@hey-api/client-axios）

2. 配置优先级问题：当同时使用配置文件(--config)和命令行参数(--client)时，命令行参数会覆盖配置文件中的设置，导致意外使用了传统版客户端。

解决方案

要解决这个问题，开发者需要：

1. 明确使用新版客户端：在配置文件中指定：

   client: "@hey-api/client-axios"
   

2. 避免参数冲突：不要同时使用配置文件和--client参数，以免产生意外的覆盖行为。

3. 正确生成客户端：使用以下命令之一：

   npx openapi-ts
   

   或

   npx openapi-ts --config=your.config.ts
   

技术实现细节

新版 Axios 客户端在实现上做了以下改进：

1. 完整的 Cookie 支持：正确处理 cookies 参数，确保其被转换为请求头
2. 更好的类型安全：为 cookie 参数提供更精确的类型定义
3. 配置继承：正确处理 WITH_CREDENTIALS 等全局配置

最佳实践

为避免类似问题，建议开发者：

1. 始终优先使用配置文件而非命令行参数
2. 明确指定客户端版本而非依赖默认值
3. 定期更新客户端依赖以获取最新修复和改进

通过以上措施，可以确保 OpenAPI-TS 生成的 Axios 客户端能够正确处理 Cookie 等认证信息，为 API 调用提供完整的功能支持。