RESTful 把一切视为资源，用 URL 定位资源、用 HTTP 方法表达操作（GET/POST/PUT/DELETE）。资源建模得好，接口自然清晰、可预测。
相比“动作式接口”（/getUser），资源式接口（/users/1）更规范、更利于复用与演进。
设计原则：URL 只描述资源，方法表达动作；返回结构统一，错误信息可读。
把接口做规范的关键。
名词化、层级化、可预测。
2xx/4xx/5xx 正确表达。
统一的分页与筛选参数。
向后兼容的演进策略。
OpenAPI 自动生成文档。
契约测试与自动化验证。
从需求到契约。
识别业务实体与操作，确定资源边界与关系。
定义 URL、方法、请求响应结构、错误格式。
用 OpenAPI 描述接口，自动生成可交互文档。
接口测试 + 契约测试，版本演进保持兼容。
规范使用 HTTP 方法。
| 方法 | 语义 | 是否幂等 |
|---|---|---|
| GET | 读取资源 | 是 |
| POST | 创建/处理 | 否 |
| PUT | 整体更新 | 是 |
| PATCH | 部分更新 | 是 |
| DELETE | 删除 | 是 |
常用方案：URL 路径版本（/v1/users）、请求头版本。选择一种统一用，重大变更升版本，保持向后兼容。
统一错误结构：code、message、details，配合合适的状态码。让前端能区分“参数错/未授权/不存在”。
前端取数需求多变、字段裁剪要求高的场景，GraphQL 更灵活；常规 CRUD 用 REST 更简单。
用 OpenAPI 从代码生成，避免文档与实现脱节。文档即契约，测试与联调都基于它。
