NSwag中获取HTTP响应头的最佳实践

在使用NSwag生成C#客户端代码时，开发者经常需要访问API响应中的HTTP头信息。本文将详细介绍如何在NSwag生成的客户端中正确处理和访问响应头，特别是针对二进制流响应的情况。

响应头在OpenAPI/Swagger中的定义

在定义API时，我们可以通过.WithOpenApi()方法明确指定响应中包含的HTTP头。例如，下面的代码定义了一个返回二进制流(application/octet-stream)的API，并在响应中添加了一个名为"X-MY-TOKEN"的自定义头：

.WithOpenApi(openApi =>
{
    openApi.Responses.Add(
        StatusCodes.Status200OK.ToString(),
        new OpenApiResponse
        {
            Content =
            {
                ["application/octet-stream"] = new OpenApiMediaType
                {
                    Schema = new OpenApiSchema
                    {
                        Type = "string",
                        Format = "binary",
                    },
                }
            },
            Headers =
            {
                ["X-MY-TOKEN"] = new OpenApiHeader
                {
                    Description = "The token to acknowledge the message.",
                    Required = true,
                    Schema = new OpenApiSchema
                    {
                        Type = "string",
                    },
                }
            }
        });

    return openApi;
});

这段配置会生成对应的Swagger/OpenAPI规范，其中明确包含了响应头的定义。

NSwag生成的客户端代码结构

NSwag针对二进制流响应会生成一个特殊的FileResponse类，这个类封装了HTTP响应的所有相关信息：

public partial class FileResponse : System.IDisposable
{
    public int StatusCode { get; private set; }
    public System.Collections.Generic.IReadOnlyDictionary<string, System.Collections.Generic.IEnumerable<string>> Headers { get; private set; }
    public System.IO.Stream Stream { get; private set; }
    // 其他成员...
}

关键点在于Headers属性，它是一个只读字典，包含了响应中的所有头信息。每个头可能对应多个值，因此字典的值类型是字符串的集合。

如何访问响应头

当调用返回FileResponse的API方法时，可以通过以下方式访问响应头：

var response = await client.MyApiMethodAsync();
if (response.Headers.TryGetValue("X-MY-TOKEN", out var tokenValues))
{
    var token = tokenValues.FirstOrDefault();
    // 使用token...
}

最佳实践建议

1. 头名称大小写处理：HTTP头名称通常是不区分大小写的，但在实际代码中最好使用与服务器端定义完全一致的名称。

2. 多值处理：某些头可能有多个值，代码中应该正确处理这种情况。

3. 资源释放：FileResponse实现了IDisposable接口，使用完毕后应该及时释放资源。

4. 错误处理：访问头信息前应该检查响应状态码，确保请求成功。

5. 类型转换：头值始终是字符串类型，需要时应该进行适当的类型转换。

总结

NSwag生成的客户端代码为开发者提供了完整的HTTP响应信息访问能力。通过FileResponse类的Headers属性，可以方便地获取API响应中定义的所有头信息。理解这一机制对于实现需要处理自定义头的API客户端非常重要。