5.12设置请求标头

创建于 2026 年 8 月 17 日约 3 分钟读完

添加、修改或移除请求标头。

HTTP 声明式请求通过 HeaderAttribute 特性来设置或移除请求标头。相应的 HTTP 声明式提取器实现为 HeaderDeclarativeExtractor 类型，该类型负责解析 HeaderAttribute 特性并构建 HttpRequestBuilder 实例所需的请求标头配置。

1. 添加请求标头

利用 HeaderAttribute 特性，可以便捷地在接口、方法或参数上添加请求标头。

cs
// 在接口定义上应用，影响所有方法[Header("header1", "value1")][Header("header2", "value2")]public interface IHttpService : IHttpDeclarative{    // 在方法上应用    [Header("header3", "value3")]    [Header("header4", "value4")]    [Get("https://furion.net/")]    Task<string> GetStringAsync();    // 在参数上应用，支持 AliasAs 属性指定别名，且可多重指定    [Header("header3", "value3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header] string header4, [Header][Header(AliasAs = "header5")] int lastHeader);    // 在参数上可通过 Value 属性设定默认值，同样可为 age 参数设定，例如 int? age = 30    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header(Value = 30)] int? age);    // 支持 [AliasAs] 定义别名    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header][AliasAs("header5")] int lastHeader);    // 支持使用冒号（:）配置    [Get("https://furion.net/")]    [Header("User-Agent: HttpAgent")]    Task<string> GetStringAsync();    // 支持 format 格式化    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header(Format = "yyyyMMdd")] DateTime date);    // 冻结参数类型将被忽略    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header] CancellationToken cancellationToken);}

若存在重复的请求标头，它们将被合并，并用逗号加空格（, ）分隔多个值。通过设置 Replace = true 属性，可以覆盖先前的请求标头设置。

2. 移除请求标头

HeaderAttribute 特性中，仅指定请求标头键而不赋值，即表示移除该标头。在接口或方法上应用有效。

cs
[Header("header1", "value1")] // 添加 header1 标头[Header("header2")]           // 标记 header2 为待移除public interface IHttpService : IHttpDeclarative{    [Header("header2", "value2")] // 添加 header2 标头    [Header("header3", "value3")] // 添加 header3 标头    [Header("header3")]           // 标记 header3 为待移除    [Get("https://furion.net/")]    Task<string> GetStringAsync();}

在发送 HTTP 请求之前，将移除配置中指定的待移除请求标头集合。也就是说，移除操作会在所有设置操作调用之后执行。

在上述示例中，尽管 GetStringAsync 方法尝试通过 [Header] 特性添加 header2 和 header3 标头，但由于随后分别有 [Header("header2")] 和 [Header("header3")] 特性仅指定了请求标头键而未赋值，因此这两个键在最终构建请求标头时会被移除。只有 header1 标头会保留在请求标头中。

HeaderAttribute 包含以下构造函数和属性：

  • 构造函数：

    • new()：作用于参数时有效，表示添加请求标头，默认键为参数名。
    • new(name)：作用于方法或接口时，若配置字符串不含冒号（:），则表示移除指定请求标头；若含冒号，则以第一个冒号为分隔，左侧为键，右侧为值。作用于参数时，表示添加请求标头，键为参数 name 的值。
    • new(name, value)：作用于接口、方法或参数，表示添加请求标头，键为参数 name 的值，优先级低于 AliasAs 属性。

  • 属性：

    • Name：请求标头键（string 类型），优先级低于 AliasAs 属性。
    • Value：请求标头的值（object 类型），当特性作用于参数时，表示默认值。
    • AliasAs：请求标头键别名（string 类型），优先级高于 Name 属性。
    • Escape：是否转义请求标头值（bool 类型），默认值为 false（不转义）。
    • Replace：是否替换已存在的请求标头（bool 类型），默认值为 false（追加）。
    • Format：要使用的格式（string? 类型），仅当 Value 实现 IFormattable 时有效。