Orval项目中FETCH客户端的自定义请求头覆盖问题解析

问题背景

在使用Orval项目生成的FETCH客户端时，开发人员发现了一个关于HTTP请求头处理的潜在问题。当开发者尝试通过options参数设置自定义请求头时，特别是在POST请求中，这些自定义头信息会被系统默认添加的Content-Type头覆盖，导致预期的自定义头信息丢失。

问题重现

该问题在以下场景中会出现：

1. 使用Orval生成的FETCH客户端
2. 通过options参数设置自定义请求头
3. 发起POST类型请求

技术分析

问题的根源在于请求头合并策略的实现方式。在原始实现中，当发起POST请求时，系统会强制设置Content-Type: application/json头，但没有正确处理与开发者自定义头的合并关系。

典型的错误实现如下：

return customFetch<Promise<createPetsResponse>>(getCreatePetsUrl(), {
  ...options,
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }, // 这会覆盖options中的headers
  body: JSON.stringify(createPetsBodyItem),
});

解决方案

正确的实现应该采用对象展开运算符(...)来合并默认头和自定义头：

return customFetch<Promise<createPetsResponse>>(getCreatePetsUrl(), {
  ...options,
  method: 'POST',
  headers: { 'Content-Type': 'application/json', ...options.headers }, // 正确合并
  body: JSON.stringify(createPetsBodyItem),
});

这种实现方式确保了：

1. 默认的Content-Type头会被设置
2. 开发者通过options传入的自定义头不会被覆盖
3. 如果开发者显式设置了Content-Type头，自定义值会覆盖默认值

临时解决方案

在官方修复发布前，开发者可以采用以下临时解决方案：

1. 使用自定义fetch客户端
2. 在发起请求前手动合并请求头
3. 避免在options中设置会被覆盖的头信息

版本更新

该问题已在Orval v7.1.1版本中得到修复。升级到该版本后，开发者可以正常使用options参数设置自定义请求头，而不用担心被默认头覆盖的问题。

最佳实践建议

1. 始终检查生成的API客户端代码中的头合并逻辑
2. 对于关键的头信息，考虑在自定义fetch客户端中统一处理
3. 在升级Orval版本后，验证自定义头是否按预期工作
4. 对于复杂的头信息需求，可以考虑使用请求拦截器统一处理

这个问题虽然看似简单，但反映了API客户端生成工具中一个常见的设计考量：如何在提供合理默认值的同时，不限制开发者的自定义需求。Orval项目团队通过这个修复，展示了他们对开发者友好性的重视。