3.1创建实例与请求地址

HttpRequestBuilder 是一个构建器工具，专门用于在通过 HttpClient 发送请求时构建所需的 HttpRequestMessage 对象。可以说，HttpRequestBuilder 是整个 HTTP 远程请求模块的核心组件，负责在发送请求前准备所有必要的请求数据。如下图所示：

HttpRequestBuilder 请求构建器 ✨#

HttpRequestBuilder 是一个构建器工具，专门用于在通过 HttpClient 发送请求时构建所需的 HttpRequestMessage 对象。可以说，HttpRequestBuilder 是整个 HTTP 远程请求模块的核心组件，负责在发送请求前准备所有必要的请求数据。如下图所示：

查看高清架构图

创建构建器实例#

HttpRequestBuilder 类型的构造函数被设计为私有，因此无法直接使用 new 关键字进行实例化。不过，它提供了多个静态方法来方便地创建 HttpRequestBuilder 的实例。

1. 使用请求谓词静态方法（推荐）

HttpRequestBuilder 提供了多种基于 HTTP 请求方法（如 GET、POST 等）的静态方法，用于快速创建实例，这些方法支持重载，以适应不同的参数需求。

cs
var httpRequestBuilder = HttpRequestBuilder.Get("https://furion.net/"); // GET 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Put("https://furion.net/"); // PUT 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Post("https://furion.net/"); // POST 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Delete("https://furion.net/"); // DELETE 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Options("https://furion.net/"); // OPTIONS 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Trace("https://furion.net/"); // TRACE 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Patch("https://furion.net/"); // PATCH 请求，支持多个重载var httpRequestBuilder = HttpRequestBuilder.Query("https://furion.net/"); // QUERY 请求，支持多个重载

2. 使用 Create 静态方法

Create 方法允许通过更灵活的方式创建 HttpRequestBuilder 实例，支持直接指定请求方法和 URL，或使用自定义 HttpMethod。

cs
var httpRequestBuilder = HttpRequestBuilder.Create("GET", "https://furion.net/");var httpRequestBuilder = HttpRequestBuilder.Create(HttpMethod.Get, "https://furion.net/");// 自定义请求谓词，如 CONNECT 请求var httpRequestBuilder = HttpRequestBuilder.Create("Connect", "https://furion.net/");

3. 使用 Setup 静态属性

Setup 返回一个空白 HttpRequestBuilder 构建器实例，专门用于配置 HttpRequestBuilder 并作为 Action<HttpRequestBuilder> 委托传入谓词快捷方法（如 GetAsync、PostAsync 等）。它通过隐式转换自动将链式配置转换为委托，省去 builder => builder 的包裹。

cs
// 传统方式：builder => builderawait httpRemoteService.GetAsync("https://furion.net/", builder => builder.UseETag().Profiler());// ✅ 使用 Setup 替代await httpRemoteService.GetAsync("https://furion.net/", HttpRequestBuilder.Setup.UseETag().Profiler());

4. 使用 FromCurl 静态方法

通过传入原生的 cURL 命令字符串，FromCurl 可以一键生成配置好的 HttpRequestBuilder 实例，省去手动调用各项配置方法的繁琐步骤。

cs
// 解析最简 cURL 命令，自动识别 GET 方法var httpRequestBuilder = HttpRequestBuilder.FromCurl("curl http://example.com");// 解析带请求体（-d）的命令，自动推断为 POSTvar httpRequestBuilder = HttpRequestBuilder.FromCurl(    "curl -X POST https://api.example.com/data -H \"Content-Type: application/json\" -d '{\"name\":\"John\"}'");
  • curlCommand：完整的 cURL 命令字符串，必须以 curl 开头。
  • configure：可选委托，用于注册自定义的标志提取器。

5. 使用 FromJson 静态方法

通过传入 JSON 配置字符串，FromJson 可以一键生成配置好的 HttpRequestBuilder 实例，省去手动链式调用的繁琐步骤。

cs
// 解析最简 JSON 配置，自动识别 GET 方法var httpRequestBuilder = HttpRequestBuilder.FromJson("""    {        "url":"http://example.com",        "method":"GET"    }    """);// 解析带请求体的 JSON 配置，自动推断为 POSTvar httpRequestBuilder = HttpRequestBuilder.FromJson("""    {        "url": "https://api.example.com/data",        "method": "POST",        "headers": {            "Content-Type": "application/json"        },        "data": {            "name": "John"        }    }    """);
  • json：完整的 JSON 配置字符串，必须是 JSON 对象（以 { 开头且以 } 结尾），属性名不区分大小写且允许尾随逗号。
  • configure：可选委托，用于注册自定义的 JSON 字段提取器。

设置请求地址#

在 HttpRequestBuilder 类型提供的静态方法中，您可以配置请求的地址。以下展示了如何使用 HttpRequestBuilder 类型静态方法来定义不同的请求地址：

cs
// 使用完整 URL 地址HttpRequestBuilder.Get("https://furion.net/");// 使用相对地址（不含前导斜杠）HttpRequestBuilder.Get("api/get/user");// 使用相对地址（含前导斜杠）HttpRequestBuilder.Get("/api/get/user");// 请求地址为空字符串HttpRequestBuilder.Get(""); // 也可以使用 string.Empty 替代// 请求地址为 nullHttpRequestBuilder.Get(null);
  • 当提供的请求地址为完整 URL 时，它将直接作为最终的请求地址。
  • 若请求地址为相对地址（无论是否包含前导斜杠 /），框架将尝试将其与 HttpClient 配置的 BaseAddress 合并，以生成最终的请求地址（RFC 3986）。例如：
cs
services.AddHttpClient(string.Empty, client =>{    client.BaseAddress = new Uri("https://furion.net/");});

在上述配置中，若请求地址为 "api/get/user" 或 "/api/get/user"，则最终的请求地址将为 "https://furion.net/api/get/user"。

  • 若请求地址为空字符串或 null，则 HttpClient 配置的 BaseAddress 将直接作为最终的请求地址。这意味着，如果 BaseAddress 为 "https://furion.net/"，则最终请求地址也将是 "https://furion.net/"。

方法命名原则#

在设计 HttpRequestBuilder 对象的方法时，我们遵循了一套明确的命名规则，以确保方法的功能和行为直观易懂。具体来说，所有只能进行操作的方法均以 Set 或 Use 开头，而所有支持重复调用、进行叠加操作的方法则以 With 或 Add 开头。

  • Set 或 Use 开头的方法：这类方法用于设置某个属性或参数，若重复调用，则后一次调用会覆盖前一次的设置。例如，SetTraceIdentifier(traceId) 方法，在多次调用时，只有最后一次调用的 traceId 会生效。
  • With 或 Add 开头的方法：这类方法用于添加或修改某些内容，且支持重复调用。在重复调用时，它们不会覆盖之前的设置，而是采用叠加的方式。例如，WithHeader(key, value) 方法，在多次调用时，会保留之前的所有头部信息，并添加新的头部信息。

这样的命名原则使得 HttpRequestBuilder 对象的方法更加清晰易懂，便于开发者在使用时快速理解每个方法的功能和行为。

设置跟踪标识#

为请求指定一个唯一标识符，便于跟踪和调试。该标识符将被设置在 X-Trace-ID 请求标头中。

cs
HttpRequestBuilder.Get("https://furion.net/")    .SetTraceIdentifier("your-id");