API命名规范直接影响接口的可读性和团队协作效率。一个没有命名规范的团队，接口名称五花八门，前端联调痛苦不堪。本文总结多年实战中沉淀的API命名规则，涵盖URL、参数和响应字段三个维度，帮助团队建立统一标准。
URL命名规则
URL命名采用小写字母加连字符的组合风格，例如 /user-orders 而不是 /userOrders 或 /user_orders。路径中的单词用连字符分隔比下划线更易读，也比驼峰更符合URL规范。资源名统一使用复数形式，比如 /users 而不是 /user。版本号放在URL前缀中，如 /v1/users。路径参数用花括号包裹，如 /users/{userId}。查询参数使用小驼峰，如 ?pageSize=20&sortBy=createTime。
请求参数命名
请求参数分为路径参数、查询参数和请求体参数三种。路径参数用于标识特定资源，如 userId、orderId。查询参数用于过滤、排序和分页，分页参数统一用 page 和 pageSize，排序用 sortBy 和 sortOrder。请求体中的字段使用小驼峰命名法，如 userName、createTime。布尔类型参数用 is/need/has 开头，如 isActive、needPagination。时间参数统一用时间戳或ISO8601格式。
响应字段规范
响应体包含数据字段和元数据字段。数据字段直接返回资源对象或数组，字段名使用小驼峰。元数据放在顶层，包含 code、message 和 requestId。列表接口额外包含 total、page、pageSize 分页信息。错误响应统一格式为 { code: 错误码, message: 错误描述, details: 具体错误详情 }。响应中不含 null 值的字段建议省略，减少传输数据量。时间字段统一返回 ISO8601 字符串格式。