5.10设置路径片段

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

添加或移除 URL 路径片段。

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

1. 添加路径片段

利用 PathSegmentAttribute 特性，可以便捷地在接口、方法或参数上添加路径片段。

cs
// 在接口定义上应用，影响所有方法[PathSegment("segment1")][PathSegment("segment2")]public interface IHttpService : IHttpDeclarative{    // 在方法上应用    [PathSegment("segment3")]    [PathSegment("segment4")]    [Get("https://furion.net/")]    Task<string> GetStringAsync();    // 在参数上应用，支持多重指定    [PathSegment("segment3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([PathSegment] string segment3, [QueryParam][QueryParam] int lastSegment);    // 在参数上可通过 Segment 属性设定默认值，同样可为 segment 参数设定，例如 string? segment = "default"    [Get("https://furion.net/")]    Task<string> GetStringAsync([PathSegment(Segment = "default")] string? segment);    // 冻结参数类型将被忽略    [Get("https://furion.net/")]    Task<string> GetStringAsync([PathSegment] CancellationToken cancellationToken);}

若存在重复的路径片段，它们将在后续追加中重复出现（如：/docs/docs/users/docs/）。

2. 移除路径片段

PathSegmentAttribute 特性中，设置 Remove = true，即表示移除该路径片段。在接口、方法或参数上应用有效。

cs
[PathSegment("segment1")] // 添加 segment1 路径片段[PathSegment("segment2", Remove = true)]           // 标记 segment2 为待移除public interface IHttpService : IHttpDeclarative{    [PathSegment("segment2")] // 添加 segment2 路径片段    [PathSegment("segment3")] // 添加 segment3 路径片段    [PathSegment("segment3", Remove = true)]           // 标记 segment3 为待移除    [Get("https://furion.net/")]    Task<string> GetStringAsync([PathSegment(Remove = true)] string seg);   // 动态根据 seg 值标记为待移除}

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

在上述示例中，尽管 GetStringAsync 方法尝试通过 [PathSegment] 特性添加 segment2 和 segment3 路径片段，但由于随后分别有 [PathSegment("segment2", Remove = true)] 和 [PathSegment("segment3", Remove = true)] 特性仅指定了 Remove = true 属性，因此这两个键在最终构建请求 URL 时会被移除。只有 segment1 路径片段会保留在请求 URL 中。

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

  • 构造函数：

    • new()：作用于参数时有效，表示添加路径片段，路径片段为参数值。
    • new(segment)：作用于方法或接口时，则表示添加指定路径片段操作；作用于参数且参数值为 null 时，表示添加路径片段，路径片段为参数 segment 的值。

  • 属性：

    • Segment：路径片段（string 类型），特性作用于参数且参数值为 null 时，可用作默认值。
    • Remove：是否标记为待删除（bool 类型），默认值为 false（追加）。