企业官网建设流程全解析

1. 什么是 API 设计

API（Application Programming Interface，应用程序编程接口）是不同软件系统之间进行数据交换与功能调用的契约。它规定了调用方如何发起请求、需要传递哪些参数、能够获得什么样的返回结果，以及在出错时系统应当如何反馈。一个 API 的优劣，不仅决定开发者能否快速完成集成，也深刻影响系统的可维护性、可扩展性和长期演进能力。API 设计，就是在系统建设初期为这些交互方式制定清晰、一致、可持续演进的规则。

在单体应用时代，API 往往只是内部模块之间的函数调用，设计好坏的影响相对有限。然而进入微服务、前后端分离、多端并存的时代后，API 已经成为产品的核心资产。它既被内部前端、移动端、小程序调用，也可能直接开放给第三方合作伙伴甚至公众开发者。一个优秀的 API 可以让调用方在几分钟内理解语义、跑通流程；一个混乱的 API 则可能让集成成本成倍上升，甚至直接劝退产品使用者。

从工程实践看，API 设计的价值主要体现在三个层面。第一，降低沟通成本：清晰一致的命名与结构，让前端、后端、测试、产品都在同一套语义下工作，减少反复确认和口口相传的隐性知识。第二，提升系统演进能力：良好的抽象与版本策略允许服务端在不破坏现有调用方的前提下持续升级，避免每次改动都引发大规模联动修改。第三，增强可预测性与安全性：统一的错误处理、认证机制、限流策略让调用方可以写出更健壮的客户端，也方便网关层统一治理。

需要特别强调的是，API 设计绝不是简单地“包装一个 HTTP 接口”。它涉及资源建模、URL 命名、状态码语义、错误处理、版本控制、安全策略、性能优化等一系列系统工程问题。本文将以 RESTful API 为主线，结合大量真实场景与代码示例，系统拆解 API 设计的最佳实践，并提供可直接落地的检查清单。全文从这个领域的基础知识逐步深入到实战细节，力求为读者建立一套完整可复用的方法论。

2. API 设计的核心原则

无论采用 REST、GraphQL 还是 gRPC，优秀的 API 设计背后都遵循一些共通原则。理解这些原则，比记住某一套具体规范更加重要。它们能帮助我们在面对模糊需求和权衡取舍时做出正确决策，也能在团队成员意见不一致时提供判断依据。

2.1 一致性优先

一致性是 API 设计中最重要、也最容易在日常迭代中被破坏的原则。这里的一致体现在多个层面：命名风格一致、URL 结构一致、参数风格一致、错误格式一致、时间格式一致、分页方式一致。调用方一旦掌握了你的第一个 API，就应该能凭借直觉推断出其他 API 的用法，而不必每次都去翻阅文档。

例如，用户相关接口若统一采用/users/{id}、/users/{id}/orders这样的层级结构，就不要在另一个模块突然使用/getUserById?id=123。如果错误响应统一返回{ "error": { "code": "...", "message": "..." } }，就不要在个别接口返回纯文本或另一种结构。一致性最好的落地方式是把规范沉淀为团队共识文档，并通过代码评审和自动化校验持续守护。许多风格漂移并非有人故意为之，而是缺少可参照规则或在赶进度时沿用了旧接口的惯性。

2.2 面向资源而非动作

REST 的核心是把系统中的“事物”抽象成资源，用名词表示，并通过有限的 HTTP 方法表达对资源的操作。资源可以是用户、订单、商品等物理实体，也可以是登录会话、支付状态等逻辑实体。URL 中应当使用名词，避免出现动词。

text

GET /users # 查询用户列表 GET /users/123 # 查询单个用户 POST /users # 创建用户 PUT /users/123 # 全量更新用户 PATCH /users/123 # 部分更新用户 DELETE /users/123 # 删除用户

与之相对，GET /getUsers、POST /createUser、GET /deleteUser?id=1都是动作式设计。它们把操作细节暴露在 URL 中，既违背 HTTP 方法语义，又会让接口数量无限膨胀。当然，并非所有动作都能优雅映射为资源，登录、支付回调、批量导出等场景可以谨慎使用动作式子资源，但应作为例外而非惯例。

2.3 可预测性与最小惊讶

可预测性意味着相同输入应产生可预期的输出，相同类型的接口应遵循相同的行为模式。查询不存在的资源应统一返回 404，创建成功应统一返回 201，未授权应统一返回 401。调用方不应在每个接口上猜测“这个接口成功时返回 200 还是 201”。

最小惊讶原则要求设计符合大多数开发者的既有认知。如果大多数人看到 204 会理解为“成功但无返回内容”，就不应该用它表示“资源未找到”；如果limit在列表接口中表示每页条数，就不要在另一个接口中用它表示时间跨度。偏离常规是允许的，但必须有充分理由并在文档中显著说明。

2.4 高内聚与低耦合

API 暴露的应该是稳定、有边界的业务能力，而不是数据库表的直接映射。调用方关心的是“如何完成一个业务目标”，而非“服务端内部有几张表、字段叫什么”。理想情况下，领域模型与 API 模型应当分离。服务端可以把复杂的内部结构合并成对调用方友好的视图，也可以隐藏将来可能变化的内容标识，从而避免内部重构时被迫升级对外 API 版本。

低耦合还体现在 API 之间的依赖关系上。一个资源应尽量不要求调用方先调完 A 才能调 B。如果确实存在强依赖，应考虑通过嵌套资源、聚合接口或批量接口一次性返回，减少客户端往返次数和状态维护成本。

2.5 渐进式演进

API 一旦发布，就会有调用方基于它构建业务。每一次破坏性修改都可能造成线上故障，因此必须做好演进规划。基本原则是：优先做向后兼容的扩展，避免破坏性修改；当破坏不可避免时，通过版本化隔离新旧行为，并给调用方留出充分迁移时间。常见兼容性扩展包括新增可选字段、新增可选查询参数、新增资源方法、放宽校验条件。破坏性修改则包括删除或重命名字段、改变字段类型、改变错误结构、收紧校验、改变分页默认值。

3. RESTful API 基础与资源建模

资源建模是 RESTful API 设计的第一步。很多后续问题，如 URL 结构、数据冗余、权限控制，都源于资源边界划分是否合理。建模的目标是找到一组概念清晰、职责单一、能够稳定表达业务语义的资源。

3.1 资源的定义

资源是任何可以被命名、寻址、描述和操作的信息实体。在电商系统中，用户、商品、订单、购物车、优惠券、支付流水都可以被建模为资源。资源并不一定要对应数据库中的某张表，它可以是计算结果的快照、虚拟实体，甚至是另一个资源的某种视图。

判断一个概念是否应成为独立资源，可以问三个问题：它是否会被独立地查询、创建、修改或删除？调用方是否需要用单独的 URL 来引用它？它是否具备稳定业务语义，而不是某个接口的临时输入输出？如果答案都是肯定的，就值得把它提升为一级资源；如果它只是父资源的附属属性，可以先作为字段表达，待业务演进到需要独立寻址时再拆分。

3.2 资源层级与嵌套

资源之间常存在天然的从属关系，例如订单属于某个用户、订单条目属于某个订单。REST 允许通过嵌套 URL 表达这种关系。然而嵌套深度需要谨慎把握，推荐最多两层，超过两层就应考虑扁平化。

text

# 推荐：两层以内 GET /users/123/orders GET /users/123/orders/456/items # 不推荐：层级过深，可读性和维护性都差 GET /companies/1/departments/2/teams/3/employees/4/addresses/5

嵌套资源的适用条件是：子资源离开父资源后无法独立存在，或者子资源的访问几乎总是发生在父资源上下文中。如果子资源本身也有很强的独立访问需求，更好的做法是既提供顶层资源，也提供必要的冗余关联字段。例如订单既可以通过/orders/456直接访问，也可以通过/users/123/orders按用户筛选，同时订单中保存userId字段建立关联。资源层级设计的关键不是把所有关系都放进 URL，而是在调用方最常见的访问路径上提供最短、最直观的入口。

3.3 集合资源与单例资源

大多数资源以集合形式存在，如/users是用户集合，/users/123是集合中的单个成员。但有些概念天然是单例，比如当前登录用户的个人资料、某个租户的全局配置。对于单例资源，可以使用唯一固定标识，如/users/me或/config。使用me可以避免客户端必须先知道自己的用户 ID 才能获取个人信息，这种“当前主体”语义在移动端和第三方登录场景中尤为重要。单例资源通常只支持 GET 和 PATCH，不支持 POST 创建集合。

3.4 领域模型与 API 模型的分离

一个常见错误是让 API 的 JSON 结构完全等同于数据库表结构或 ORM 实体。这种设计看似省事，实际上把内部实现细节暴露给外部，后续任何内部调整都会牵动 API。正确做法是引入 API DTO（Data Transfer Object），它只包含对外有意义的字段，使用对调用方友好的命名和类型，并根据场景裁剪数据。下表展示内部字段与对外 API 字段的对比思路：

这种分离虽然增加了一点编码工作量，但换取了 API 的稳定性和内部重构的自由度，非常值得。

4. URL 设计规范

URL 是调用方与 API 交互的第一道界面。良好的 URL 应当具备自解释能力：调用方只读 URL 就能大致猜出它返回什么。URL 设计看似简单，却极容易出现不规范、不一致和过度冗余的情况。

4.1 命名风格

资源的命名应遵循以下规则：使用名词而非动词；使用复数名词表示集合；全部小写；多词使用连字符而非下划线或驼峰；避免文件扩展名。

text

# 推荐 GET /api/v1/users GET /api/v1/users/123/posts # 不推荐 GET /api/v1/getUserList GET /api/v1/user_search_by_name

复数形式在集合语义上更自然，也避免单复数混淆。媒体类型应由Accept和Content-Type头协商决定，不要通过.json这样的扩展名来指定。

4.2 路径层级与可读性

URL 路径应当从最稳定的概念到最具体的概念逐步递进。例如/organizations/{orgId}/projects/{projectId}/tasks，从左到右是从宽到窄的自然层级。层级之间应当有真实的从属关系，而不是为了满足 REST 形式而强行嵌套。此外，路径中不要包含无意义的前缀或技术细节，版本号通常采用/v1、/v2的前缀形式。

4.3 尾斜杠与路径规范化

URL 是否带尾斜杠应当是全局一致的决定，通常推荐不带尾斜杠，如/users而非/users/。无论选择哪种，服务端都应做规范化处理：把带尾斜杠和不带尾斜杠的请求视为同一路由，避免两个 URL 指向同一资源但行为不同。更规范的做法是在网关层统一处理尾斜杠，设置 301 重定向或直接内部归一化。

4.4 查询参数与路径参数的边界

路径参数用于标识资源本身，查询参数用于表达筛选、排序、分页等“如何获取资源”的条件。一个经验法则是：删除某个路径参数后 URL 指向的资源会改变；删除某个查询参数后资源仍是同一个，只是数据的视图发生变化。

text

# 路径参数：标识具体资源 GET /users/123 # 查询参数：筛选和投影 GET /users?status=active&page=1&size=20&sort=-createdAt

需要避免把查询参数用于核心资源寻址，例如GET /users?id=123。虽然技术上可行，但它破坏了资源语义，也不利于后续统一路由、缓存和权限治理。

5. HTTP 方法语义

HTTP 方法不是随意的动词标签，而是带有明确语义和幂等性约定的协议动词。正确使用方法不仅能提升 API 表现力，也能让中间件、网关、缓存和客户端自动获得很多能力。下面逐一讨论最常用方法。

5.1 GET：安全且幂等

GET 用于读取资源，不应当改变服务端状态。它必须是安全的，也必须是幂等的：无论调用多少次，结果和副作用都相同。正因为 GET 具备这些性质，浏览器、CDN、代理可以放心地缓存 GET 响应。违背这一原则的典型错误是用 GET 创建资源或触发副作用，例如GET /send-email?to=xxx，这类设计会导致爬虫、预取、重试等行为产生不可预期的后果。

5.2 POST：创建与复杂操作

POST 用于创建集合中的新资源，或执行无法用其他方法表达的复杂操作。POST 不保证幂等，重复调用可能会创建多个资源或重复执行副作用。

json

POST /orders { "userId": "123", "items": [ { "productId": "P200", "quantity": 2 } ], "addressId": "ADDR-9" }

由于 POST 的非幂等性，关键业务系统需要配合幂等键等机制防止重复提交。POST 的响应通常返回 201 Created，并在Location头中给出新资源的 URL。

5.3 PUT：全量替换

PUT 用于完整替换一个已知标识的资源。调用方必须提供资源的完整表示，缺失字段将被视为清空或覆盖。PUT 是幂等的：对同一资源反复发送相同的 PUT 请求，最终状态一致。PUT 常用于能够由客户端完整构造资源内容的场景，如更新用户基础资料。

json

PUT /users/123 { "userName": "zhangsan", "email": "zhangsan@example.com", "nickname": "张三" }

如果只想更新部分字段，PUT 会要求客户端先取回完整资源再合并，容易产生并发覆盖风险，此时应优先使用 PATCH。

5.4 PATCH：部分更新

PATCH 用于对资源进行部分修改，只传递需要变更的字段。它的优点是网络开销小、并发冲突概率低。常见的 PATCH 格式有 JSON Merge Patch 和 JSON Patch。JSON Merge Patch 更简单直观，适合大多数业务场景。

json

PATCH /users/123 { "nickname": "新昵称" }

需要注意的是，PATCH 不保证幂等，其幂等性取决于补丁操作本身。例如“将年龄加 1”这样的语义天然不幂等，而“将昵称设置为某值”则是幂等的。

5.5 DELETE：删除资源

DELETE 用于删除指定资源。删除成功通常返回 204 No Content 或 200，删除不存在的资源一般返回 404。DELETE 在语义上是幂等的：无论调用多少次，最终资源都处于已删除状态。实际实现中，业务系统经常采用逻辑删除，即把记录标记为已删除而不是物理移除，此时 DELETE 表现为对资源状态的一次转换。

5.6 方法选择建议

选择方法时应优先考虑语义是否匹配，而不是“能不能用”。把删除操作写成 GET，虽然调用方便，但会破坏缓存、爬虫、预取等机制的前提假设。

6. 状态码设计

HTTP 状态码是 API 与调用方之间最基础的语义约定。正确使用状态码，可以显著减少客户端对响应体的解析困难，让日志监控、网关路由和自动化测试都变得更加可靠。状态码使用上的一个常见误区，是无论成功还是失败都返回 200，再把真实的业务结果塞进响应体。这种做法会破坏 HTTP 协议语义，也让 CDN、网关和客户端无法基于状态码做统一处理。

6.1 常用状态码分类

表中的 401 和 403 经常被混淆。401 表达的是“你是谁还不清楚”或者“你的凭证无效”，属于认证问题；403 表达的则是“我知道你是谁，但你不能做这件事”，属于授权问题。清晰区分两者，能帮助调用方在遇到 401 时引导用户重新登录，在遇到 403 时检查权限配置。

6.2 状态码使用原则

保持全局一致：同样的业务语义只能对应同一个状态码。例如“资源不存在”在所有接口都返回 404，而不是有的返回 404、有的返回 200 加错误码。

用最准确的状态码：创建成功用 201 而不是 200；异步任务用 202 而不是 200；空响应用 204 而不是 200 加空对象。越准确的语义越有利于调用方和中间件。

不让状态码承担业务错误码职责：状态码代表 HTTP 层的通用语义，业务细节应通过响应体中的错误码和消息进一步说明。例如“库存不足”“优惠券已过期”都可以使用 409 或 422，再用业务错误码细分。

面向调用方思考：选择状态码时，应优先考虑调用方拿到状态码后会做什么。401 触发重新登录，429 触发退避重试，409 触发人工介入或刷新重试，500 则通常只安全重试或上报。

7. 错误处理与响应格式

错误处理是 API 设计中很容易被忽视、却极大影响开发体验的部分。一个优秀的 API，不仅要让成功路径清晰，更要让失败路径同样明确、可预测、可编程处理。调用方在接入系统时，往往最先遇到的就是各种异常情况，因此错误响应的设计直接决定了集成效率。

7.1 统一错误响应结构

全系统应当使用同一种错误响应格式，不能有的接口返回纯文本，有的返回 JSON，有的返回另一种 JSON 结构。推荐的结构至少包含错误码和可读消息，并可扩展详细信息、字段校验结果等。

json

{ "error": { "code": "ORDER_INSUFFICIENT_STOCK", "message": "商品 P200 库存不足", "details": [ { "field": "items[0].quantity", "reason": "available stock is 1" } ], "traceId": "e17a0d3c-2c4b-4a1f-8e44-12f9adce1234" } }

这里有几个设计要点。错误码建议采用稳定、可读的字符串而不是数字代号，因为字符串具备自解释能力，也更容易在代码中做枚举。错误码的命名通常遵循“领域加场景”的方式，例如USER_EMAIL_ALREADY_EXISTS、ORDER_STATUS_NOT_ALLOWED。消息面向开发者，应尽量具体，说明出错原因和解决方向；面向终端用户的文案则应由客户端根据错误码自行映射，避免服务端掺杂展示层逻辑。

details可用于携带批量校验失败时的逐字段错误。对于创建订单、批量导入等复杂场景，一次性返回所有校验错误比逐个尝试提交体验更好。traceId则用于链路追踪，把客户端反馈和日志关联起来。

7.2 业务错误码与 HTTP 状态码的映射

业务错误码和 HTTP 状态码是两个不同维度，不应混为一谈。HTTP 状态码面向传输层和通用语义，业务错误码面向具体领域。典型做法是：每个错误响应都选择一个最贴切的 HTTP 状态码，再通过error.code表达精确业务含义。

例如，“用户不存在”和“订单已过期”在 HTTP 层都可以用 404 表达“目标不存在”，但业务错误码分别为USER_NOT_FOUND和ORDER_EXPIRED。调用方可以先根据状态码做通用处理，再根据业务错误码做精细分支。这样既保持协议层面的统一，又保留了业务表达力。

应当避免的错误做法，是把所有业务错误都塞进 400，也不要把服务器内部异常直接透传给客户端。对于未预期的 500 错误，不要在响应体中暴露堆栈、SQL 或内部路径，只返回通用消息和 traceId，真实异常记录在服务端日志中。

7.3 常见错误场景示例

8. 版本控制与兼容性演进

API 不可能一成不变。随着业务发展，总会出现字段新增、结构调整、规则变化等需求。版本控制的目标，是让这些变化在不破坏现有调用方的前提下有序发生。没有版本策略的 API，就像没有刹车的高速列车，每一次修改都可能是事故。

8.1 版本策略的选择

常见的版本控制方式主要有三类：URL 路径版本、请求头版本和媒体类型版本。

URL 路径版本：/api/v1/users、/api/v2/users。最大的优点是直观，调用方一眼就能看出使用的版本，也便于网关路由和文档拆分。缺点是 URL 中包含版本信息，在严格 REST 主义者看来不够“纯粹”，但实践中这是最流行、最容易被团队接受的方式。

请求头版本：通过自定义头如Api-Version: v2或Accept-Version: v2传递版本。优点是资源 URI 保持稳定，缺点是调用方忘记传头时极易拿到错误版本，排查成本较高。

媒体类型版本：使用Accept: application/vnd.company.resource.v2+json这种定制媒体类型。表达能力强，但过于复杂，对多数业务系统来说是过度设计。

对大多数团队而言，URL 路径版本是性价比最高的选择。它足够简单、清晰，也能与路由器、网关、文档工具良好配合。版本号只取主版本号即可，例如 v1、v2，不要出现 v1.2.3 这样的语义化版本，因为 API 的破坏性变化只应该体现在主版本上。

8.2 兼容性演进原则

版本控制不是鼓励随意发布破坏性变更，而是为不可避免的变更提供安全出口。日常演进中，应优先做向后兼容的扩展：

• 新增可选字段：老调用方忽略新字段即可继续工作。

• 新增可选查询参数：默认行为保持不变。

• 新增资源方法或新的子资源：不触碰已有路由。

• 放宽校验规则：原本能通过校验的请求仍然通过。

以下变化属于破坏性修改，不能在原版本上直接发布：

• 删除字段或重命名字段。

• 改变字段类型，例如把 groupId 从数字改成字符串。

• 改变成功响应的状态码或响应结构。

• 收紧校验规则，让原本合法的请求变得不合法。

• 改变分页默认值或排序默认规则。

• 删除已有的方法或路由。

出现这些情况时，应发布新版本，并给旧版本保留一段合理的兼容期。兼容期内要做好迁移通知，提供清晰的变化说明和迁移脚本，必要时提供自动化检测工具，帮助调用方发现不兼容的用法。

8.3 废弃流程

废弃旧版本需要一套明确的流程：先标记 Deprecated，在文档和响应头中提示太阳落山时间；经过一个或多个版本的缓冲期后，再按计划下线。可以用Deprecation响应头和Sunset响应头传递废弃信息，方便工具化识别。无论如何，都要避免在没有任何提醒的情况下突然删除旧接口。

9. 认证与授权

认证解决“你是谁”的问题，授权解决“你能做什么”的问题。两者是 API 安全体系的两块基石，任何对外暴露的接口都应当明确其认证方式和授权范围。

9.1 常见认证方式

选择认证方式时，应结合安全要求、调用方类型、运维成本综合判断。对于内部服务间调用，mTLS 或 API Key 加网络隔离通常足够；对于开放平台，OAuth 2.0 是事实标准；对于前后端分离的单页应用，JWT 配合刷新令牌是常见方案。

9.2 授权模型

授权模型决定“谁能访问哪些资源”。常见模型包括：

• RBAC（基于角色的访问控制）：用户绑定角色，角色绑定权限。简单直观，适合大多数业务系统。

• ABAC（基于属性的访问控制）：根据用户属性、资源属性、环境属性动态判断。灵活但复杂，适合策略多变场景。

• ReBAC（基于关系的访问控制）：根据用户与资源之间的关系判断。适合社交、协作类系统。

无论采用哪种模型，API 层都应统一做权限校验，避免把权限判断散落在各业务方法中。网关层可以承担粗粒度校验，服务层再做细粒度校验，形成纵深防御。

9.3 安全传输与凭证管理

所有对外 API 都应强制使用 HTTPS，避免凭证和数据在传输过程中被窃取。Token 应设置合理有效期，并提供刷新机制。刷新令牌应妥善保管，最好与访问令牌分离存储。密钥和证书应通过安全的密钥管理服务下发，避免硬编码在代码或配置文件中。

10. 分页、过滤与排序

列表接口是 API 中使用频率最高、也最容易设计不一致的一类接口。分页、过滤、排序是列表接口的三大核心能力，应当在全局范围内统一约定。

10.1 分页设计

常见的分页方式有两种：偏移分页和游标分页。

偏移分页使用page和size或offset和limit参数，简单直观，适合数据量不大、允许跳页的场景。缺点是在数据频繁变动时可能产生重复或遗漏，且深分页性能较差。

text

GET /users?page=2&size=20 GET /users?offset=20&limit=20

游标分页使用一个不透明的cursor参数，服务端根据游标定位下一页起点。它适合数据量大、实时性要求高的场景，如信息流、日志查询。缺点是不能随意跳页。

text

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

无论采用哪种方式，响应中都应包含分页元信息，例如：

json

{ "data": [ ... ], "pagination": { "page": 2, "size": 20, "total": 135, "hasNext": true } }

10.2 过滤设计

过滤参数应保持命名一致，通常使用字段名作为参数名，多个值用逗号分隔或重复参数表达。范围过滤可以使用field_gte、field_lte这样的后缀，也可以用min、max等语义化命名。

text

GET /orders?status=paid&createdAt_gte=2024-01-01&amount_lte=1000 GET /products?category=book&tag=java&tag=spring

避免为每个过滤条件设计一套独立的参数格式，这样会导致接口难以记忆和自动化处理。

10.3 排序设计

排序参数通常使用sort，值为字段名，前缀-表示降序，多个字段用逗号分隔。

text

GET /users?sort=-createdAt GET /orders?sort=status,-amount

排序字段应当做白名单校验，避免调用方传入数据库不存在的字段或恶意字段，导致性能问题或注入风险。

11. 幂等性设计

幂等性是指同一操作执行一次或多次，对系统产生的影响相同。对于支付、下单、扣库存等关键业务，幂等性是防止重复提交、保证数据一致性的重要手段。

11.1 为什么需要幂等

网络超时、客户端重试、消息重复投递都可能导致同一请求被多次执行。如果接口不具备幂等性，就可能产生重复订单、重复扣款、重复发券等严重问题。因此，凡是会产生副作用的接口，都应考虑幂等设计。

11.2 幂等键

最常用的幂等实现方式是幂等键。调用方在请求头或请求体中携带一个全局唯一的Idempotency-Key，服务端在处理前先检查该键是否已处理过。如果已处理，直接返回上次的结果；如果未处理，则正常执行并记录结果。

text

POST /payments Idempotency-Key: 6c4b0b5e-2f4a-4c3b-9d1e-8f7a2b1c0d9e Content-Type: application/json { "orderId": "ORDER-123", "amount": 99.00, "currency": "CNY" }

服务端应当把幂等键与处理结果一起持久化，并设置合理的过期时间。对于并发请求，可以使用唯一索引或分布式锁保证同一幂等键只有一个请求真正执行。

11.3 天然幂等的设计

除了幂等键，还可以通过设计让操作天然幂等。例如：

• 使用 PUT 更新资源为确定状态，而不是用 POST 做增量修改。

• 使用 DELETE 删除资源，重复删除结果一致。

• 使用状态机约束操作，只有特定状态才能执行特定动作，重复请求会被状态校验拦截。

• 使用版本号或条件请求，避免并发覆盖。

在关键业务中，通常会把幂等键与状态机、版本号结合使用，形成多重防护。

12. 性能与缓存

API 的性能直接影响用户体验和系统成本。合理的缓存策略、分页策略、字段裁剪和压缩，可以显著降低响应时间和带宽消耗。

12.1 缓存头

HTTP 提供了丰富的缓存控制头，正确使用可以让客户端、CDN、代理自动缓存响应，减少服务端压力。

• Cache-Control：控制缓存行为，如max-age、no-cache、no-store、private、public。

• ETag：资源版本标识，配合If-None-Match实现条件请求。

• Last-Modified：资源最后修改时间，配合If-Modified-Since实现条件请求。

• Expires：绝对过期时间，逐渐被Cache-Control取代。

对于不常变化的资源，可以设置较长的max-age；对于用户私有数据，应使用private并配合认证；对于实时性要求高的数据，应使用no-store或较短的缓存时间。

12.2 条件请求

条件请求允许客户端在资源未变化时避免传输响应体。服务端返回ETag或Last-Modified，客户端下次请求时携带If-None-Match或If-Modified-Since，如果资源未变化，服务端返回 304 Not Modified，不返回响应体。

text

GET /users/123 If-None-Match: "abc123" HTTP/1.1 304 Not Modified ETag: "abc123"

条件请求不仅能节省带宽，还能减少服务端序列化和网络传输开销，是读多写少场景的重要优化手段。

12.3 字段裁剪与稀疏字段集

默认返回全部字段虽然方便，但在移动端或带宽受限场景下可能造成浪费。可以支持fields参数，让调用方指定需要的字段。

text

GET /users/123?fields=id,name,email

字段裁剪应做好权限校验，避免调用方通过字段选择绕过权限控制。同时，字段名应保持与资源模型一致，避免引入另一套命名。

12.4 压缩与传输优化

服务端应支持gzip或br压缩，减少响应体大小。对于大文件下载，应支持分块传输和断点续传。对于实时性要求高的场景，可以考虑使用 HTTP/2 或 HTTP/3，提升多路复用和传输效率。

13. 限流与熔断

限流和熔断是保护 API 可用性的重要手段。它们可以防止单个调用方或异常流量拖垮整个系统，也能在依赖服务故障时快速失败，避免级联雪崩。

13.1 限流策略

常见的限流算法包括：

• 固定窗口：实现简单，但存在临界问题。

• 滑动窗口：平滑限流，适合大多数场景。

• 令牌桶：允许突发流量，适合需要弹性的场景。

• 漏桶：恒定速率处理，适合保护下游。

限流维度可以按调用方、按接口、按 IP、按用户等。返回 429 Too Many Requests 时，应携带Retry-After头，告知调用方多久后可以重试。

text

HTTP/1.1 429 Too Many Requests Retry-After: 30 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1700000000

13.2 熔断与降级

当下游服务错误率或响应时间超过阈值时，熔断器会打开，快速失败后续请求，避免资源耗尽。经过一段时间后，熔断器进入半开状态，允许少量请求探测下游是否恢复。如果恢复正常，则关闭熔断器；如果仍然失败，则继续保持打开。

降级是在依赖不可用时提供简化或兜底逻辑，保证核心功能可用。例如推荐服务不可用时返回热门榜单，支付服务不可用时引导用户稍后重试。

限流和熔断应在网关层和服务层共同实施，形成多层防护。网关层做全局限流和粗粒度熔断，服务层做细粒度限流和业务降级。

14. 文档与测试

优秀的 API 不仅要有良好的设计，还要有清晰的文档和可执行的测试。文档让调用方快速上手，测试保证接口行为符合预期。

14.1 API 文档

API 文档应包含以下内容：

• 接口说明：用途、适用场景、调用限制。

• 请求方法、URL、路径参数、查询参数、请求头。

• 请求体结构，包括字段类型、是否必填、取值范围、示例。

• 响应体结构，包括成功和失败示例。

• 状态码和错误码说明。

• 认证方式和权限要求。

• 限流策略和重试建议。

• 版本变更记录和废弃计划。

推荐使用 OpenAPI（Swagger）等标准格式描述 API，这样可以自动生成文档、客户端 SDK 和测试用例，减少人工维护成本。

14.2 契约测试

契约测试用于验证服务端实现是否符合 API 契约，以及调用方是否按契约使用 API。常见的工具包括 Pact、Spring Cloud Contract 等。契约测试可以在服务拆分、版本升级时提前发现不兼容问题，是保障 API 稳定性的重要手段。

14.3 集成测试与端到端测试

除了契约测试，还应编写集成测试验证接口在真实环境下的行为，包括认证、授权、限流、错误处理等。端到端测试则从调用方视角验证完整业务流程，确保多个 API 协同工作时行为正确。

测试用例应覆盖成功路径、边界条件、异常场景和并发场景。对于关键接口，还应做性能测试和压力测试，评估其在高负载下的表现。

15. API 设计检查清单

在完成 API 设计后，可以使用以下清单做一次系统检查，确保没有遗漏重要细节。

15.1 资源与 URL

• 资源是否用名词表示，避免动词。

• 集合资源是否使用复数名词。

• URL 是否全部小写，多词是否使用连字符。

• 嵌套层级是否控制在两层以内。

• 是否避免了无意义的前缀和文件扩展名。

• 尾斜杠处理是否全局一致。

15.2 HTTP 方法

• GET 是否只用于读取，不产生副作用。

• POST 是否用于创建或复杂操作。

• PUT 是否用于全量替换且幂等。

• PATCH 是否用于部分更新，语义是否明确。

• DELETE 是否幂等，删除不存在资源的行为是否明确。

15.3 状态码与错误处理

• 状态码是否准确表达语义。

• 401 和 403 是否区分清楚。

• 错误响应结构是否全局统一。

• 业务错误码是否稳定、可读、可枚举。

• 是否避免暴露内部异常和堆栈。

15.4 版本与兼容性

• 是否有明确的版本策略。

• 破坏性修改是否通过新版本发布。

• 旧版本是否有废弃流程和迁移期。

• 是否提供兼容性检测工具或说明。

15.5 安全与性能

• 是否强制 HTTPS。

• 认证和授权是否覆盖所有敏感接口。

• 是否有限流和熔断策略。

• 是否合理使用缓存和条件请求。

• 是否支持字段裁剪和压缩。

15.6 文档与测试

• 是否有完整的 API 文档。

• 是否使用 OpenAPI 等标准格式。

• 是否有契约测试和集成测试。

• 是否覆盖异常场景和并发场景。

• 是否有变更记录和废弃通知。

16. 总结

API 设计是一项贯穿系统生命周期的系统工程。它不仅关乎接口能否跑通，更关乎系统能否长期稳定演进、团队能否高效协作、调用方能否快速集成。

优秀 API 的共同特征是：一致、可预测、面向资源、边界清晰、演进有序。它们用统一的命名和结构降低认知成本，用准确的状态码和错误格式提升可编程性，用版本策略和兼容性规则保障长期稳定，用安全、限流、缓存等手段保护系统可用性。

API 设计没有银弹，也没有一劳永逸的规范。重要的是理解原则背后的原因，结合业务场景和团队能力做出权衡，并通过文档、评审、测试和监控持续守护设计质量。只有这样，API 才能真正成为产品的核心资产，而不是技术债务的来源。