如何为已搭建的.NET Core 6 API项目创建API客户端库

下面是几种在.NET生态中为你的API构建客户端库的常用方法，从手写实现到自动生成都有覆盖：

1. 手写强类型HttpClient客户端 #

这是最灵活的方式，适合需要完全控制请求逻辑的场景：

• 创建一个类库项目（推荐用.NET Standard 2.1或.NET 6，保证兼容性）
• 复制或复用API项目中的请求/响应模型类（比如Product、CreateProductRequest），确保两端模型结构一致
• 编写封装HttpClient的强类型客户端类：

using System.Net.Http.Json;

namespace MyApi.Client;

public class MyApiClient
{
    private readonly HttpClient _httpClient;

    // 通过构造函数注入HttpClient，便于配置和测试
    public MyApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        // 可在此设置API基础地址，也可在注册时配置
        _httpClient.BaseAddress = new Uri("https://your-api-domain/api/");
    }

    // GET请求示例：获取单个产品
    public async Task<Product?> GetProductAsync(int productId)
    {
        return await _httpClient.GetFromJsonAsync<Product>($"products/{productId}");
    }

    // POST请求示例：创建产品
    public async Task<Product> CreateProductAsync(CreateProductRequest request)
    {
        var response = await _httpClient.PostAsJsonAsync("products", request);
        // 确保请求成功，否则抛出异常
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Product>() ?? throw new InvalidOperationException("Failed to parse response");
    }
}

• 在消费端（比如Web App、Console App）注册客户端：

// Program.cs中
builder.Services.AddHttpClient<MyApiClient>(client =>
{
    client.BaseAddress = new Uri("https://your-api-domain/api/");
    // 添加默认请求头，比如Accept、Authorization
    client.DefaultRequestHeaders.Add("Accept", "application/json");
});

• 直接注入MyApiClient即可使用。

2. 用NSwag自动生成客户端 #

如果你的API已经启用Swagger（.NET Core 6默认模板已包含），可以自动生成客户端代码，减少重复劳动：

• 在客户端类库中安装NSwag.MSBuild包
• 编辑类库的.csproj文件，添加自动生成任务（替换为你的Swagger JSON地址）：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NSwag.MSBuild" Version="13.20.0" PrivateAssets="all" />
  </ItemGroup>

  <!-- 编译前自动生成客户端代码 -->
  <Target Name="GenerateApiClient" BeforeTargets="Build">
    <Exec Command="$(NSwagExe_Core31) swagger2csclient 
      /input:https://your-api-domain/swagger/v1/swagger.json 
      /output:Generated/MyAutoGeneratedApiClient.cs 
      /namespace:MyApi.Client 
      /generateClientInterfaces:true" />
  </Target>

</Project>

• 编译类库后，会自动生成包含所有API调用方法的客户端类和接口，直接使用即可。注册方式和手写客户端一致，注入生成的接口或类。

3. 使用Refit创建声明式客户端 #

Refit是一个基于HttpClient的声明式客户端库，通过特性标注接口来定义API调用，代码更简洁：

• 在客户端类库中安装Refit和Refit.HttpClientFactory包
• 定义标注Refit特性的接口：

using Refit;

namespace MyApi.Client;

public interface IMyApiClient
{
    [Get("/products/{productId}")]
    Task<Product?> GetProductAsync(int productId);

    [Post("/products")]
    Task<Product> CreateProductAsync([Body] CreateProductRequest request);

    [Delete("/products/{productId}")]
    Task DeleteProductAsync(int productId);
}

• 在消费端注册Refit客户端：

// Program.cs中
builder.Services.AddRefitClient<IMyApiClient>()
    .ConfigureHttpClient(client =>
    {
        client.BaseAddress = new Uri("https://your-api-domain/api/");
        client.DefaultRequestHeaders.Add("Accept", "application/json");
    });

• 注入IMyApiClient即可调用API，Refit会自动处理HttpClient的请求逻辑。

关键注意事项 #

• 模型复用：建议将请求/响应模型放在单独的共享类库中，API项目和客户端库都引用这个类库，避免重复定义导致的不一致。
• 错误处理：除了EnsureSuccessStatusCode()，建议自定义处理API返回的错误响应（比如包含错误码和消息的统一格式）。
• 授权：如果API需要认证，可在注册HttpClient时添加Authorization头，或者使用拦截器动态注入token。

内容的提问来源于stack exchange，提问作者sachinpawar013