API 设计规范：从可用到可维护

API 设计规范：从可用到可维护

好 API 不只是能返回数据，还要让调用方容易理解、容易排错，并且能在业务增长后平滑演进。

资源命名

优先使用名词表示资源，例如 /users、/orders，避免把实现细节暴露在路径中。

状态码

200 表示成功，201 表示创建成功，401/403 表示认证或权限问题，404 表示资源不存在，409 表示版本或状态冲突。

分页与筛选

列表接口应明确默认页大小和最大页大小，并对搜索词与排序字段做白名单校验。

幂等与版本

写入动作要支持幂等键。破坏性变更使用新版本，非破坏性字段保持向后兼容。