接口命名应以资源为中心使用复数名词小写连字符路径，动词由HTTP方法承担；层级嵌套不超过三层；版本显式置于路径如/api/v1/；响应统一结构并严格遵循HTTP状态码语义。

接口命名不是“起个名字”那么简单，而是定义系统语义、约束协作边界、降低理解成本的第一道防线。核心就一条：让路径本身说话，而不是靠文档或口头解释。

资源为中心，只用名词复数

URL 不表达动作，只标识资源。动词交给 HTTP 方法去承担。

• ✅ 正确：/users、/orders、/product-categories
• ❌ 错误：/getUser、/createOrder、/deleteUserById、/user/list
• 小写 + 连字符（-）是通用安全选择，避免下划线（_）、驼峰（userOrders）或大小混写（UserOrders）
• 复数形式体现集合性，即使单条查询也属于该资源的一个实例（如 /users/123）

层级清晰，嵌套不过三

资源之间有自然归属关系时，用路径嵌套表达，但要克制。

• ✅ 合理：/users/{userId}/orders（用户下的订单）
• ✅ 合理：/orders/{orderId}/items（订单下的商品项）
• ❌ 过深：/users/{u}/orders/{o}/items/{i}/details —— 可读性差、路由难维护、客户端构造易错
• 替代方案：用查询参数过滤，如 /items?orderId=123&userId=456

版本控制必须显性化

不加版本的接口等于没有契约。业务一变，旧客户端立刻崩。

• 推荐方式：/api/v1/users、/api/v2/users（路径中带 v{数字}）
• 备选方式：通过 Accept 头（如 application/vnd.myapp.v2+json），适合多格式共存场景
• 禁止把版本藏在参数里（如 /users?version=2），无法被网关、CDN、日志系统有效识别
• v1 发布后，v0 不应立即下线，保留至少一个大版本周期做兼容过渡

统一响应与错误语义

命名规范不止于 URL，还延伸到数据契约层面。

• 所有成功响应统一结构：{ "code": 200, "message": "ok", "data": {...} }
• HTTP 状态码严格匹配语义：201（创建成功）、204（删除成功）、400（参数错）、404（资源不存在）、422（校验失败）、500（服务异常）
• 错误信息不暴露技术细节（如数据库字段名、堆栈），只返回可操作提示（如 “手机号格式不正确”）
• 列表接口默认支持分页参数：?page=1&size=20，不强制要求，但提供即统一