你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

RESTful Web API 实现的最佳做法

本文介绍实现、部署和操作 RESTful Web API 的最佳做法。 它侧重于请求处理、性能、可靠性、发布和监视。 有关资源建模和 API 设计的指南,请参阅 Web API 设计。

体系结构指南适用于实现语言和框架。 C# 示例演示了 ASP.NET Core控制器。

处理请求

在实现处理请求的代码时,请考虑以下几点。

保留 HTTP 方法语义并实现幂等性

使用 GET 返回资源数据,使用 HEAD 返回没有正文的响应标头。 请勿使用任一方法创建、更新或删除资源。

GET、HEAD、PUT 和 DELETE 必须是幂等的,因此重复相同的请求具有与执行一次相同的预期效果。 例如,DELETE 会更改资源状态,但重复执行 DELETE 不会删除更多资源。 第一个 DELETE 请求可能会返回 204(无内容),而后续请求返回 404(找不到)。

POST 和 PATCH 本质上不是幂等的。 将属性设置为值的 PATCH 操作可以是幂等的,但递增计数器的操作不是幂等的。 记录哪些状态更改操作客户端可以安全地重试。 如果你支持重试非自然幂等的操作,请实现并记录服务如何防止重复副作用。 有关方法语义,请参阅 HTTP 请求方法。

注意

有关实现指南,请参阅 幂等使用者模式。 在实践中,首先确定某个操作是否自然是幂等的。 如果不是这样,请通过跟踪已处理的消息 ID 并主动或被动地处理重复项来实现人工幂等性。

验证请求数据并控制字段访问

定义仅公开 API 协定中的字段的请求和响应模型。 将这些模型映射到存储的数据,而不是将请求主体直接绑定到数据库实体或返回每个存储的属性。 通过提交其他字段来防止调用方更改受保护的属性,并省略它们无权读取的属性。 数据传输对象(DTO)是强制实施此边界的一种方法。 有关详细信息,请参阅“防止在 ASP.NET Core中过度发布”。

保存更改之前,请验证必填字段、类型、范围和业务规则。 如果支持字段选择,请在投影响应之前根据允许列表和调用方的权限验证请求的字段。 应用记录的限制以筛选和排序。 有关相应的合同选项,请参阅实现分页和筛选。

限制创建资源的 POST 操作的副作用

当 POST 请求创建资源时,请将其影响限制为该资源和直接相关的资源。 例如,创建订单也可能更新库存并生成计费信息。 它不应修改不相关的信息。

避免实现琐碎的 POST、PUT 和 DELETE 操作

避免根据聊天操作来设计 API。 每个请求都有协议、网络和计算开销。 例如,运行 100 个较小的请求而不是一个更大的批处理请求会导致客户端、网络和资源服务器上的开销增加。 对于需要批量操作的工作负荷,请考虑使用有界批处理请求,而不是多个单独请求。

  • 对集合的 GET 请求可以同时检索多个资源。
  • POST 请求可以包含多个新资源的详细信息,并将其全部添加到同一集合。
  • PUT 请求可以替换集合中的整个资源集。
  • DELETE 请求可以删除整个集合。

定义最大批大小、有效负载大小、执行时间和并发。 指定批处理是原子的,还是可以部分成功,并为每个操作返回结果。 授权并验证批处理中的每个操作。

如果使用 OData,可以使用 ASP.NET Core OData 来实现批处理请求。 有关详细信息,请参阅 ASP.NET Core OData 概述。

发送响应时请按照 HTTP 规范操作

返回相应的 HTTP 状态代码、标头和正文格式,以便客户端可以解释和处理响应。

例如,同步创建资源的 POST 操作应返回 201(已创建),并在 Location 响应标头中标识该资源。 接受后续处理工作的操作可以返回 202(已接受),但该响应并不表示该工作已成功完成。 不要包含包含 204(无内容)或 304(未修改)的响应正文。 有关详细信息,请参阅 HTTP 请求方法。

支持内容协商

响应正文可以包含格式不同的数据,例如 JSON 或 XML。 客户端可以使用 Accept 请求标头来指定支持的媒体类型。 例如,请求映像的客户端可以指定 image/jpeg, image/gif, image/png。 返回支持的表示形式,并在 Content-Type 响应标头中标识其媒体类型。

如果客户端未指定 Accept 标头,请使用文档中说明的默认格式。 默认情况下,ASP.NET Core控制器使用 JSON 格式化程序。 定义 API 无法生成请求表示形式时会发生什么情况。 例如,将 API 配置为返回 406(不可接受),而不是以无提示方式返回不受支持的格式。 有关详细信息,请参阅 ASP.NET Core Web API 中的格式响应数据。

对于具有正文的请求,请检查请求的 Content-Type,并且仅接受该操作支持的格式。 对于不支持的格式,返回 415(不支持的媒体类型)。 此检查独立于通过 Accept的响应协商。 在 ASP.NET Core中,配置输入格式化程序,并在需要限制操作的请求格式时使用[Consumes]。 有关详细信息,请参阅使用 ASP.NET Core 创建 Web API。

实现所选 API 版本控制策略

在应用程序和网关中一致 地应用在设计过程中选择的版本控制策略 。 将请求路由到所选版本的处理程序和响应架构。 定义对省略、格式不正确和不受支持的版本标识符的处理行为,而不是悄然更改现有调用方接收到的协定。

保留受支持版本的请求和响应协定。 引入破坏性变更时,请提供新版本并保留受支持的早期版本。 处理旧调用方发出的请求,这些请求省略新添加的可选字段。 有关详细信息,请参阅 API 版本控制与兼容性。

使生成的资源链接和缓存表示形式与所选版本保持一致。 对于基于标头的版本控制,请确保缓存区分不同版本的请求,而不是仅依赖于 URI。

解析并授权租户上下文

对于 多租户 API,请确定每个请求的租户,并验证经过身份验证的调用方是否可以访问该租户。 仅将路径、主机名和标头中的租户标识符视为路由输入。 有关详细信息,请参阅在多租户解决方案中将请求映射到租户。

在查询或更新数据以及将工作交给后台处理器时,始终使用授权租户上下文。 如果应用程序或网关缓存存储特定于租户的数据,请在缓存密钥中包含租户标识符。 有关特定于网关的指南,请参阅 支持多租户的 API 管理功能。

超文本作为应用程序状态引擎(HATEOAS)使用链接来帮助客户端发现和导航资源。 例如,包含客户详细信息的响应可以包含指向该客户的订单的链接。 描述每个链接资源支持的操作,例如 GET、POST、PUT 和 DELETE,并提供相应的 URI。 有关详细信息,请参阅 API 设计。

以下示例使用应用程序定义的链接表示形式。 记录其约定,而不是假设客户端可以解释自定义链接字段。 针对客户的 GET 请求将返回指向该客户的订单的链接:

GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "PUT",
     "types": ["application/x-www-form-urlencoded"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "DELETE",
     "types": []},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "POST",
     "types": ["application/x-www-form-urlencoded"]}
]}

Customer以下记录表示客户数据。 其 Links 属性包含 HATEOAS 链接。

public sealed record Customer(
    int CustomerId,
    string CustomerName,
    IReadOnlyList<Link> Links);

public sealed record Link(
    string Rel,
    string Href,
    string Action,
    IReadOnlyList<string> Types);

GET 操作从存储中检索客户数据,构造一条带有其链接的 Customer 记录,并返回 JSON 响应。 每个链接均包含以下字段:

  • 返回的资源与链接资源之间的关系(Rel)。 在此示例中,self 表示客户,而 orders 表示客户的订单集合。
  • 以 URI 形式表示由该链接描述的对象的超链接(Href)。
  • 可以发送到 URI 的 HTTP 请求类型(Action)。
  • 应在 HTTP 请求中提供或可在响应中返回的任何数据的格式 (Types),具体取决于请求的类型。

HTTP 响应的示例中所示的 HATEOAS 链接指示客户端应用程序可以执行以下操作:

  • 向 https://api.contoso.com/customers/2 发出的用于将客户详细信息检索为 XML 或 JSON 的 HTTP GET 请求。
  • 将 HTTP PUT 请求发送到 https://api.contoso.com/customers/2 以修改客户详细信息。 请求正文使用此格式: application/x-www-form-urlencoded
  • 用于删除客户记录的 HTTP DELETE 请求 https://api.contoso.com/customers/2 。 此操作不需要请求正文,并且不返回响应正文。
  • 向 https://api.contoso.com/customers/2/orders 发出的 HTTP GET 请求,用于以 XML 或 JSON 形式检索客户的订单。
  • 用于为客户创建订单的 HTTP POST 请求 https://api.contoso.com/customers/2/orders 。 请求正文使用此格式: application/x-www-form-urlencoded

处理异常

如果操作引发未处理的异常,请考虑以下指南。

捕获异常并向客户端返回有意义的响应

一致地处理异常,并返回一个有意义的错误响应,该响应可以安全地与客户端共享。 不要在生产响应中返回异常对象、堆栈跟踪或内部实现详细信息。 返回反映失败的 HTTP 状态代码,而不是为每个情况返回状态代码 500。 例如,如果用户请求导致违反约束的数据库更新(例如尝试删除有未完成订单的客户),则返回 409(冲突)和安全解释。 对于格式错误的输入或请求验证失败,而非意外的服务器故障,返回 400(错误请求)。 有关 HTTP 状态定义,请参阅 状态代码。 有关实现指南,请参阅处理 ASP.NET Core中的错误。

以下控制器将预期的域结果映射到 HTTP 响应。 在删除操作的过程中,其存储库操作检查授权和未完成的订单。 意外故障由集中式异常处理统一处理,而不是在每个操作中被静默捕获。

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
    {
        var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);

        return outcome switch
        {
            DeleteOutcome.Deleted => NoContent(),
            DeleteOutcome.NotFound => NotFound(),
            DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "The customer has outstanding orders."
            }),
            _ => throw new InvalidOperationException("Unknown deletion outcome.")
        };
    }
}

public enum DeleteOutcome
{
    Deleted,
    NotFound,
    HasOutstandingOrders
}

Important

不要包含可能对攻击者尝试获取对 API 未经授权的访问有用的信息。

托管层可以在请求到达 API 之前拒绝请求。 例如,身份验证失败可能会导致 401(未授权)响应。 身份验证后,验证调用方是否有权访问请求的资源。 授权失败时返回 403 (禁止访问)。

一致地处理异常,并记录有关错误的信息

若要一致地处理异常,请考虑在整个 Web API 中实现全局错误处理策略。 记录服务器上的诊断信息,但不包括机密、访问令牌和敏感个人数据。 在编写日志条目之前对敏感值进行脱敏,并仅允许已授权用户访问日志。 有关详细信息,请参阅 用于监视和威胁检测的体系结构策略。

在 ASP.NET Core 中,使用异常处理中间件和问题详细信息响应,以提供一致的错误契约。 配置生产响应以省略诊断详细信息,并包括支持团队用于查找相应日志的相关标识符。 有关详细信息,请参阅处理 ASP.NET Core 中的错误。

区分客户端错误和服务器端错误

对客户端错误使用 HTTP 4xx 状态代码,对服务器错误使用 HTTP 5xx 状态代码。 在错误响应中保留此区别。

优化客户端数据访问

频繁的请求和大型响应会使网络成为瓶颈。 实现资源检索和更新时减少不必要的传输。

支持客户端缓存

使用 Cache-Control 响应标头指定客户端和中间服务器是否可以存储响应及其保持新鲜的时间。

下面的示例演示了 HTTP GET 请求和包含 Cache-Control 标头的相应响应:

GET https://api.contoso.com/orders/2 HTTP/1.1
HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

在此示例中,响应将在 600 秒内保持有效。 该 private 指令允许在专用缓存(如浏览器缓存)中存储,但禁止在共享缓存中存储。 仅将 public 用于可在不同调用方之间安全共享的响应。 对不得存储的敏感响应,请使用 no-store。

在 ASP.NET Core控制器中,在返回响应之前设置缓存标头:

Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
    Private = true,
    MaxAge = TimeSpan.FromMinutes(10)
};

注意

该 no-cache 指令允许存储,但在重复使用之前需要重新验证。 使用 no-store 禁止存储。

API 在其响应中控制缓存策略和验证器。 客户端和中间服务器使用该信息来管理其缓存。 一致地设置这些标头,以便调用方可以重复使用响应,而无需不必要的数据传输。

若要确定 max-age,请考虑工作负荷可以容忍的过期程度。 当缓存的响应仍然新鲜时,资源可能会更改。 当新鲜度过期时,缓存可以重新验证响应,而不是放弃响应并再次下载整个表示形式。 对于需要立即查看更改的数据,不要使用较长的新生命周期。

提供 ETag 以优化查询处理

实体标记(ETag)是所选资源表示形式的不透明验证器。 客户端可以使用缓存的响应保留它,并在 If-None-Match 中发送它,以检查表示形式是否已更改。 相应的 GET 或 HEAD 请求在没有响应正文的情况下返回 304(未修改)。

生成一个验证程序,该验证程序在应用程序实例之间保持一致,并在表示形式发生更改时发生更改。

以下控制器对返回的确切 JSON 字节进行哈希处理,并重复使用应用程序的配置的 JSON 选项。 FileContentResult在没有自定义结果包装器的情况下应用 ASP.NET Core条件响应处理。 存储库仅返回调用方有权读取的订单。 在主机应用程序中配置身份验证和授权。

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
    [HttpGet("{id:int}")]
    [HttpHead("{id:int}")]
    public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
    {
        var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
        if (order is null)
        {
            return NotFound();
        }

        var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
        var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");

        Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
        {
            Private = true,
            MaxAge = TimeSpan.FromMinutes(10)
        };

        return new FileContentResult(payload, "application/json")
        {
            EntityTag = etag
        };
    }
}

此示例缓冲表示形式并读取顺序,甚至对于条件请求也是如此。 仅将其用于受限的非敏感响应。 对于大型资源,请考虑使用在所选表示形式发生更改时更改的存储版本令牌,以便无需生成完整有效负载即可验证请求。 如果内容协商、压缩或网关转换更改表示形式,请确保验证器和缓存变体对表示形式保持正确。

响应包括 ETag 和缓存策略。 以下示例显示了显示的 JSON 正文 SHA-256 哈希的前 16 个十六进制字符(64 位),后跟 ... 简洁。 实际标头包含没有省略号的完整哈希。

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

提示

对包含敏感数据的响应使用 Cache-Control: no-store。 对于可缓存的其他特定于用户的响应,请使用 private 以防止其存储在共享缓存中。 有关实现注意事项,请参阅 ASP.NET Core中的响应缓存中间件。

支持条件 GET 请求,以便调用方可以在不下载未更改的资源表示的情况下重新验证缓存的响应。 实现以下请求和响应行为:

  1. 接受在 If-None-Match 标头中提供 ETag 的条件 GET 请求,例如:

    GET https://api.contoso.com/orders/2 HTTP/1.1
    If-None-Match: "3097D1FD51082205..."
    
  2. 将所请求资源的当前 ETag(此示例中的顺序 2)与 If-None-Match 条件进行比较。

    • 如果条件匹配,则返回 304 (未修改)而不返回响应正文。

    • 如果条件不匹配,则返回 200 (OK) 以及当前表示形式。

    • 如果请求的资源不再存在,则返回 404(找不到)。

注意

ETag 不会使响应安全缓存。 一致地应用缓存指令,包括条件响应和错误响应,并对敏感数据使用 no-store。

尽可能对条件请求使用框架支持。 如果自己执行比较,请处理所有提供的实体标记、通配符条件以及弱与强比较规则,而不是仅比较第一个标记。 在 304(未修改)响应中包含相应的 ETag 和缓存标头,并在返回资源元数据之前执行授权。

提示

通过存储验证器,可以检查表示形式是否已更改,而无需检索完整的资源。 当资源很大或检索成本高昂时,此方法可以减少数据传输和处理。

使用 ETag 实现乐观并发控制

若要防止更新丢失,请针对状态更改请求,根据资源的当前 ETag 评估 If-Match 前置条件。 这允许 API 根据已被另一操作修改过的表示形式来拒绝更改。 实现以下行为:

  1. 接受在 If-Match 标头中标识预期版本的更新请求。 以下 PUT 请求更新订单 2。 它使用早期 GET 响应中以相同方式缩写的 ETag。 该标记标识现有表示形式,而不是新的请求正文:

    PUT https://api.contoso.com/orders/2 HTTP/1.1
    If-Match: "3097D1FD51082205..."
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 37
    
    productId=3&quantity=5&orderValue=250
    
  2. 将所请求资源的当前 ETag(此示例中的顺序 2)与 If-Match 条件进行比较。

    • 如果前置条件匹配,则以原子方式执行更新并返回文档中说明的成功响应,例如 204(无内容)。 并不只是因为更新了现有资源才需要 Location 标头。 仅当成功的 PUT 响应满足 HTTP 对存储表示形式的验证器要求时,才返回 ETag。

    • 如果条件不匹配,则返回 412 (前置条件失败)。 此示例不返回响应正文。

    • 如果要更新的资源不再存在,则返回 404 (找不到)。

  3. 记录成功和冲突响应,以便调用方可以确定更新是否成功,或者是否需要在提交另一项更改之前检索当前表示形式。

对于必须防止丢失更新的操作,需要前置 If-Match 条件,并在缺少前置条件时返回 428(需要前置条件)。 对If-Match使用强比较。

检查应用程序内存中的版本,然后无条件保存会创建竞态条件。 确保在数据存储中以原子方式执行版本比较和写入。 例如,使用数据库并发令牌,以便仅当存储的版本仍与用于评估请求的版本匹配时,更新才会成功。

在实体框架 (EF) 核心中,配置并发令牌并处理 DbUpdateConcurrencyException,而不是覆盖并发更改。 在 API 的数据访问代码中,除非操作的语义允许,否则不要自动替换预期版本并重试发生冲突的数据库更新。 有关详细信息,请参阅 处理并发冲突。

处理大型请求和响应

大型请求和响应正文会占用 API 内存、带宽和连接容量。 实现流式处理和资源限制,避免大型传输耗尽服务资源。 处理大量数据时,请考虑以下几点:

优化涉及大型对象的请求和响应

对于大型对象(如图像或其他二进制数据),支持流式上传和下载。

使用异步流式处理 API,让服务器为协商的 HTTP 版本选择传输分帧。 不要手动将 Transfer-Encoding: chunked 添加到响应的每个部分。 流式处理不限于 HTTP/1.1 分块编码。 避免在应用程序内存中缓冲整个无界请求或响应。

在应用程序和托管层设置请求正文限制、上传限制、超时和取消策略。 在启动响应之前,使用 413(内容过大)拒绝超大请求。

HTTP 压缩可以降低传输大小,但代价是在服务器和客户端上进行额外的处理。 例如,客户端可以发送 Accept-Encoding: gzip。 如果服务器返回 gzip 压缩的内容,请使用 Content-Encoding: gzip 来识别编码。

通过托管平台或中间件配置压缩,并在客户端和服务器端测量其 CPU 和带宽权衡。

  • 避免重新压缩已经压缩过的文件格式。
  • 在为动态生成的 HTTPS 响应启用压缩之前,请评估压缩风险(如 BREACH),并应用适当的缓解措施。 即使在中间件中禁用 HTTPS 压缩,托管服务器也可能配置为应用压缩。
  • 确保在内容编码更改时缓存变体和 ETag 保持正确。

有关压缩实现指南和安全注意事项,请参阅 ASP.NET Core中的响应压缩。

支持大型资源的部分下载

如果 API 支持部分下载大型资源,请用 Accept-Ranges 表明该功能。 通过返回资源的元数据(包括其总 Content-Length)而不返回响应正文来处理 HEAD 请求。 对于指定受支持字节范围的 GET 请求,返回 206(部分内容)、针对返回部分的 Content-Length,以及用于标识资源该部分的 Content-Range。 此响应协定允许调用方检索资源的某些部分,而无需 API 返回整个对象。

HTTP HEAD 请求和部分响应会在 API 设计中详细介绍。

处理大型上传的 100-Continue

对于大型 HTTP/1.1 上传,客户端可以发送请求标头 Expect: 100-continue ,并在传输正文之前等待。 服务器可以发送临时 100(继续)响应或拒绝请求,而无需接收完整正文。 此交换是一个请求的一部分,而不是一个初步的空请求,后跟第二个完整请求。

配置并测试托管堆栈和网关如何在有和没有 Expect: 100-continue 的情况下处理请求。 验证 API 在接受或拒绝上传时的行为,并衡量对服务器资源使用情况和请求延迟的影响。

支持对可能返回大量对象的请求进行分页

检索整个大型集合可能会增加服务器处理、网络流量和延迟。

验证服务器上的分页输入并强制实施最大页面大小。 以下控制程序演示了请求验证。 它默认为 10 个结果,并拒绝超出 1 到 100 的限制,或 0 到 10,000 以外的偏移量。 这些边界是示意性的。 根据工作负荷和负载测试选择限制。 使用 [ApiController]时,验证失败会生成 400 响应。 有关详细信息,请参阅使用 ASP.NET Core 创建 Web API。

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
        [FromQuery, Range(1, 100)] int limit = 10,
        [FromQuery, Range(0, 10000)] int offset = 0,
        CancellationToken cancellationToken = default)
    {
        var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
        return Ok(orders);
    }
}

客户端可以使用 请求从偏移量 50 开始的 30 个订单。

除了上述示例中所示的请求验证之外,在响应契约中包括下一页链接或继续令牌。 例如,当有其他页面可用时,返回将 https://api.contoso.com/orders?limit=30&offset=80 属性设置为 nextLink 的订单。 在链接中保留筛选器、排序顺序和 API 版本。 在最后一页省略 nextLink 或将其设置为 null。 有关下一链接协定的示例,请参阅Microsoft Graph分页。

在数据存储区中而不是在加载整个集合之后应用筛选和分页。 使用确定性排序顺序。 对于大型或频繁更改的集合,请评估基于游标的分页以避免昂贵的偏移量和不稳定的页面边界。

提示

对查询复杂性、筛选表达式和请求大小强制执行文档规定的限制。 测试请求路径中每个网关、代理和服务器的极限。

保持响应能力、可伸缩性和可用性

为 API 的关键操作定义延迟、吞吐量和可用性目标。 针对预期流量、流量突增和依赖项故障进行设计和测试。 横向扩展和无状态处理支持这些目标。 请考虑以下实现要求。

为长时间运行的请求提供异步支持

对于持续时间超过普通 HTTP 请求的工作,请验证和授权该请求,持久记录工作,并返回 202(已接受)。 不要依赖未跟踪的进程内任务在响应后完成:应用程序重启、缩容和部署可能会中断它。 当工作必须继续运行时,请使用持久队列和工作程序或持久工作流,以便即使发生这些事件,工作也能继续运行。 有关完整的 HTTP 语义和实现指南,请参阅 异步 Request-Reply 模式。

为调用方提供检索操作状态和结果的方法。 处理完成后,API 还可以通知调用方。

可以提供客户端轮询的状态资源:

  1. 客户端提交请求。 在接受工作之前验证其输入和权限。
  2. 在持久存储中保留操作标识符和状态,例如Azure 表存储,并使用Azure 服务总线将工作加入队列,供单独的处理器处理。 协调持久化和入队,使这两个操作之间发生故障时不会导致已接受的工作丢失。
  3. 返回 202,其中包含 Location 标识状态终结点的标头以及 Retry-After 控制轮询频率的标头。 仅在工作已被持久记录后接受请求。
  4. 辅助角色处理该操作并更新其持久状态。 使处理具有幂等性,因为工作线程可能会重复收到同一任务。 对暂时性故障采用有界重试。
  5. 客户端轮询状态终结点。 对状态终结点和结果终结点强制实施资源级授权。 不可猜测的标识符并非授权。
  6. 在工作进行期间,返回记录的状态表示形式。 完成后,提供结果或 303(查看其他),重定向到结果资源。 通过一致且安全的错误约定报告失败。
  7. 定义操作记录和结果的保留和清理。 文档操作过期、重复提交和任何受支持的取消行为。

对于连接的客户端,请考虑将 ASP.NET Core SignalR 用于完成通知。 保持持久状态资源可用,以便客户端可以在断开连接或错过通知后恢复。 有关详细信息,请参阅 ASP.NET Core SignalR 概述。

确保每个请求都是无状态的

不要要求后续请求到达与先前请求相同的应用程序实例。 将工作流和资源状态保留在适当的共享存储中,而不只是在进程内存中。 请求可以依赖于持久的资源状态,而无需创建服务器实例相关性。 无状态请求处理支持横向扩展。

了解下游依赖项

为每个下游调用设置超时。 确保调用、重试和延迟的总时间不超过 API 请求的截止时间,并将请求取消传播到下游操作。

仅重试暂时性故障,以及可安全重复执行的操作。 使用带退避和抖动的有限重试。 限制每个依赖项的聚合重试次数以及每个请求的尝试次数。 有关详细信息,请参阅临时故障处理。

当重复依赖项故障可能耗尽 API 容量时,请使用 断路器 。

跟踪客户端并实现限制以降低 DoS 攻击的可能性

设置请求速率、并发、有效负载和执行时间限制。 尽可能按经过身份验证的调用方或租户划分限制。 当调用方超过配置的速率时,返回 429(请求过多);当服务暂时不可用时,返回 503(服务不可用)。 在适当情况下添加 Retry-After。 如果 API 重试对下游依赖项的调用,则应限制这些重试次数,以免它们放大过载。

网关和应用程序限制用于不同的目的。 网关限制可以保护共享容量。 应用程序限制可以反映运营成本和下游容量。 两者都不能替代网络层 DDoS 保护或 Web 应用程序防火墙。 有关详细信息,请参阅 “限制”模式。

小心管理永久 HTTP 连接

对于入站连接,请为工作负荷和网络路径配置服务器和网关保持连接超时、请求超时和并发连接限制。 不要在每次响应后例行强制关闭连接。 有关 ASP.NET Core服务器设置的信息,请参阅为 Kestrel Web 服务器配置选项。

如果 API 本身调用下游 HTTP 服务,请重复使用这些出站连接。 在 .NET API 实现中,使用具有适当 HttpClient 的长期存在的 PooledConnectionLifetime 实例,或使用由 IHttpClientFactory 创建的客户端。 不再需要出站响应消息和流时释放这些消息和流。 这些设置适用于 API 的下游调用,不适用于传入客户端连接。 有关详细信息和 Cookie 处理注意事项,请参阅 有关使用 HttpClient 的准则。

发布和管理 Web API

将 API 部署到满足其运行要求的托管环境。 请考虑以下策略:

  • 使用 HTTPS。 对受保护终结点的请求进行身份验证,并为每个资源和操作强制实施授权。
  • 扩展托管环境以随着需求变化满足响应时间承诺。
  • 如果 API 的计费模型需要,请计量请求。
  • 根据需要调节流量并强制执行客户端配额。
  • 记录符合性和事件响应所需的审核事件,但不记录凭据、令牌或敏感请求和响应正文。
  • 监视主机运行状况并定义恢复操作,例如重启不正常的主机。

请考虑使用单独的 外观来处理共享管理问题,并将已验证的请求转发到 API。 外观模式可以提供以下功能:

  • 充当多个 Web API 的集成点。
  • 转换消息并转换使用不同技术生成的客户端的通信协议。
  • 缓存请求和响应以减少托管 Web API 的服务器上的负载。

在版本控制下保留 API 协定和网关配置,验证部署管道中的更改,并定义回滚过程。 将托管、标识、网络和治理与组织的登陆区域方法保持一致。 有关详细信息,请参阅什么是 Azure 登陆区域?

测试 Web API

使用单元测试来验证 API 的逻辑和集成测试,以验证其 HTTP 行为。

包括以下检查:

  • 测试所有路由以验证它们是否调用正确的操作。 特别注意 HTTP 状态代码 405(方法不被允许)被意外返回。 此状态代码可以指示路由与可以调度到该路由的 HTTP 方法(GET、POST、PUT、DELETE)之间的不匹配。

    发送使用各个路由不支持的方法的请求,并验证文档中记录的 405(不允许的方法)响应和 Allow 标头。

  • 验证所有路由是否都得到正确保护并受相应身份验证和授权检查的制约。

    注意

    安全性的某些方面(如用户身份验证)可能是主机环境(而不是 Web API)的责任,但仍需要在部署过程中包括安全测试。

  • 测试每个操作执行的异常处理,并验证是否将相应的有意义的 HTTP 响应传递回客户端应用程序。

  • 验证请求和响应消息的格式是否正确。 例如,对于创建资源的 POST 请求,请验证反序列化、解析、资源创建和响应的 Location 标头。

  • 与响应内容协商分开测试支持和不支持的请求媒体类型。 验证针对不受支持的请求格式返回的 415(不支持的媒体类型)响应,以及格式不正确的正文的文档中记录的验证错误。

  • 测试每个受支持的 API 版本,包括其路由、请求验证和响应架构。 测试省略、格式不正确和不受支持的版本标识符,并验证缓存的响应不会跨越版本边界。

  • 验证响应消息中的所有链接和 URI。 例如,HTTP POST 消息应返回新创建的资源的 URI。 所有 HATEOAS 链接都应有效。

  • 确保每个操作针对不同输入组合返回正确的状态代码。 例如:

    • 如果查询成功,它应返回状态代码 200(OK)。
    • 如果未找到资源,该作应返回 HTTP 状态代码 404(找不到)。
    • 如果客户端发送的请求成功删除资源,则状态代码应为 204(无内容)。
    • 如果客户端发送的请求创建了新资源,则状态代码应为 201(已创建)

    调查来自应用程序或托管层的意外 5xx 响应。

  • 测试客户端应用程序可以指定的不同请求标头组合并确保 Web API 在响应消息中返回预期的信息。

  • 测试查询字符串。 如果操作可以采用可选参数(如分页请求),请测试不同的组合和参数顺序。

  • 验证异步操作是否成功完成。 对于流式处理响应,请验证 API 是否不会缓冲整个有效负载,并且它是否能够正确处理客户端断开连接和取消。 如果 API 为长时间运行的操作提供状态资源,请验证它们是否正确报告操作进度和结果。

测试影响正确性的失败和边界事例:

  • 验证最小、最大、负数、格式不正确、过大的分页参数和批处理输入。
  • 按照分页链接进行,直到到达最后一页为止。 验证链接是否保留查询选项,并验证返回的是文档中说明的完成信号。
  • 验证其他输入字段不能更改受保护的属性,并且字段选择不能公开未经授权的数据。
  • 测试匹配、非匹配、弱、多个和通配符 ETag,并验证 304 响应是否不包含正文。
  • 执行并发更新并确认数据存储以原子方式拒绝过时的写入。
  • 验证调用方无法读取其他调用方的资源、状态记录或缓存响应。
  • 对于多租户 API,请测试伪造的或不匹配的租户标识符。 启用缓存后,测试来自不同租户的相同资源 URI 的请求。
  • 模拟超时、客户端取消、依赖项失败、工作程序重启和后台工作重复传递。
  • 验证下游超时和重试预算、取消和断路器恢复。
  • 验证 429(请求过多)和 503(服务不可用)响应、重试行为以及拒绝过载请求的成本。

针对类似生产的基础结构和实际操作组合运行负载测试。 定义吞吐量、延迟百分位数、错误率和资源饱和度的通过和失败标准。 使用Azure 负载测试并将回归检查集成到部署管道中。

使用 API 管理

如果需要强制实施策略的托管网关,请考虑使用Azure API 管理。 它增加了成本、另一个网络跃点和请求路径中的依赖项。 根据容量、网络、可用性和区域要求选择服务层级和拓扑;功能因层而异。 开发人员层不适用于生产工作负荷。 按照 API 管理Well-Architected 服务指南进行操作。

可以通过完成以下步骤来发布和管理 Web API:

  1. 将 Web API 部署到托管平台,例如Azure 应用服务、Azure 容器应用、Azure Kubernetes 服务 (AKS)或Azure 虚拟机。

  2. 配置 API 管理以将请求从网关 URL 路由到后端 API。 一个 API 管理实例可以将请求路由到多个 API。 当应用程序需要不同的访问边界时,多个实例还可以公开相同的后端 API。

    注意

    响应中的 HATEOAS 链接应引用 API 管理网关 URL,而不是后端服务器 URL。

  3. 导入版本控制的 OpenAPI 定义,并验证导入的操作、参数、安全要求和响应架构是否与实现匹配。 检查支持的 OpenAPI 版本和导入限制。 有关详细信息,请参阅 导入 OpenAPI 规范。

  4. 为客户端到网关和网关到后端通信配置身份验证和授权。 验证 OAuth 2.0 访问令牌并强制实施客户端请求所需的权限。 对于支持Microsoft Entra ID身份验证的后端,首选仅具有所需权限的 API 管理托管标识。 证书验证是另一个选项。 在有更安全的选项可用时,请避免使用基本身份验证。 有关详细信息,请参阅 Azure API 管理 中的 API 身份验证和授权。

    注意

    如果需要 API 管理订阅密钥,请不要将其用作身份验证和资源级授权的替代项。

  5. 根据需要配置身份验证、跨域访问、消息转换、IP 筛选、速率限制和配额的策略。 仅为安全缓存的数据配置响应缓存。 在适当的范围内应用策略并验证对每个操作有效的行为。

有关详细信息,请参阅API 管理文档。

Important

网关不会使后端私有或替换资源级授权。 设计整个工作负荷(包括网关)的后端访问控制、故障处理、容量和可观测性。 根据所选层的功能评估地区和区域冗余。 在成本模型中包括网关费用、遥测引入和保留以及数据传输。

为客户端开发人员提供支持

为 API 使用者提供身份验证、操作、参数、数据类型和响应代码的文档。

记录 Web API 的 REST 操作

发布一个 OpenAPI 定义,该定义描述 API 的操作、参数、请求和响应架构以及安全要求。 将其与实现一起纳入版本控制,并验证它是否与 API 的实际行为匹配。

为 API 参考补充指导,帮助使用者正确使用 API:

  • 每个操作的身份验证要求和权限。
  • 代表性请求、成功的响应和错误响应。
  • 输入验证规则、有效负载限制、分页和速率限制。
  • 超时行为、重试安全性以及任何幂等性要求。
  • 长时间运行的操作的状态和结果检索。
  • 版本控制与兼容性预期。

使文档和示例在 API 协定发生更改时保持最新。

实现客户端 SDK

请考虑为 API 使用者提供 SDK。 SDK 可以提供类型化方法,这些方法可构造请求、分析响应并显示 API 文档中说明的错误。

请考虑从 API 的 OpenAPI 定义生成类型化客户端,但要根据该服务验证生成客户端的行为。 文档身份验证、超时、取消、分页、错误响应以及可安全重试的操作。 使客户端和 API 兼容性策略保持一致。 生成的代码不会消除集成测试的需求。

监视 Web API

一起监视 API、其依赖项和任何网关。 根据客户影响定义服务级别目标和警报,而不是仅依赖于主机运行状况。

直接监视 Web API

使用 OpenTelemetry 插桩收集跟踪、指标和日志,并将信号导出到 Application Insights 或其他受支持的后端。 对于 .NET、Node.js 和 Python 插桩,请遵循 Microsoft OpenTelemetry 发行版指南。 Java使用 Azure Monitor OpenTelemetry 发行版。 遵循特定于语言的 OpenTelemetry 启用指南。

监视描述 API 行为的信号:

  • 按操作统计的请求量、失败率和延迟百分位数
  • 依赖项延迟、失败和超时
  • 限流拒绝、并发任务和资源饱和
  • 后台操作队列时长、完成时间、失败和重试
  • 缓存有效性,当缓存是设计的一部分时

监视工具自动收集的遥测数据因语言、库和配置而异。 为域操作和后台工作添加埋点。 不要假定浏览器会话、用户角色或所有请求详细信息都将自动可用。 跨网关、应用程序和工作器传播跟踪上下文。 配置采样和保留,以平衡诊断需求、数据敏感度和遥测成本。

在适当情况下,使用 Application Insights 标准可用性测试 进行定期外部检查。 在不暴露敏感数据的情况下检查有意义的运行状况或操作终结点,定义可操作的警报并维护响应 Runbook。

使用 API 管理监视 Web API

使用 API 管理支持的Azure Monitor指标、日志、分析和诊断来区分网关故障与后端故障。 关联网关和应用程序遥测,并监视策略故障、容量、请求延迟和限制。 可用信号取决于层级和网关配置。

遵循 API 管理的Well-Architected 服务指南中的可观测性和容量建议。

后续步骤