RESTful API
RESTful，即REST 风格（Representational State Transfer），是一种设计网络 API 的架构风格，由计算机科学家 Roy Fielding 在 2000 年提出。它基于 HTTP 协议，强调接口的统一性、无状态性和可缓存性，已成为现代 Web 服务的主流设计范式。
一、核心原则
- 平台无关性：客户端可跨平台调用 API，无需了解服务内部实现。通过 HTTP 作为标准协议，使用 JSON/XML 等通用数据格式，并提供清晰文档实现。
- 松耦合：客户端与服务可独立演化，互不依赖对方的内部逻辑。通过标准协议和数据格式协商机制确保双方协作。
二、核心概念
- 资源与 URI：资源是 API 操作的对象（如订单、用户），每个资源由唯一的 URI 标识（例如
https://api.example.com/orders/1代表编号为 1 的订单）。 - 资源表示：资源通过 JSON、XML 等格式传输，客户端通过 URI 请求资源，服务返回对应的数据（例如 GET 请求上述 URI 可能返回
{"orderId":1,"price":99.9}）。 - HTTP 方法：用标准 HTTP 方法定义对资源的操作，如
GET（获取）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）。 - 无状态：每个请求独立，服务不存储客户端状态，所有信息都包含在请求和资源中，支持高可扩展性。
- 超媒体链接（HATEOAS）：资源表示中包含超链接，指引客户端访问相关资源或执行操作（例如订单信息中可能包含指向对应客户的查询链接）。
三、设计要点
- URI 设计
- 用名词表示资源（如
/orders而非/create-order），因 HTTP 方法已隐含操作语义。 - 集合用复数名词（如
/customers表示客户列表，/customers/5表示单个客户），避免复杂层级（如不建议/customers/1/orders/99/products）。 - 不暴露数据库结构，通过抽象层隔离 API 与底层存储，防止数据泄露。
- HTTP 方法与状态码
GET：获取资源，成功返回 200（OK），资源不存在返回 404（Not Found）。POST：创建资源，成功返回 201（Created，含新资源 URI），无效请求返回 400（Bad Request）。PUT：全量更新资源，需幂等（多次请求结果一致），冲突返回 409（Conflict）。PATCH：部分更新资源，仅传输修改内容（如通过 JSON 补丁指定字段变更），格式错误返回 400（Bad Request）。DELETE：删除资源，成功返回 204（No Content）。- 其他关键设计
- 异步操作：耗时任务返回 202（Accepted），并提供状态查询接口（通过 Location 头指定）。
- 分页与过滤：通过
limit（返回数量）和offset（起始位置）分页，通过查询参数（如?status=shipped）过滤数据，减少无效传输。 - 版本控制：支持通过 URI（如
/v2/orders）、查询参数（如?version=2）或请求头指定版本，确保旧客户端兼容。 - 多租户支持：通过子域名、自定义头（如
X-Tenant-ID）或 URI 路径（如/tenants/xxx/orders）隔离不同租户资源。 - 可追踪性：通过
Correlation-ID等请求头追踪分布式系统中的请求流转，便于问题排查。
四、成熟度与规范
- 成熟度模型：从低到高分为四级，Level 3 为完全符合 REST 定义，需支持 HATEOAS；多数实际 API 处于 Level 2（使用 HTTP 方法操作资源）。
- OpenAPI 规范：标准化 API 描述，提倡 “契约优先” 设计（先定义接口再实现），可自动生成文档和客户端代码，提升开发效率。
发表评论