接口命名规范核心是见名知意、统一可读、符合语义；url以名词复数开头、kebab-case分隔、不带动词；http方法严格对应语义；字段用snake_case；响应统一list/total结构；版本走路径，非标操作单独定义。

接口命名规范的核心是“见名知意、统一可读、符合语义”，不是越短越好，也不是越复杂越专业，而是让调用方一眼看懂资源是什么、操作是什么、层级关系在哪。

URL 路径要体现资源与动作语义

路径以名词复数开头，用 kebab-case（短横线分隔），不带动词前缀。例如：

• /api/v1/users —— 用户集合，不是 /api/v1/getUsers
• /api/v1/users/123/orders —— 用户 123 的订单列表，层级清晰且不超过三级
• /api/v1/orders/batch-cancel —— 批量取消订单，特殊动作用 batch- 前缀标识

HTTP 方法必须严格对应业务意图

别用 POST 包打天下，每个方法承载明确语义：

• GET：只用于查询，不修改状态，参数放 query string
• POST：新增资源，或执行非幂等动作（如 /users/123/disable）
• PUT：全量替换，客户端提供完整对象
• PATCH：局部更新，只传需改的字段（如 { "is_active": false }）
• DELETE：删除资源，不带请求体

参数和字段命名保持风格一致

字段名用 snake_case，布尔值加 is_ 或 has_ 前缀，避免拼音或缩写：

• ✅ user_name、is_deleted、created_at
• ❌ userName（混用驼峰）、delFlag（无意义缩写）、shanchu（拼音）
• 响应中列表统一为 list + total 结构，如：{"list": [...], "total": 42}

版本与扩展动作要有明确标识

大版本走 URL 路径，小迭代不升级；非标准操作不塞进 CRUD，单独定义：

• 版本写成 /api/v2/users，不写成 /api/users?version=2
• 支付订单写成 POST /api/v1/orders/789/pay，而不是在 /orders/789 下 PATCH status=paying
• 搜索接口用 GET /api/v1/users?keyword=jack&status=active，不用 POST + body