5.14设置 Cookie

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

添加、修改或移除 Cookie。

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

1. 添加 Cookie

利用 CookieAttribute 特性，可以便捷地在接口、方法或参数上添加 Cookie 。

cs
// 在接口定义上应用，影响所有方法[Cookie("cookie1", "value1")][Cookie("cookie2", "value2")]public interface IHttpService : IHttpDeclarative{    // 在方法上应用    [Cookie("cookie3", "value3")]    [Cookie("cookie4", "value4")]    [Get("https://furion.net/")]    Task<string> GetStringAsync();    // 在参数上应用，支持 AliasAs 属性指定别名，且可多重指定    [Cookie("cookie3", "value3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie] string cookie4, [Cookie][Cookie(AliasAs = "cookie5")] int lastCookie);    // 在参数上可通过 Value 属性设定默认值，同样可为 age 参数设定，例如 int? age = 30    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie(Value = 30)] int? age);    // 支持 [AliasAs] 定义别名    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie][AliasAs("cookie5")] int lastCookie);    // 支持 format 格式化    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie(Format = "yyyyMMdd")] DateTime date);    // 冻结参数类型将被忽略    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie] CancellationToken cancellationToken);}

若存在重复的 Cookie 键，则后设置的键值会覆盖先前的设置。

2. 移除 Cookie

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

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

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

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

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

  • 构造函数：

    • new()：作用于参数时有效，表示添加 Cookie ，默认键为参数名。
    • new(name)：作用于方法或接口时，则表示移除指定 Cookie 操作；作用于参数时，表示添加 Cookie ，键为参数 name 的值。
    • new(name, value)：作用于接口、方法或参数，表示添加 Cookie ，键为参数 name 的值，优先级低于 AliasAs 属性。

  • 属性：

    • Name：Cookie 键（string 类型），优先级低于 AliasAs 属性。
    • Value：Cookie 的值（object 类型），当特性作用于参数时，表示默认值。
    • AliasAs：Cookie 键别名（string 类型），优先级高于 Name 属性。
    • Format：要使用的格式（string? 类型），仅当 Value 实现 IFormattable 时有效。