1. 什么是 API 设计APIApplication 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?id123。如果错误响应统一返回{ error: { code: ..., message: ... } }就不要在个别接口返回纯文本或另一种结构。一致性最好的落地方式是把规范沉淀为团队共识文档并通过代码评审和自动化校验持续守护。许多风格漂移并非有人故意为之而是缺少可参照规则或在赶进度时沿用了旧接口的惯性。2.2 面向资源而非动作REST 的核心是把系统中的“事物”抽象成资源用名词表示并通过有限的 HTTP 方法表达对资源的操作。资源可以是用户、订单、商品等物理实体也可以是登录会话、支付状态等逻辑实体。URL 中应当使用名词避免出现动词。textGET /users # 查询用户列表 GET /users/123 # 查询单个用户 POST /users # 创建用户 PUT /users/123 # 全量更新用户 PATCH /users/123 # 部分更新用户 DELETE /users/123 # 删除用户与之相对GET /getUsers、POST /createUser、GET /deleteUser?id1都是动作式设计。它们把操作细节暴露在 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 DTOData Transfer Object它只包含对外有意义的字段使用对调用方友好的命名和类型并根据场景裁剪数据。下表展示内部字段与对外 API 字段的对比思路内部字段是否暴露对外处理方式id是直接暴露可作为资源标识user_name是映射为 userName统一驼峰风格password_hash否绝不暴露internal_status部分映射为简化的 status 枚举created_at是统一 ISO 8601 时间格式deleted_flag否通过过滤逻辑隐藏这种分离虽然增加了一点编码工作量但换取了 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?statusactivepage1size20sort-createdAt需要避免把查询参数用于核心资源寻址例如GET /users?id123。虽然技术上可行但它破坏了资源语义也不利于后续统一路由、缓存和权限治理。5. HTTP 方法语义HTTP 方法不是随意的动词标签而是带有明确语义和幂等性约定的协议动词。正确使用方法不仅能提升 API 表现力也能让中间件、网关、缓存和客户端自动获得很多能力。下面逐一讨论最常用方法。5.1 GET安全且幂等GET 用于读取资源不应当改变服务端状态。它必须是安全的也必须是幂等的无论调用多少次结果和副作用都相同。正因为 GET 具备这些性质浏览器、CDN、代理可以放心地缓存 GET 响应。违背这一原则的典型错误是用 GET 创建资源或触发副作用例如GET /send-email?toxxx这类设计会导致爬虫、预取、重试等行为产生不可预期的后果。5.2 POST创建与复杂操作POST 用于创建集合中的新资源或执行无法用其他方法表达的复杂操作。POST 不保证幂等重复调用可能会创建多个资源或重复执行副作用。jsonPOST /orders { userId: 123, items: [ { productId: P200, quantity: 2 } ], addressId: ADDR-9 }由于 POST 的非幂等性关键业务系统需要配合幂等键等机制防止重复提交。POST 的响应通常返回 201 Created并在Location头中给出新资源的 URL。5.3 PUT全量替换PUT 用于完整替换一个已知标识的资源。调用方必须提供资源的完整表示缺失字段将被视为清空或覆盖。PUT 是幂等的对同一资源反复发送相同的 PUT 请求最终状态一致。PUT 常用于能够由客户端完整构造资源内容的场景如更新用户基础资料。jsonPUT /users/123 { userName: zhangsan, email: zhangsanexample.com, nickname: 张三 }如果只想更新部分字段PUT 会要求客户端先取回完整资源再合并容易产生并发覆盖风险此时应优先使用 PATCH。5.4 PATCH部分更新PATCH 用于对资源进行部分修改只传递需要变更的字段。它的优点是网络开销小、并发冲突概率低。常见的 PATCH 格式有 JSON Merge Patch 和 JSON Patch。JSON Merge Patch 更简单直观适合大多数业务场景。jsonPATCH /users/123 { nickname: 新昵称 }需要注意的是PATCH 不保证幂等其幂等性取决于补丁操作本身。例如“将年龄加 1”这样的语义天然不幂等而“将昵称设置为某值”则是幂等的。5.5 DELETE删除资源DELETE 用于删除指定资源。删除成功通常返回 204 No Content 或 200删除不存在的资源一般返回 404。DELETE 在语义上是幂等的无论调用多少次最终资源都处于已删除状态。实际实现中业务系统经常采用逻辑删除即把记录标记为已删除而不是物理移除此时 DELETE 表现为对资源状态的一次转换。5.6 方法选择建议方法语义幂等安全典型场景GET读取资源是是查询列表、查询详情POST创建资源或复杂操作否否创建订单、提交表单PUT全量替换资源是否更新完整用户资料PATCH部分更新资源视情况否修改昵称、更新状态DELETE删除资源是否删除订单、移除地址选择方法时应优先考虑语义是否匹配而不是“能不能用”。把删除操作写成 GET虽然调用方便但会破坏缓存、爬虫、预取等机制的前提假设。6. 状态码设计HTTP 状态码是 API 与调用方之间最基础的语义约定。正确使用状态码可以显著减少客户端对响应体的解析困难让日志监控、网关路由和自动化测试都变得更加可靠。状态码使用上的一个常见误区是无论成功还是失败都返回 200再把真实的业务结果塞进响应体。这种做法会破坏 HTTP 协议语义也让 CDN、网关和客户端无法基于状态码做统一处理。6.1 常用状态码分类状态码含义适用场景200 OK请求成功GET、PUT、PATCH 等成功的一般响应201 Created资源已创建POST 创建成功配合 Location 头返回新资源 URI202 Accepted已接受异步处理中耗时任务、异步回调、批量处理204 No Content成功但无返回内容DELETE 成功、无需返回体的更新301 Moved Permanently永久重定向资源 URL 永久变更304 Not Modified内容未改变配合 ETag、Last-Modified 做缓存校验400 Bad Request请求语法或参数错误参数缺失、格式错误、校验失败401 Unauthorized未认证或认证失败缺少凭证、Token 过期或无效403 Forbidden已认证但无权限权限不足、资源禁止访问404 Not Found资源不存在查询、更新、删除不存在的资源409 Conflict资源状态冲突并发冲突、重复创建、业务规则冲突422 Unprocessable Entity语义校验失败参数格式正确但业务校验不通过429 Too Many Requests请求过于频繁限流场景配合 Retry-After 头500 Internal Server Error服务端内部错误未预期异常、系统故障502 Bad Gateway网关错误上游服务无响应或返回异常503 Service Unavailable服务暂时不可用维护、过载、熔断降级表中的 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 常见错误场景示例场景建议状态码示例业务错误码参数缺失或格式错误400INVALID_ARGUMENTToken 缺失或过期401UNAUTHENTICATED无权限操作403PERMISSION_DENIED资源不存在404USER_NOT_FOUND并发冲突409VERSION_CONFLICT业务规则校验失败422BUSINESS_VALIDATION_FAILED限流429RATE_LIMIT_EXCEEDED系统异常500INTERNAL_ERROR8. 版本控制与兼容性演进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.v2json这种定制媒体类型。表达能力强但过于复杂对多数业务系统来说是过度设计。对大多数团队而言URL 路径版本是性价比最高的选择。它足够简单、清晰也能与路由器、网关、文档工具良好配合。版本号只取主版本号即可例如 v1、v2不要出现 v1.2.3 这样的语义化版本因为 API 的破坏性变化只应该体现在主版本上。8.2 兼容性演进原则版本控制不是鼓励随意发布破坏性变更而是为不可避免的变更提供安全出口。日常演进中应优先做向后兼容的扩展新增可选字段老调用方忽略新字段即可继续工作。新增可选查询参数默认行为保持不变。新增资源方法或新的子资源不触碰已有路由。放宽校验规则原本能通过校验的请求仍然通过。以下变化属于破坏性修改不能在原版本上直接发布删除字段或重命名字段。改变字段类型例如把 groupId 从数字改成字符串。改变成功响应的状态码或响应结构。收紧校验规则让原本合法的请求变得不合法。改变分页默认值或排序默认规则。删除已有的方法或路由。出现这些情况时应发布新版本并给旧版本保留一段合理的兼容期。兼容期内要做好迁移通知提供清晰的变化说明和迁移脚本必要时提供自动化检测工具帮助调用方发现不兼容的用法。8.3 废弃流程废弃旧版本需要一套明确的流程先标记 Deprecated在文档和响应头中提示太阳落山时间经过一个或多个版本的缓冲期后再按计划下线。可以用Deprecation响应头和Sunset响应头传递废弃信息方便工具化识别。无论如何都要避免在没有任何提醒的情况下突然删除旧接口。9. 认证与授权认证解决“你是谁”的问题授权解决“你能做什么”的问题。两者是 API 安全体系的两块基石任何对外暴露的接口都应当明确其认证方式和授权范围。9.1 常见认证方式方式说明适用场景API Key调用方在请求头或参数中携带固定密钥内部服务、第三方简单集成OAuth 2.0通过授权服务器颁发 Access Token第三方登录、开放平台JWT自包含的令牌携带签名和声明信息无状态服务、前后端分离Session Cookie服务端保存会话浏览器自动携带 Cookie传统 Web 应用mTLS双向 TLS 证书认证高安全要求的服务间通信选择认证方式时应结合安全要求、调用方类型、运维成本综合判断。对于内部服务间调用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参数简单直观适合数据量不大、允许跳页的场景。缺点是在数据频繁变动时可能产生重复或遗漏且深分页性能较差。textGET /users?page2size20 GET /users?offset20limit20游标分页使用一个不透明的cursor参数服务端根据游标定位下一页起点。它适合数据量大、实时性要求高的场景如信息流、日志查询。缺点是不能随意跳页。textGET /users?cursoreyJpZCI6MTIzfQlimit20无论采用哪种方式响应中都应包含分页元信息例如json{ data: [ ... ], pagination: { page: 2, size: 20, total: 135, hasNext: true } }10.2 过滤设计过滤参数应保持命名一致通常使用字段名作为参数名多个值用逗号分隔或重复参数表达。范围过滤可以使用field_gte、field_lte这样的后缀也可以用min、max等语义化命名。textGET /orders?statuspaidcreatedAt_gte2024-01-01amount_lte1000 GET /products?categorybooktagjavatagspring避免为每个过滤条件设计一套独立的参数格式这样会导致接口难以记忆和自动化处理。10.3 排序设计排序参数通常使用sort值为字段名前缀-表示降序多个字段用逗号分隔。textGET /users?sort-createdAt GET /orders?sortstatus,-amount排序字段应当做白名单校验避免调用方传入数据库不存在的字段或恶意字段导致性能问题或注入风险。11. 幂等性设计幂等性是指同一操作执行一次或多次对系统产生的影响相同。对于支付、下单、扣库存等关键业务幂等性是防止重复提交、保证数据一致性的重要手段。11.1 为什么需要幂等网络超时、客户端重试、消息重复投递都可能导致同一请求被多次执行。如果接口不具备幂等性就可能产生重复订单、重复扣款、重复发券等严重问题。因此凡是会产生副作用的接口都应考虑幂等设计。11.2 幂等键最常用的幂等实现方式是幂等键。调用方在请求头或请求体中携带一个全局唯一的Idempotency-Key服务端在处理前先检查该键是否已处理过。如果已处理直接返回上次的结果如果未处理则正常执行并记录结果。textPOST /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不返回响应体。textGET /users/123 If-None-Match: abc123 HTTP/1.1 304 Not Modified ETag: abc123条件请求不仅能节省带宽还能减少服务端序列化和网络传输开销是读多写少场景的重要优化手段。12.3 字段裁剪与稀疏字段集默认返回全部字段虽然方便但在移动端或带宽受限场景下可能造成浪费。可以支持fields参数让调用方指定需要的字段。textGET /users/123?fieldsid,name,email字段裁剪应做好权限校验避免调用方通过字段选择绕过权限控制。同时字段名应保持与资源模型一致避免引入另一套命名。12.4 压缩与传输优化服务端应支持gzip或br压缩减少响应体大小。对于大文件下载应支持分块传输和断点续传。对于实时性要求高的场景可以考虑使用 HTTP/2 或 HTTP/3提升多路复用和传输效率。13. 限流与熔断限流和熔断是保护 API 可用性的重要手段。它们可以防止单个调用方或异常流量拖垮整个系统也能在依赖服务故障时快速失败避免级联雪崩。13.1 限流策略常见的限流算法包括固定窗口实现简单但存在临界问题。滑动窗口平滑限流适合大多数场景。令牌桶允许突发流量适合需要弹性的场景。漏桶恒定速率处理适合保护下游。限流维度可以按调用方、按接口、按 IP、按用户等。返回 429 Too Many Requests 时应携带Retry-After头告知调用方多久后可以重试。textHTTP/1.1 429 Too Many Requests Retry-After: 30 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 170000000013.2 熔断与降级当下游服务错误率或响应时间超过阈值时熔断器会打开快速失败后续请求避免资源耗尽。经过一段时间后熔断器进入半开状态允许少量请求探测下游是否恢复。如果恢复正常则关闭熔断器如果仍然失败则继续保持打开。降级是在依赖不可用时提供简化或兜底逻辑保证核心功能可用。例如推荐服务不可用时返回热门榜单支付服务不可用时引导用户稍后重试。限流和熔断应在网关层和服务层共同实施形成多层防护。网关层做全局限流和粗粒度熔断服务层做细粒度限流和业务降级。14. 文档与测试优秀的 API 不仅要有良好的设计还要有清晰的文档和可执行的测试。文档让调用方快速上手测试保证接口行为符合预期。14.1 API 文档API 文档应包含以下内容接口说明用途、适用场景、调用限制。请求方法、URL、路径参数、查询参数、请求头。请求体结构包括字段类型、是否必填、取值范围、示例。响应体结构包括成功和失败示例。状态码和错误码说明。认证方式和权限要求。限流策略和重试建议。版本变更记录和废弃计划。推荐使用 OpenAPISwagger等标准格式描述 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 才能真正成为产品的核心资产而不是技术债务的来源。
