企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

RESTful API（Representational State Transfer API，表征状态转移接口）是当今 Web 服务中最主流的接口设计范式之一。本篇指南以 developer-roadmap 仓库中 api-design 路线图的restful-apis主题为核心，系统讲解 REST 的五大核心约束、HTTP 方法与状态码的正确使用、资源建模与 URI 设计，以及分页、版本化等实战要点。读完本文，你将能够基于 HTTP 协议设计出无状态、可缓存、接口统一、易于消费与扩展的 RESTful Web 服务。

RESTful API 是什么

RESTful API 是一套用于设计网络化应用的约定（conventions），它建立在 HTTP 协议之上，利用 HTTP 方法对数据进行读取、更新与删除。与 SOAP 等重量级协议相比，REST 提供了一种简单、标准化的方式构建 Web 服务，使其能够被浏览器、移动端、第三方系统等不同客户端轻松消费。

其核心价值体现在四个方面：

• 性能（performance）：依托 HTTP 缓存与无状态设计，减少不必要的服务端计算与网络往返；
• 可扩展性（scalability）：服务端不保存客户端会话状态，任意节点都能独立处理请求，便于水平扩展；
• 简单性（simplicity）：统一接口与资源化表达，让 API 容易被理解与实现；
• 可靠性（reliability）：通过标准化的状态码与幂等语义，让错误可预测、可恢复。

REST 的核心原则

REST 的五个关键特征构成了这一架构风格的基础，对应仓库中的 rest-principles 主题：

1. 无状态（Statelessness）

每次客户端请求都必须携带服务端处理该请求所需的全部信息，服务端不保存客户端上下文。这意味着：

• 认证信息（如 Token）随请求传递，而不是依赖服务端 Session；
• 任意一台服务器实例都能响应任意请求，实现真正意义上的负载均衡与故障转移；
• 请求之间互不依赖，便于缓存与重试。

2. 客户端-服务器分离（Client-Server）

客户端专注于用户界面与交互，服务端专注于数据存储与业务逻辑。两者通过统一接口解耦，使客户端与服务端可以独立演进。

3. 可缓存（Cacheability）

响应必须显式或隐式声明自身是否可缓存，从而让客户端或中间代理复用响应，减少网络开销。HTTP 提供了Cache-Control、ETag等机制配合实现（详见仓库中的 http-caching 主题）。

4. 统一接口（Uniform Interface）

通过资源、资源的表示、自描述消息与超媒体（HATEOAS）等约束，统一客户端与服务端的交互方式，使 API 易于理解、灵活且可扩展。

5. 分层系统（Layered System）

客户端无需关心请求经过多少中间层（网关、负载均衡、缓存代理），各层职责独立，可自由组合。

资源与资源表示（Resources and Representations）

REST 的核心思想是围绕资源（resource）展开：资源是 API 管理的任何"名词"，例如用户、订单、商品。客户端通过 HTTP 方法操作资源，而服务端返回的是资源的表示（representation）——当前主流的表示格式是 JSON。

仓库中的 resource-modeling 主题强调：建模即决定 API 暴露哪些"事物"以及它们如何映射到 URL。一个良好的资源模型应当在一开始就定义清楚：

• 资源的边界（哪些数据属于该资源）；
• 资源之间的关系（一对一、一对多、多对多）；
• 资源携带的数据字段。

如果建模阶段草率，后期就会出现别扭的 URL 结构和不一致的数据形状，一旦消费者开始依赖你的 API，修复代价将极其高昂。

HTTP 方法：CRUD 的语义映射

HTTP 方法定义了客户端可以向服务端发起的请求类型，是客户端与服务器交互的框架（见 http-methods 主题）。REST 中常用的方法有 GET、POST、PUT、DELETE 和 PATCH，它们与 CRUD 操作一一对应（见 crud-operations 主题）：

设计要点：

• GET与DELETE不得产生副作用（如修改数据、触发邮件发送），否则会破坏缓存与重试的安全前提；
• PUT是全量替换语义，PATCH是增量修改语义，不要混用；
• POST常用于无法用其他方法语义表达的操作（如"提交订单""上传文件"），非幂等意味着重复请求会产生多个结果，客户端需要额外去重保障。

HTTP 状态码：让结果可读、可调试

状态码是 API 设计不可分割的一部分，它向客户端传达请求处理结果的信息（见 http-status-codes 主题）。状态码是三位数字，第一位数字定义响应类别，后两位不具有分类意义。常用类别与典型取值：

使用规范：

• 200表示请求成功，404表示请求的资源在服务端不存在；
• 创建资源成功应返回201 Created，并携带Location头指向新资源；
• 204 No Content适合 DELETE 或无需响应体的操作；
• 语义化的状态码能显著提升 API 的健壮性，让调用方无需解析响应体即可判断结果，更易于调试。

URI 设计与参数：让接口可读、可记忆

URI 设计原则

URI 是用于在互联网上标识资源的字符串。精心设计 URI 是打造流畅 API 界面的关键（见 uri-design 主题）：

• 使用名词而非动词：/users而不是/getUsers；
• 利用 URL 的层级结构对相关资源分组：/users/42/orders表达"用户 42 的订单"；
• 使用复数形式表示资源集合：/users、/orders；
• 层级结构允许 API 在不破坏现有客户端功能的前提下随时间扩展：新增子资源只需追加路径段。

路径参数、查询参数与请求体

URL、查询参数与路径参数共同决定了 API 如何发送和检索数据（见 url-query--path-parameters 主题）：

• 路径参数（Path Parameters）：作为 URL 中可变数据的占位符，用于定位具体资源。例如GET /users/{id}中的{id}；
• 查询参数（Query Parameters）：用于过滤、排序或选择数据字段。例如GET /users?role=admin&sort=created_at&fields=id,name；
• 请求体（Body）：用于携带创建或更新资源所需的完整数据，通常为 JSON。

三者职责划分清晰：路径参数定位"哪个资源"，查询参数描述"怎么筛选/呈现"，请求体提供"要写入的数据"。

数据交换格式：JSON 与 REST

构建 JSON/RESTful API 时，JSON（JavaScript Object Notation）因其轻量、易读、被广泛接受而成为事实上的信息交换格式（见 building-json--restful-apis 主题）。一个典型的资源表示如下：

{ "data": { "type": "user", "id": "42", "attributes": { "name": "Alice", "email": "alice@example.com", "created_at": "2026-09-30T10:00:00Z" }, "relationships": { "orders": { "links": { "related": "/users/42/orders" } } } } }

要点：

• 服务端资源可通过标准 HTTP 协议被访问与操作，方便不同服务与系统之间的通信；
• 无状态交互要求每个请求都必须包含服务端理解并处理请求所需的全部信息，认证凭证、上下文数据不得依赖服务端记忆。

进阶实践：分页与版本化

分页（Pagination）

分页是 API 设计中处理海量数据的关键手段：与其在单个响应中返回全部数据（既臃肿又低效），不如将数据切分为更小的批次，让客户端按需增量获取（见 pagination 主题）。常见策略：

• limit-offset（偏移量分页）：GET /users?limit=20&offset=40。实现简单，但深分页时性能较差，数据变动时容易重复或遗漏；
• cursor-based（游标分页）：GET /users?limit=20&cursor=eyJpZCI6...。基于不透明游标定位，性能稳定、结果一致，适合实时变化的数据流；
• time-based（基于时间分页）：GET /events?before=2026-10-01T00:00:00Z。适合日志、事件类追加型数据。

一个优秀的分页设计应在易用性、效率与可扩展性之间取得平衡，并在响应中返回总数、下一页游标等元信息。

版本化（Versioning）

随着业务需求演进，API 必然发生变化，而版本化的目标就是在不破坏既有客户端应用的前提下管理变更（见 versioning-strategies 主题）。主流策略包括：

选择版本化策略时需综合考量实现难度、客户端兼容性与可访问性；URI 版本化是实践中最常见、对开发者最友好的一种。

总结

RESTful API 之所以成为接口设计的流行选择，根源在于它把性能、可扩展性、简单性与可靠性内建到了一组约束之中：无状态的客户端-服务器通信、可缓存的数据、统一的接口，以及围绕资源及其表示的交互模型。配合规范的 HTTP 方法语义、语义化的状态码、清晰的 URI 与参数设计、JSON 表示格式，以及分页与版本化等演进机制，开发者可以构建出既易于被各类客户端消费、又能够长期稳定演进的高质量 Web 服务。

如需深入学习，可继续浏览仓库中 api-design 路线图下的 REST 原则、HTTP 方法、HTTP 状态码、CRUD 操作、资源建模、URI 设计、分页与版本化策略等相关主题。

• 文档
• 教程
• 知识库