RESTful API 是一种基于RESTRepresentational State Transfer表述性状态转移架构风格设计的 Web API 接口规范。它由 Roy Fielding 博士在其博士论文中提出核心思想是将所有网络资源抽象为 URI统一资源标识符并通过标准的HTTP 协议对资源进行创建、读取、更新和删除等操作。RESTful 的本质是利用 HTTP 协议的特性来设计面向资源的 API而非单纯为了传输数据而设计接口。️ 六大架构约束REST 的核心定义要成为真正的 RESTful API必须遵循以下 6 个核心约束客户端-服务器分离 (Client-Server)关注点分离。客户端负责 UI 交互服务器负责数据存储和业务逻辑两者独立演进。无状态 (Stateless)这是 REST 最重要的约束。服务器端不存储任何客户端请求之间的上下文信息。每个请求必须包含所有必要信息如身份验证 Token服务器负责验证和处理。这使得服务器易于水平扩展。可缓存 (Cacheable)响应数据必须显式声明是否允许缓存通过Cache-Control等头信息。提高网络效率。统一接口 (Uniform Interface)REST 的核心特征约束了接口的通用性包含 4 个子约束资源标识URI每个资源有唯一的 URI。通过表述操作资源客户端通过操作资源的不同表述如 JSON/XML来改变资源状态。自描述消息消息头Header和消息体Body都包含足以让服务器理解的元数据。超媒体作为应用状态引擎 (HATEOAS)返回结果中包含下一步操作的链接如分页链接驱动客户端自动跳转这是最高级的 REST 成熟度。分层系统 (Layered System)客户端不知道请求经过了代理、网关还是最终服务器分层设计增加了安全性防火墙和负载均衡能力。按需代码 (Code-On-Demand - 可选)允许服务器返回可执行的代码如 JavaScript供客户端运行目前极少使用。 核心要素资源、URI 与 HTTP 方法1. 资源与 URI 设计规范资源用名词复数表示资源是事物User、Order而不是动作getUser。例如/users、/orders。层级关系用路径表示/users/123/orders表示 ID 为 123 的用户的所有订单。避免层级过深通常建议不超过两层如/users/123/orders可改为/orders?userId123使用查询参数过滤。使用小写字母和中划线如/user-profiles不建议使用下划线。2. HTTP 方法动词与幂等性HTTP 方法对应操作请求体幂等性安全性典型场景GET查询资源可选不建议是是获取列表或详情POST创建资源是否重复提交会创建多个否注册用户、提交订单PUT全量更新资源是是否更新整个用户信息需传全部字段PATCH局部更新资源是否极端情况否仅修改用户密码DELETE删除资源否是否注销用户幂等性 (Idempotent)无论执行 1 次还是 N 次资源状态保持一致GET、PUT、DELETE 都是幂等的POST 不是。 HTTP 状态码响应语义RESTful API 必须充分利用 HTTP 状态码而不是将错误信息放在 JSON 里返回 200。分类状态码含义使用场景2xx 成功200 OK成功GET、PUT、PATCH 成功201 Created已创建POST 创建资源成功常附带Location头返回新资源 URI204 No Content无内容DELETE 成功或 PUT 更新成功但无需返回 Body3xx 重定向301/302资源移动当 URI 变更时重定向4xx 客户端错误400 Bad Request参数错误或请求格式错误JSON 格式错误、必填字段缺失401 Unauthorized未认证缺少 Token 或 Token 过期403 Forbidden权限不足已登录但无操作权限404 Not Found资源不存在URI 路径错误或资源已被删除422 Unprocessable Entity语义错误参数校验失败如邮箱格式不正确429 Too Many Requests请求过频触发了限流策略5xx 服务器错误500 Internal Server Error服务器内部错误代码异常、数据库连接失败应尽量避免暴露堆栈503 Service Unavailable服务不可用服务宕机或正在重启 成熟度模型Richardson Maturity Model该模型定义了 RESTful API 的 4 个等级用于衡量接口的 REST 纯度Level 0单 URI 单一方法如仅使用POST /api通过 Body 参数区分操作。类似 RPC 风格。Level 1多 URI资源拆分引入资源概念如/users和/orders但依然只使用 POST。Level 2多 URI HTTP 方法正确使用 GET/POST/PUT/DELETE并配合状态码。这是 90% 以上成熟项目停留的等级。Level 3HATEOAS超媒体驱动响应中提供“下一步操作”的链接如 RESTful API 返回订单详情时附带cancel或pay的可执行 URI。这是真正的 REST 风格顶点但实现复杂在现实中常被简化。️ 安全性与认证RESTful API 自身不包含安全机制通常借助 HTTP 语义实现Token 认证最常用的方式。将 JWTJSON Web Token放在请求头Authorization: Bearer token中。OAuth2.0委托授权协议如微信登录。API Key放在请求头或 Query 参数中适用于服务器间调用。强制 HTTPS生产环境必须使用 TLS 加密传输。 高级最佳实践避坑指南字段过滤允许客户端指定返回字段减少冗余传输。GET /users/123?fieldsid,name,email分页与排序分页参数?page2size20偏移量或?cursorabc123limit10游标分页更适用于大数据量。排序?sortage,desc。API 版本控制当接口发生破坏性变更时必须使用版本控制。推荐做法放在 URI 路径中/v1/users这是最直观且清晰的方式常见于 Spring BootRequestMapping配置。备选方案放在 Header 中Accept-Version: v1。响应体结构统一为统一前后端交互推荐包装统一返回格式json{ code: 0, // 业务状态码 message: success, data: { ... }, // 具体的资源数据 timestamp: 1630000000 }注意对于204 No Content情况不应返回 Body。避免“动词”污染 URI严禁出现/api/createUser。应该用POST /api/users。启用 GZIP 压缩对于返回体较大的 JSON 数据压缩可以大幅节省带宽。 RESTful vs 其他常见风格对比维度RESTful APIGraphQLgRPC协议HTTP/HTTPSHTTP/HTTPSHTTP/2数据格式JSON主流 / XMLJSONProtobuf二进制传输效率中等中等请求体可能较大极高二进制序列化性能优势利用 HTTP 缓存单一请求获取复杂嵌套数据减少请求次数高效的二进制传输和流式传输适用场景通用 Web 应用、对外开放 API复杂多端查询BFF 层、数据结构多变的前端微服务间内部通信、低延迟/高性能场景 总结RESTful API 设计的本质是将资源抽象与 HTTP 协议深度融合通过无状态、统一接口和标准状态码构建松耦合、可扩展的系统边界。对于绝大多数业务系统达到Richardson Maturity Model Level 2使用正确 URI、HTTP 方法和状态码并坚持统一响应格式、合理分页和 Token 鉴权即可设计出优秀且规范的 RESTful 接口。Level 3HATEOAS虽然理想但在实际工程中往往因实现成本过高而被适度简化。 
长河君 · 2026/8/31 5:44:59 · 阅读 1.2k android开发转到java后端开发--RESTful API
RESTful API 是一种基于RESTRepresentational State Transfer表述性状态转移架构风格设计的 Web API 接口规范。它由 Roy Fielding 博士在其博士论文中提出核心思想是将所有网络资源抽象为 URI统一资源标识符并通过标准的HTTP 协议对资源进行创建、读取、更新和删除等操作。RESTful 的本质是利用 HTTP 协议的特性来设计面向资源的 API而非单纯为了传输数据而设计接口。️ 六大架构约束REST 的核心定义要成为真正的 RESTful API必须遵循以下 6 个核心约束客户端-服务器分离 (Client-Server)关注点分离。客户端负责 UI 交互服务器负责数据存储和业务逻辑两者独立演进。无状态 (Stateless)这是 REST 最重要的约束。服务器端不存储任何客户端请求之间的上下文信息。每个请求必须包含所有必要信息如身份验证 Token服务器负责验证和处理。这使得服务器易于水平扩展。可缓存 (Cacheable)响应数据必须显式声明是否允许缓存通过Cache-Control等头信息。提高网络效率。统一接口 (Uniform Interface)REST 的核心特征约束了接口的通用性包含 4 个子约束资源标识URI每个资源有唯一的 URI。通过表述操作资源客户端通过操作资源的不同表述如 JSON/XML来改变资源状态。自描述消息消息头Header和消息体Body都包含足以让服务器理解的元数据。超媒体作为应用状态引擎 (HATEOAS)返回结果中包含下一步操作的链接如分页链接驱动客户端自动跳转这是最高级的 REST 成熟度。分层系统 (Layered System)客户端不知道请求经过了代理、网关还是最终服务器分层设计增加了安全性防火墙和负载均衡能力。按需代码 (Code-On-Demand - 可选)允许服务器返回可执行的代码如 JavaScript供客户端运行目前极少使用。 核心要素资源、URI 与 HTTP 方法1. 资源与 URI 设计规范资源用名词复数表示资源是事物User、Order而不是动作getUser。例如/users、/orders。层级关系用路径表示/users/123/orders表示 ID 为 123 的用户的所有订单。避免层级过深通常建议不超过两层如/users/123/orders可改为/orders?userId123使用查询参数过滤。使用小写字母和中划线如/user-profiles不建议使用下划线。2. HTTP 方法动词与幂等性HTTP 方法对应操作请求体幂等性安全性典型场景GET查询资源可选不建议是是获取列表或详情POST创建资源是否重复提交会创建多个否注册用户、提交订单PUT全量更新资源是是否更新整个用户信息需传全部字段PATCH局部更新资源是否极端情况否仅修改用户密码DELETE删除资源否是否注销用户幂等性 (Idempotent)无论执行 1 次还是 N 次资源状态保持一致GET、PUT、DELETE 都是幂等的POST 不是。 HTTP 状态码响应语义RESTful API 必须充分利用 HTTP 状态码而不是将错误信息放在 JSON 里返回 200。分类状态码含义使用场景2xx 成功200 OK成功GET、PUT、PATCH 成功201 Created已创建POST 创建资源成功常附带Location头返回新资源 URI204 No Content无内容DELETE 成功或 PUT 更新成功但无需返回 Body3xx 重定向301/302资源移动当 URI 变更时重定向4xx 客户端错误400 Bad Request参数错误或请求格式错误JSON 格式错误、必填字段缺失401 Unauthorized未认证缺少 Token 或 Token 过期403 Forbidden权限不足已登录但无操作权限404 Not Found资源不存在URI 路径错误或资源已被删除422 Unprocessable Entity语义错误参数校验失败如邮箱格式不正确429 Too Many Requests请求过频触发了限流策略5xx 服务器错误500 Internal Server Error服务器内部错误代码异常、数据库连接失败应尽量避免暴露堆栈503 Service Unavailable服务不可用服务宕机或正在重启 成熟度模型Richardson Maturity Model该模型定义了 RESTful API 的 4 个等级用于衡量接口的 REST 纯度Level 0单 URI 单一方法如仅使用POST /api通过 Body 参数区分操作。类似 RPC 风格。Level 1多 URI资源拆分引入资源概念如/users和/orders但依然只使用 POST。Level 2多 URI HTTP 方法正确使用 GET/POST/PUT/DELETE并配合状态码。这是 90% 以上成熟项目停留的等级。Level 3HATEOAS超媒体驱动响应中提供“下一步操作”的链接如 RESTful API 返回订单详情时附带cancel或pay的可执行 URI。这是真正的 REST 风格顶点但实现复杂在现实中常被简化。️ 安全性与认证RESTful API 自身不包含安全机制通常借助 HTTP 语义实现Token 认证最常用的方式。将 JWTJSON Web Token放在请求头Authorization: Bearer token中。OAuth2.0委托授权协议如微信登录。API Key放在请求头或 Query 参数中适用于服务器间调用。强制 HTTPS生产环境必须使用 TLS 加密传输。 高级最佳实践避坑指南字段过滤允许客户端指定返回字段减少冗余传输。GET /users/123?fieldsid,name,email分页与排序分页参数?page2size20偏移量或?cursorabc123limit10游标分页更适用于大数据量。排序?sortage,desc。API 版本控制当接口发生破坏性变更时必须使用版本控制。推荐做法放在 URI 路径中/v1/users这是最直观且清晰的方式常见于 Spring BootRequestMapping配置。备选方案放在 Header 中Accept-Version: v1。响应体结构统一为统一前后端交互推荐包装统一返回格式json{ code: 0, // 业务状态码 message: success, data: { ... }, // 具体的资源数据 timestamp: 1630000000 }注意对于204 No Content情况不应返回 Body。避免“动词”污染 URI严禁出现/api/createUser。应该用POST /api/users。启用 GZIP 压缩对于返回体较大的 JSON 数据压缩可以大幅节省带宽。 RESTful vs 其他常见风格对比维度RESTful APIGraphQLgRPC协议HTTP/HTTPSHTTP/HTTPSHTTP/2数据格式JSON主流 / XMLJSONProtobuf二进制传输效率中等中等请求体可能较大极高二进制序列化性能优势利用 HTTP 缓存单一请求获取复杂嵌套数据减少请求次数高效的二进制传输和流式传输适用场景通用 Web 应用、对外开放 API复杂多端查询BFF 层、数据结构多变的前端微服务间内部通信、低延迟/高性能场景 总结RESTful API 设计的本质是将资源抽象与 HTTP 协议深度融合通过无状态、统一接口和标准状态码构建松耦合、可扩展的系统边界。对于绝大多数业务系统达到Richardson Maturity Model Level 2使用正确 URI、HTTP 方法和状态码并坚持统一响应格式、合理分页和 Token 鉴权即可设计出优秀且规范的 RESTful 接口。Level 3HATEOAS虽然理想但在实际工程中往往因实现成本过高而被适度简化。