REST 与 API 选择
API 怎样成为调用双方的契约？
- API: 应用程序接口，约定请求、参数、结果和错误，使调用方无需知道实现细节也能使用能力;
- 选择依据: 先明确资源、操作、兼容与权限，再比较调用次数、缓存、工具和传输开销;
REST 如何围绕资源提供统一接口？
- REST: 以资源及其表示为核心的架构风格，不是“所有返回 JSON 的 HTTP 接口”的别名;
- 约束: 客户端与服务端分离、无状态、可缓存、统一接口、分层系统，按需代码为可选约束;
- 无状态: 每次请求携带解释该请求所需的上下文，不是服务器不允许存数据库或资源状态;
- 统一接口: 包含资源标识、表示操作、自描述消息和超媒体驱动，可继续学习 HATEOAS;
- 权衡: 通用 HTTP 工具和缓存方便，但固定响应形状可能过量取数，复杂页面可能多次往返;
| HTTP 方法 | 常见语义 |
|---|---|
| GET / HEAD | 获取表示 / 只获取响应头 |
| POST | 提交数据并按资源语义处理 |
| PUT | 创建或整体替换目标资源表示 |
| PATCH | 对资源进行部分修改 |
| DELETE | 请求删除目标资源 |
- 状态码: 1xx 为信息，2xx 为成功，3xx 为重定向，4xx 为请求方错误，5xx 为服务端错误;
- 资源示例:
GET /users/{id}读取用户，POST /users创建用户，路径表达资源、方法表达动作;
如何比较三种接口技术的代价？
| 维度 | REST | GraphQL | gRPC |
|---|---|---|---|
| 核心表达 | 资源 | 字段查询 | 服务方法 |
| 调用次数 | 依资源设计 | 可聚合多个字段 | 依方法粒度与流设计 |
| 缓存 | 易利用 HTTP | 需设计查询及客户端缓存 | 通常在应用层处理 |
| 契约与工具 | 可配合 OpenAPI | 类型模式与工具 | IDL 与代码生成 |
| 兼容演进 | 资源与版本约定 | 字段新增及弃用 | 消息字段与方法兼容 |