• Ｃ＃ 使用 REST API HTTP 客户端生成器

    本文内容

    1. 使用 AutoClientAttribute
    2. 使用谓词属性定义 HTTP 方法
    3. HTTP 有效负载
    4. HTTP 头

    显示另外 2 个

     备注

    此 API 是实验性的。 它可能会在后续版本的库中更改，并且无法保证向后兼容性。

    HttpClient是使用 REST API 的好方法，但存在挑战。 其中一个挑战是需要写入以使用 API 的样板代码量。 本文介绍了如何使用Microsoft.Extensions.Http.AutoClient NuGet 包修饰接口并生成 HTTP 客户端依赖项。 AutoClient 的基础源生成器生成接口的实现，以及用于将其注册到依赖项注入容器中的扩展方法。 此外，AutoClient 会为每个 HTTP 请求生成遥测数据，该请求随Microsoft.Extensions.Http.Telemetry一起发送。

    使用 AutoClientAttribute

    AutoClientAttribute负责触发 AutoClient 生成器以发出修饰接口的相应实现。 它接受要从IHttpClientFactory中检索的HttpClient的httpClientName。 请考虑以下接口定义：

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(httpClientName: "GeneratedClient")]
    4. public interface IProductClient
    5. {
    6. }

     提示

    接口名称必须以I开头。 该名称去除了前导I，并用作遥测RequestMetadata的RequestMetadata.DependencyName。 如果名称以Api或Client结尾，则排除这些名称。 例如，如果接口命名为IProductClient，则依赖项名称为Product。

    要替代计算的依赖项名称，请使用AutoClientAttribute的customDependencyName参数。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(
    4.     httpClientName: "GeneratedClient",
    5.     customDependencyName: "Widget Service")]
    6. public interface IWidgetClient
    7. {
    8. }

     备注

    上述两个代码示例都会导致编译警告，因为接口未定义任何 HTTP 方法。 该警告由 AutoClient 生成器发出，提醒发出实现是无用的。

    使用谓词属性定义 HTTP 方法

    空接口不是有用的抽象。 要定义 HTTP 方法，必须使用 HTTP 谓词属性。 每个 HTTP 方法都会返回Task，其中T是以下类型之一：

    返回类型说明
    Task响应的原始内容以字符串形式返回。
    Task当T是任何可序列化的类型时，响应内容从 JSON 反序列化并返回。
    Task如果需要HttpResponseMessage本身（如从HttpClient.SendAsync中返回），请使用此类型。

    当 HTTP 响应的内容类型未application/json且方法的返回类型不是Task时，会引发异常。

    HTTP 谓词属性

    使用以下属性之一定义 HTTP 方法：

    每个属性都需要path参数，该参数路由到基础 REST API，并且它应相对于HttpClient.BaseAddress。 path不能包含查询字符串参数，而是使用QueryAttribute。 从遥测的角度来看，path用作RequestMetadata.RequestRoute。

    使用任何谓词属性修饰的 HTTP 方法必须具有CancellationToken参数，并且它应是定义的最后一个参数。 CancellationToken参数用于取消 HTTP 请求。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient("GeneratedClient")]
    4. public interface IUserClient
    5. {
    6.     [Get("/api/users")]
    7.     public Task GetUsersAsync(
    8.         CancellationToken cancellationToken = default);
    9. }

    前面的代码：

    • 使用GetAttribute定义 HTTP 方法。
    • path 为 /api/users。
    • 该方法返回Task，其中T是User[]。
    • 此方法接受可选的CancellationToken参数，该参数在未提供参数时分配给default。

    路由参数

    URL 可能包含路由参数，例如"/api/users/{userId}"。 要定义路由参数，方法还必须接受名称相同的参数（本例中为userId）：

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IRouteParameterUserClient), "User Service")]
    4. public interface IRouteParameterUserClient
    5. {
    6.     [Get("/api/users/{userId}")]
    7.     public Task GetUserAsync(
    8.         string userId,
    9.         CancellationToken cancellationToken = default);
    10. }

    在上述代码中：

    • GetUserAsync方法具有名为userId的路由参数。
    • userId参数用于请求的path，替换{userId}占位符。

    遥测请求名称

    方法名称用作RequestMetadata.RequestName。 如果方法名称包含Async后缀，会将其删除。 例如，名为GetUsersAsync的方法计算为"GetUsers"。

    要替代名称，请使用 HTTP 谓词属性的每个属性的RequestName属性。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IRequestNameUserClient), "User Service")]
    4. public interface IRequestNameUserClient
    5. {
    6.     [Get("/api/users", RequestName = "CustomRequestName")]
    7.     public Task<List<User>> GetUsersAsync(
    8.         CancellationToken cancellationToken = default);
    9. }

    HTTP 有效负载

    要使用请求发送 HTTP 有效负载，请在方法的参数上使用BodyAttribute。 如果不向其传递任何参数，它会将内容类型视为 JSON，在发送之前对参数进行序列化。 否则，请定义显式BodyContentType并在BodyAttribute内使用它。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IPayloadUserClient), "User Service")]
    4. public interface IPayloadUserClient
    5. {
    6.     [Post("/api/users")]
    7.     public Task<User> CreateUserAsync(
    8.         // The content type is JSON
    9.         // The parameter is serialized before sending
    10.         [Body] User user,
    11.         CancellationToken cancellationToken = default);
    12.  
    13.     [Put("/api/users/{userId}/displayName")]
    14.     public Task<User> UpdateDisplayNameAsync(
    15.         string userId,
    16.         // The content type is text/plain
    17.         // The parameter is sent as is
    18.         [Body(BodyContentType.TextPlain)] string displayName,
    19.         CancellationToken cancellationToken = default);
    20. }

    HTTP 头

    可通过两种方式使用 HTTP 请求发送标头。 其中一个方式最适合永不更改值的标头（静态标头）。 另一种方式是基于方法的参数更改的标头。

    静态标头

    要定义静态标头，请在接口定义上使用StaticHeaderAttribute。 将标头名称和值传递给其构造函数。

    还可以在方法中一起使用多个StaticHeaderAttribute。 在方法上使用StaticHeader属性时，该 HTTP 标头仅针对该方法发送，而接口级StaticHeader属性针对所有方法发送。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IStaticHeaderUserClient), "User Service")]
    4. [StaticHeader("X-ForAllRequests", "GlobalHeaderValue")]
    5. public interface IStaticHeaderUserClient
    6. {
    7.     [Get("/api/users")]
    8.     [StaticHeader("X-ForJustThisRequest", "RequestHeaderValue")]
    9.     public Task> GetUsersAsync(
    10.         CancellationToken cancellationToken = default);
    11. }

    参数标头

    使用HeaderAttribute定义基于参数的标头，可以从方法的属性接收标头的值。 将标头名称传递给其构造函数。

    该参数可以是任何类型。 当标头类型不是string时，对参数的值调用.ToString()方法。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IParameterHeaderUserClient), "User Service")]
    4. public interface IParameterHeaderUserClient
    5. {
    6.     [Get("/api/users")]
    7.     public Task> GetUsersAsync(
    8.         [Header("X-MyHeader")] string myHeader,
    9.         CancellationToken cancellationToken = default);
    10. }

    查询参数

    使用方法参数上的QueryAttribute定义查询参数。 所有类型都有效，并且查询值依赖于.ToString()方法，以在不是string类型时获取参数的值。

    QueryAttribute.Key从参数的名称分配。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(IQueryUserClient))]
    4. public interface IQueryUserClient
    5. {
    6.     [Get("/api/users")]
    7.     public Task<List<User>> GetUsersAsync(
    8.         [Query] string search,
    9.         CancellationToken cancellationToken = default);
    10. }

    GetUsersAsync方法生成 HTTP 请求，其 URL 格式为/api/users?search={search}。 此格式用作遥测的RequestMetadata.RequestRoute。

    如果需要更改查询键，可以调用key基于参数的构造函数，QueryAttribute(String)。

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(ICustomQueryUserClient))]
    4. public interface ICustomQueryUserClient
    5. {
    6.     [Get("/api/users")]
    7.     public Task<List<User>> GetUsersAsync(
    8.         [Query("customQueryKey")] string search,
    9.         CancellationToken cancellationToken = default);
    10. }

    GetUsersAsync方法生成 HTTP 请求（URL 格式类似于/api/users?customQueryKey={customQueryKey}），因为密钥名称被替代为customQueryKey。

    依赖项注入挂钩

    除了接口的实现外，生成扩展方法以在依赖项注入容器中注册客户端。 生成的扩展方法的名称与接口名称相同，将前导I替换为Add。

    例如，请考虑以下接口定义：

    C#复制

    1. using Microsoft.Extensions.Http.AutoClient;
    2.  
    3. [AutoClient(nameof(ICompleteUserClient))]
    4. [StaticHeader("User-Agent", "dotnet-auto-client sample")]
    5. public interface ICompleteUserClient
    6. {
    7.     [Get("users")]
    8.     public Task GetAllUsersAsync(
    9.         CancellationToken cancellationToken = default);
    10.  
    11.     [Get("users")]
    12.     public Task GetUserByNameAsync(
    13.         [Query] string name,
    14.         CancellationToken cancellationToken = default);
    15.  
    16.     [Get("users/{userId}")]
    17.     public Task GetUserByIdAsync(
    18.         int userId,
    19.         CancellationToken cancellationToken = default);
    20.  
    21.     [Post("users")]
    22.     [StaticHeader("X-CustomHeader", "custom-value")]
    23.     public Task CreateUserAsync(
    24.         [Body(BodyContentType.ApplicationJson)] User user,
    25.         CancellationToken cancellationToken = default);
    26.  
    27.     [Delete("user/{userId}")]
    28.     public Task DeleteUserAsync(
    29.         int userId,
    30.         [Header("If-None-Match")] string eTag,
    31.         CancellationToken cancellationToken = default);
    32. }

    虽然生成器发出ICompleteUserClient接口的实现，但它还会在IServiceCollection上生成AddCompleteUserClient扩展方法。 请考虑以下示例Program.cs代码：

    C#复制

    1. using System.Text.Json;
    2. using Microsoft.Extensions.DependencyInjection;
    3. using Microsoft.Extensions.Hosting;
    4.  
    5. HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(null);
    6.  
    7. // Add a named HTTP client "ICompleteUserClient".
    8. builder.Services.AddHttpClient(nameof(ICompleteUserClient), options =>
    9. {
    10.     options.BaseAddress = new("https://jsonplaceholder.typicode.com");
    11. });
    12.  
    13. builder.Services.AddCompleteUserClient(options =>
    14. {
    15.     options.JsonSerializerOptions = new(JsonSerializerDefaults.Web)
    16.     {
    17.         PropertyNameCaseInsensitive = true
    18.     };
    19. });
    20.  
    21. builder.Services.AddSingleton<UserService>();
    22.  
    23. using IHost host = builder.Build();
    24.  
    25. UserService service = host.Services.GetRequiredService<UserService>();
    26.  
    27. await service.ProcessUsersAsync();
    28.  
    29. host.Run();

    在前面的示例代码中：

    可以将客户端注入服务构造函数以使用客户端：

    C#复制

    1. using System.Net.Http.Json;
    2.  
    3. internal sealed class UserService(ICompleteUserClient userClient)
    4. {
    5.     public async Task ProcessUsersAsync()
    6.     {
    7.         // Create a new user.
    8.         HttpResponseMessage response = await userClient.CreateUserAsync(new(
    9.             Id: null, /* Is populated upon successful HTTP POST when creating user */
    10.             Name: "Ada Lovelace",
    11.             Username: "ada.lovelace",
    12.             Email: "1st-computer-programmer@example.com",
    13.             Address: new(
    14.                 Street: "123 Engineer Lane",
    15.                 Suite: null,
    16.                 City: "London",
    17.                 ZipCode: "EC1A",
    18.                 Geo: new(
    19.                     Lat: 51.509865m, Lng: -0.118092m)),
    20.             Phone: "+1234567890",
    21.             Website: "www.example.com",
    22.             Company: new(
    23.                 Name: "Babbage, LLC.",
    24.                 CatchPhrase: "works on my machine",
    25.                 Bs: "This is the future")));
    26.  
    27.         User? createdUser = await response.Content.ReadFromJsonAsync<User>();
    28.  
    29.         Console.WriteLine($"""
    30.             CreateUserAsync: Created user
    31.                '{createdUser}'...
    33.             """);
    34.  
    35.         // Get user by id.
    36.         User receivedUser = await userClient.GetUserByIdAsync(7);
    37.         Console.WriteLine($"""
    38.             GetUserAsync: Received user
    39.                 '{receivedUser}'...
    41.             """);
    42.  
    43.         // Get list of all users.
    44.         User[] allUsers = await userClient.GetAllUsersAsync();
    45.         Console.WriteLine($"""
    46.             GetUsersAsync: Received a total of {allUsers.Length} users...
    47.             """);
    48.     }
    49. }

    有关详细信息，请参阅.NET 依赖项注入。

  • 相关阅读:
    UE4 C++ ActionRoguelike开发记录
    SQLZOO 7 More JOIN
    [Hive] CTE 通用表达式 WITH关键字
    【服务治理】服务熔断、服务降级、服务限流、流量削峰、错峰
    小程序毕设作品之微信二手交易小程序毕业设计成品（3）后台功能
    html与css知识点
    设计模式-适配器-笔记
    满级大牛 HuaWei 首次出这份 598 页【网络协议全彩手册】，建议大家收藏
    10款最赞的ROS机器人操作系统课程+为何ROS不是必须的
    通过这些API，开发者可以在自己的应用程序中嵌入电商功能，为用户提供便捷的购物体验
  • 原文地址：https://blog.csdn.net/lvmingzhou/article/details/134162860