getOrder、orderGet、query_order 各写各的，前端对接全靠问，接口文档过期。
没有版本管理，后端改字段结构直接破坏线上，前端连夜加班返工。
永远返回"操作失败"或一堆堆栈，前端不知道错在哪，用户体验一塌糊涂。
用名词表示资源（/users、/orders/123），动词由 HTTP 方法承担。
200/201/400/401/404/500 各归其位，调用方一眼看懂结果。
data/code/message 一致的包裹结构，前端解析逻辑统一。
URL 或 Header 携带版本号，破坏性变更走新版本，向后兼容。
OpenAPI/Swagger 自动生成文档，前后端与第三方按契约协作。
鉴权、HTTPS、限流、参数校验，安全是 API 的第一属性。
状态码是接口的"第一句话"，用对状态码，问题定位快一半。
| 状态码 | 含义 | 典型场景 |
|---|---|---|
| 200 | 成功 | GET 查询、更新成功 |
| 201 | 已创建 | POST 新建资源 |
| 204 | 无内容 | 删除成功、空响应 |
| 400 | 参数错误 | 校验失败、格式不对 |
| 401 | 未认证 | 未登录 / Token 失效 |
| 403 | 无权限 | 已登录但无权访问 |
| 404 | 资源不存在 | URL 或资源未找到 |
| 409 | 冲突 | 重复提交、状态冲突 |
| 429 | 限流 | 请求过于频繁 |
| 5xx | 服务端错误 | 500 内部错误 / 502 网关 / 503 不可用 |
返回 code + message + 字段级错误详情（fieldErrors），前端能精确定位并友好提示。
统一 page/size/sort/filter 参数，响应返回 total 与分页信息，避免前端各自发明。
写操作支持幂等键，配合超时重试，网络抖动也不产生重复数据。
JWT/OAuth 统一鉴权，按用户/IP 限流防刷，关键接口审计日志。
规范 API 是前后端并行开发、高效联调的前提，也是团队协作的基石。
对外提供能力，清晰稳定的 API 决定开发者是否愿意接入。
Web、App、小程序共用一套 API，设计一致性降低多端成本。
服务间接口规范统一，配合契约测试保证分布式协作可靠。
