WebApiClient 教程

WebApiClient 教程

1. 项目介绍

WebApiClient 是一个基于 .NET 的高性能、高可扩展性的 HTTP 客户端库。它旨在提供一种声明式的 API 使用方式，相比 Refit 具备更好的功能、性能和可伸缩性。其特色包括：

• 语义化声明: 开发仅需通过 C# 接口声明 API。
• 多样化序列化: 支持 JSON、XML、Form 等序列化方式及自定义序列化。
• 代码裁剪与 AOT: 支持.NET 8的代码裁剪和AOT编译。
• 面向切面编程: 拦截器、过滤器、日志、重试、缓存等功能。
• 源码生成工具: 可以从 OpenApi 文档自动生成接口代码。

2. 项目快速启动

安装 NuGet 包

在你的 .csproj 文件中添加以下依赖项：

<ItemGroup>
  <PackageReference Include="WebApiClientCore" Version="最新版本号" />
</ItemGroup>

然后运行 dotnet restore 来安装包。

创建 API 客户端接口

using WebApiClient;

public interface IWeatherService : IWebApiClient
{
    [Get("/weatherforecast")]
    Task<List<WeatherForecast>> GetWeatherForecasts();
}

使用 API 客户端

var weatherService = new HttpClientFactory().CreateApi<IWeatherService>("http://localhost:5000");
var forecasts = await weatherService.GetWeatherForecasts();

3. 应用案例和最佳实践

• 错误处理: 使用 Task<T> 或 Task<HttpResponseMessage> 返回类型处理错误状态码。
• 配置拦截器: 添加全局或特定接口的拦截器来统一处理如日志记录、异常捕获等。
• API 版本控制: 通过接口命名规则（如 Iv1UserService）或查询字符串参数来实现。

4. 典型生态项目

• OAuth2 集成: 利用 WebApiClientCore.Extensions.OAuths 扩展包进行身份验证和授权。
• Json-RPC 客户端: 使用 WebApiClientCore.Extensions.JsonRpc 实现 Json-Rpc 协议的调用。
• 源码生成工具: WebApiClientCore.SourceGenerator 允许从 OpenApi 规范生成接口代码，简化接口声明工作。

---

此教程为快速入门 WebApiClient 的基本步骤，更多详细信息和高级特性请参考项目官方文档：WebApiClient GitHub Wiki。