.NET6中HttpClient通过请求头传递API版本的问题求助

一、修复Accept头的客户端设置错误 #

你遇到的"The format of value 'application/json; api-version=1.0' is invalid."错误，是因为直接将api-version参数嵌入媒体类型字符串传入MediaTypeWithQualityHeaderValue构造函数时，该类会严格验证媒体格式，导致解析失败。正确的做法是单独添加版本参数：

HttpContent httpContent = new StringContent(JsonConvert.SerializeObject(bodyParams), Encoding.UTF8, "application/json");
var httpClient = _httpClient.CreateClient("MyAPI");

// 正确设置带api-version参数的Accept头
var mediaType = new MediaTypeWithQualityHeaderValue("application/json");
mediaType.Parameters.Add(new NameValueHeaderValue("api-version", "1.0"));
httpClient.DefaultRequestHeaders.Accept.Add(mediaType);

var response = await httpClient.PostAsync("Data/Send", httpContent);
// 后续代码...

不要直接用httpClient.DefaultRequestHeaders.Add("Accept", "application/json; api-version=1.0")，这种方式会绕过格式验证，可能引发兼容性问题，优先使用上述标准方式。

二、解决自定义头返回415错误的问题 #

415错误本质是媒体类型不支持，但结合你的场景，大概率是服务端未正确配置自定义头版本读取器，导致无法识别版本号，进而找不到匹配的路由/接口。

1. 服务端配置自定义头版本读取器 #

在Program.cs中配置API版本化时，添加HeaderApiVersionReader以支持自定义api-version头：

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 启用自定义头传递版本号
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
    // 如果需要同时支持Accept头和自定义头，使用复合读取器
    // options.ApiVersionReader = new CompositeApiVersionReader(
    //     new HeaderApiVersionReader("api-version"),
    //     new MediaTypeApiVersionReader("api-version")
    // );
});

2. 客户端自定义头设置（保持原代码即可） #

客户端添加自定义头的代码是正确的，确保没有重复添加或格式错误：

httpClient.DefaultRequestHeaders.Add("api-version", "1.0");

3. 额外排查点 #

• 确认服务端控制器已标记[ApiVersion]属性：

  [ApiController]
  [ApiVersion("1.0")]
  [Route("api/[controller]")] // 路由不要包含版本号
  public class DataController : ControllerBase
  {
      [HttpPost("Send")]
      public async Task<IActionResult> Send(DataDto bodyParams)
      {
          // 接口逻辑
      }
  }
  

• 检查请求的Content-Type是否与服务端接收的一致：客户端已设置为application/json，确保服务端接口参数绑定正确（比如使用[FromBody]）。

三、验证测试 #

完成上述配置后，分别测试两种方式：

• Accept头方式：客户端按标准方式设置带api-version参数的Accept头，服务端通过MediaTypeApiVersionReader解析版本
• 自定义头方式：客户端添加api-version:1.0头，服务端通过HeaderApiVersionReader解析版本

内容的提问来源于stack exchange，提问作者Scottish Smile