RESTful API 接口设计标准及规范（CSDN 笔记）
ABSTRACT
2019-01 CSDN 文章（2021-09 收藏）。一套完整的 RESTful API 设计规范：URI 规则、HTTP 方法与幂等性、请求格式与内容协商、响应约定、错误处理、服务型资源、异步任务、版本演进十个方面。
核心要点
- REST 是一组架构约束与原则，不创造新技术；核心是更好地使用 Web 现有标准，理论上不绑定 HTTP（但 HTTP 是目前唯一实例）。
- URI 即资源：小写、用中杠不用下杠、名词复数表集合；
/zoos/1表单个资源，/zoos/1;2;3表多个。 - 避免层级过深：
/zoos/1/areas/3/animals/4改用查询参数/animals?zoo=1&area=3；组合实体（如 User 的 Address）必须经父实体 id 导航。 - HTTP 方法对应 CRUD：GET 查询、POST 向集合创建、PUT 全量更新、PATCH 部分更新、DELETE 删除。
- 安全性与幂等性：GET 安全且幂等；POST 皆否；PUT/DELETE 幂等但不保证反复请求返回相同响应（如二次 DELETE 返回 404 合法）。
- 复杂查询参数化：过滤、排序（
?sort=age,desc）、投影、分页（limit/offset）；高频复杂查询可做 bookmark 标签化。 - 请求体只用三种格式：application/json、x-www-form-urlencoded、multipart/form-data；内容协商用 Accept 头或 URL 后缀。
- 响应约定：body 直接是数据不做多余包装；DELETE 返回空；时间用毫秒长整型；不传 null 字段；分页带 paging 元信息。
- 错误处理：出错不得给 2xx（防客户端缓存）；用标准状态码（400/401/403/404/500/503）；Controller 层统一异常拦截——业务异常用其指定状态码与文案，非业务异常统一 500 + 线上通用文案。
- 服务型资源（搜索、计算、批量推送）：把服务看作资源，计算结果是资源的表示，按属性选 HTTP 方法。
- 异步任务：返回任务资源（含状态），客户端轮询
/task/3或/task/3/status组合资源。 - 版本演进：URL 放版本（/v1/）最明显实用；失效 API 返回 404/410，迁移返回 301。
关键实体与概念
REST、URI、幂等性、安全性、内容协商、状态码、统一异常拦截、组合资源、API 版本化
关联概念
来源回溯
- 原始文件：
raw/ip/wechat_articles/RESTful API接口设计标准及规范；_时光偏执的博客-CSDN博客.md（原文 2019-01-12，收藏 2021-09-18）
时效性评估
- 仍有效：RESTful 核心规范（URI 设计、幂等性、状态码、错误处理）至今是后端 API 设计的主流基线。
- 已过时：GraphQL、tRPC、gRPC 在特定场景分流了 REST 的份额；「body 不包装」一条在国内实践中常被统一
{code, data, message}信封替代（便于网关与前端统一处理），属规范取舍而非对错；OpenAPI/Swagger 文档化已成标配，本文未涉及。