FluentHttpClient 技术文档

1. 安装指南

FluentHttpClient 是一个现代化的异步 HTTP 客户端，适用于 REST API。您可以通过 NuGet 包管理器进行安装：

Install-Package Pathoschild.Http.FluentClient

该客户端适用于多种平台，包括 Linux、Mac 和 Windows：

平台	最小版本
.NET	5.0
.NET Core	1.0
.NET Framework	4.5.2
.NET Standard	1.3
Mono	4.6
Unity	2018.1
Universal Windows Platform	10.0
Xamarin.Android	7.0
Xamarin.iOS	10.0
Xamarin.Mac	3.0

2. 项目使用说明

创建客户端并链式调用方法来设置请求/响应。以下是一个发送 GET 请求并将响应反序列化为自定义 Item 类型的示例：

Item item = await new FluentClient()
   .GetAsync("https://example.org/api/items/14")
   .As<Item>();

您还可以重用客户端来发送多个请求（通过内置的连接池提高性能），并在构造函数中设置基础 URL：

using var client = new FluentClient("https://example.org/api");

Item item = await client
   .GetAsync("items/14")
   .As<Item>();

客户端提供了 DELETE、GET、POST、PUT 和 PATCH 方法的支持。您还可以使用 SendAsync 方法来构建自定义 HTTP 请求。

3. 项目 API 使用文档

以下是 API 的使用方法：

URL 参数

您可以通过匿名对象向请求 URL 添加任意数量的参数：

await client
   .PostAsync("items/14")
   .WithArguments(new { page = 1, search = "some search text" });

或者使用字典：

await client
   .PostAsync("items/14")
   .WithArguments(new Dictionary<string, object> { /* ... */ });

或者单独添加：

await client
   .PostAsync("items/14")
   .WithArgument("page", 1)
   .WithArgument("search", "some search text");

请求体

您可以直接在 POST 或 PUT 请求中添加模型请求体：

await client.PostAsync("search", new SearchOptions(…));

或者添加到任何请求中：

await client
   .GetAsync("search")
   .WithBody(new SearchOptions(…));

或者以各种格式提供：

格式	示例
序列化模型	WithBody(new ExampleModel())
表单 URL 编码	WithBody(p => p.FormUrlEncoded(values))
文件上传	WithBody(p => p.FileUpload(files))
HttpContent	WithBody(httpContent)

头部信息

您可以为请求添加任意数量的头部信息：

await client
   .PostAsync("items/14")
   .WithHeader("User-Agent", "Some Bot/1.0.0")
   .WithHeader("Content-Type", "application/json");

或者使用方法来设置常见的头部信息，如 WithAuthentication、WithBasicAuthentication、WithBearerAuthentication 和 SetUserAgent。

读取响应

您可以通过等待 As* 方法来解析响应：

await client
   .GetAsync("items")
   .AsArray<Item>();

以下是可以使用的格式：

类型	方法
Item	As<Item>()
Item[]	AsArray<Item>()
byte[]	AsByteArray()
string	AsString()
Stream	AsStream()
JToken	AsRawJson()
JObject	AsRawJsonObject()
JArray	AsRawJsonArray()

AsRawJson 方法也可以返回 dynamic 类型，以避免需要模型类：

dynamic item = await client
   .GetAsync("items/14")
   .AsRawJsonObject();

string author = item.Author.Name;

如果您不需要内容，只需等待请求即可：

await client.PostAsync("items", new Item(…));

读取响应信息

在解析主体之前，您还可以读取 HTTP 响应信息：

IResponse response = await client.GetAsync("items");
if (response.IsSuccessStatusCode || response.Status == HttpStatusCode.Found)
   return response.AsArray<Item>();

错误处理

默认情况下，如果服务器返回错误代码，客户端将抛出 ApiException：

try
{
   await client.Get("items");
}
catch(ApiException ex)
{
   string responseText = await ex.Response.AsString();
   throw new Exception($"The API responded with HTTP {ex.Response.Status}: {responseText}");
}

如果您不想这样，可以...

• 为单个请求禁用：

  IResponse response = await client
     .GetAsync("items")
     .WithOptions(ignoreHttpErrors: true);
  

• 为所有请求禁用：

  client.SetOptions(ignoreHttpErrors: true);
  

• 使用自定义错误过滤器。

4. 项目安装方式

请参考上文“安装指南”部分，使用 NuGet 包管理器进行安装。

Install-Package Pathoschild.Http.FluentClient