API 设计从资源建模开始，而不是从 URL 开始

接口是团队之间的契约。先理解要管理的对象和它们的关系，再设计请求方法、路径、校验规则与错误响应。

围绕资源组织路径

例如文章可以表示为 /api/posts，单篇文章表示为 /api/posts/{id}。HTTP 方法表达常见操作：GET 读取，POST 创建，PUT 或 PATCH 更新，DELETE 删除。

让错误也成为契约的一部分

调用方需要知道请求成功、参数错误、未授权还是资源不存在。选择恰当的状态码，并保持错误响应结构稳定，能减少前后端的猜测与特殊分支。

• 为字段定义明确的类型、必填规则和长度边界。
• 区分身份认证与资源授权，避免只验证“是谁”却不验证“能做什么”。
• 在接口发布后谨慎删除或重命名字段，兼顾仍在使用旧版本的客户端。