5.13设置路径参数（模板/配置参数）

在 URL 路径中替换对象模板字符串。

HTTP 声明式请求通过 PathAttribute 特性和方法定义的非冻结类型参数来配置路径参数。相应的 HTTP 声明式提取器为 PathDeclarativeExtractor 类型，它负责解析这些 PathAttribute 特性及方法中定义的非冻结类型参数，并构建 HttpRequestBuilder 实例所需的路径参数配置。

123456789101112131415161718192021222324

// 在接口定义上应用，影响所有方法[Path("path1", "value1")][Path("path2", "value2")]public interface IHttpService : IHttpDeclarative{    // 在方法上应用    [Path("path3", "value3")]    [Get("https://furion.net/{path1}/{path2}/{path3}")]    Task<string> GetStringAsync();    // 方法上定义的非冻结类型参数默认会添加到路径参数中，可在 URL 地址中直接使用    [Get("https://furion.net/{path1}/{path2}/?id={id}&name={name}&address={address}&age={age}&name1={user.Name}&obj={obj}")]    Task<string> GetStringAsync(int id, string name, string[] address, int age, User user, object? obj);    [Get("https://furion.net/{name?}")] // "?" 结尾表示键不存在时替换为空字符串，可结合 [RemoveTrailingSlash] 特性使用    Task<string> GetStringAsync(string name);    [Get("https://furion.net/{**path}")] // "**" 开头表示不对路径分割符 "/" 转义    Task<string> GetStringAsync(string path);    // 冻结参数类型将被忽略    [Get("https://furion.net/")]    Task<string> GetStringAsync(CancellationToken cancellationToken);}

若存在重复的路径参数键，则后设置的键值会覆盖先前的设置。

模板路径语法

模板路径除了直接使用 {key} 外，还支持通过 . 访问对象的属性、嵌套属性，以及通过 [index] 访问集合中的元素。此外，对象类型的属性在未找到同名属性时，会自动尝试将其视为字典，并以路径标识符作为键进行取值（等同于 dict["key"]）。

• {key}：直接替换对应的值。
• {key.property}：访问 key 对象的 property 属性，或当 key 为字典时访问键为 "property" 的值。
• {key.property.nested}：多级属性/键访问。
• {list[0]}：访问 list 集合（数组、List<T> 等）中索引为 0 的元素。
• {user.names[1]}：先访问 user 对象的 names 属性，再取其索引 1 处的元素。
• {dic.key}：当 dic 是字典时（包括 Dictionary<string, T> 和 Hashtable 等），dic.key 会作为 dic["key"] 取值。
• {obj.dictProp.someKey[0].another}：混合使用点号和索引，逐级深入取值。

以上路径都支持在结尾添加 ? 表示值不存在时替换为空字符串，以及添加 ** 前缀表示不对路径分隔符 / 进行转义。

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

• 构造函数：

  • new(name, value)：作用于接口或方法，表示添加路径参数，键为参数 name 的值。

• 属性：

  • Name：路径参数键（string 类型）。
  • Value：路径参数的值（object 类型）。

配置参数

除了通过 {key} 模板语法设置路径参数外，框架还提供了配置参数，用于读取配置信息进行替换操作。配置参数使用 [[key]] 语法，例如：

12345

public interface IHttpService : IHttpDeclarative{    [Get("https://furion.net?id=[[id]]&name=[[name]]")]    Task<string> GetStringAsync();}

启用配置参数支持

要在 HttpRemote 服务中启用配置参数支持，请按照以下步骤进行配置：

123456

services.AddHttpRemote(builder => {})    .ConfigureOptions(options =>    {        // 设置用于替换 URL 地址中配置模板参数的提供源        options.Configuration = builder.Configuration;  // 若使用 Furion 框架可直接设置 App.Configuration    });

配置参数的使用

配置参数将从您的配置文件中读取并替换到 URL 中。例如，您的配置文件可能如下所示：

1234

{  "id": 1,  "name": "Furion"}

配置参数的键支持多种格式语法，以便更灵活地访问配置文件中的值：

• [[key]]：直接访问 key 对应的值。
• [[key:sub]]：访问 key 下的 sub 子项的值。
• [[key:sub:nest]]：访问 key 下的 sub 子项中的 nest 子项的值。
• 备用值查找：
  • [[notfound | bak]]：如果 notfound 不存在，则查找 bak。
  • [[notfound | bak | other]]：如果 notfound 和 bak 都不存在，则查找 other。
  • [[notfound | bak:sub | other:sub:nest]]：支持更深层次的备用查找。
• 默认值：
  • [[notfound || default]]：如果 notfound 不存在，则使用 default 作为值。
  • [[notfound | bak | other || 默认值]]：结合备用查找和默认值，确保总有值可用。