NSwag中实现动态请求头的技术方案解析

前言

在使用NSwag生成API客户端时，开发者经常会遇到需要为每个请求动态添加自定义请求头的情况。本文将深入探讨这一常见需求的解决方案，并分析不同实现方式的优缺点。

问题背景

在微服务架构中，服务间调用经常需要传递特定的上下文信息，这些信息通常以HTTP头部的形式传递。例如：

• 认证令牌
• 跟踪ID
• 租户信息
• 语言偏好等

当使用NSwag生成的客户端时，这些头部信息往往需要根据每个请求的上下文动态生成，而不是简单地使用固定值。

解决方案比较

1. 使用OpenAPI规范定义头部参数

推荐程度：★★★★★

最规范的解决方案是在OpenAPI/Swagger规范中明确定义这些头部参数。这种方式有以下优势：

• 类型安全：可以明确定义参数的数据类型
• 文档完整：生成的API文档会包含这些头部参数说明
• 代码清晰：调用方必须显式提供这些参数

实现方法是在OpenAPI规范中添加header参数定义，例如：

parameters:
  - name: X-Correlation-Id
    in: header
    description: 请求跟踪ID
    required: true
    schema:
      type: string

2. 扩展生成的客户端类

推荐程度：★★★★

NSwag生成的客户端类默认是partial类，可以通过扩展部分类的方式添加自定义逻辑：

public partial class MyApiClient
{
    partial void PrepareRequest(HttpClient client, HttpRequestMessage request, string url)
    {
        request.Headers.Add("X-Custom-Header", GetDynamicValue());
    }
}

优点：

• 集中管理头部逻辑
• 不影响生成的代码

缺点：

• 难以获取请求级别的上下文信息
• 在单例模式下存在线程安全问题

3. 使用作用域(Scoped)生命周期

推荐程度：★★★

在依赖注入容器中，将客户端注册为Scoped生命周期而非Singleton：

services.AddScoped<IMyApiClient, MyApiClient>();

这样每个HTTP请求都会获得独立的客户端实例，可以在构造函数中注入Scoped服务来获取请求级上下文。

适用场景：

• 需要访问HTTP上下文等请求级服务
• 头部信息与用户会话相关

4. 自定义请求消息工厂

推荐程度：★★★

通过UseHttpRequestMessageCreationMethod选项自定义请求创建逻辑：

client.UseHttpRequestMessageCreationMethod = true;

然后在基类中实现CreateHttpRequestMessageAsync方法，可以完全控制请求创建过程。

最佳实践建议

1. 优先使用OpenAPI规范定义：对于已知的、稳定的头部参数，应该在API契约中明确定义。

2. 合理选择生命周期：

   • 无状态客户端：Singleton
   • 需要请求上下文：Scoped

3. 线程安全考虑：任何共享状态都需要考虑线程安全，特别是在Singleton模式下。

4. 上下文传递：对于需要从控制器传递到客户端的上下文信息，可以考虑：

   • 使用AsyncLocal
   • 依赖注入上下文对象
   • 显式参数传递

总结

NSwag提供了多种灵活的方式来处理动态请求头，开发者应根据具体场景选择最适合的方案。对于API契约明确的头部参数，优先使用OpenAPI规范定义；对于需要动态计算的头部值，可以通过扩展客户端类或使用适当生命周期的方式实现。理解这些技术方案的适用场景和限制条件，将帮助开发者构建更健壮的微服务通信层。