RESTful API查询参数命名规范及最佳实践问询

通用核心原则 #

• 语义优先：参数名要直观反映对应含义，避免使用无意义的缩写，除非是行业通用缩写（比如page、page_size这类普遍认可的命名）
• 全局统一：整个API体系内的命名规则必须完全一致，不要出现部分接口用小驼峰、部分用蛇形命名的情况，避免调用方混淆
• 规避特殊字符：不要使用空格、以及@/#/&这类本身在URL中具备特殊含义的字符作为参数名组成部分，防止转义出错导致参数解析失败
• 避开保留字：不要使用HTTP协议、常用Web框架的保留关键字作为参数名，比如default、delete这类，避免和框架内置逻辑冲突

命名风格选型建议 #

目前主流的四种命名风格的适配场景如下：

• PascalCase（大驼峰）：几乎不会用于查询参数命名，该风格一般仅用于类名、类型名的代码定义，放在URL中不符合通用API设计习惯，辨识度低
• camelCase（小驼峰）：仅适合Java/JavaScript技术栈且无外部开发者调用的内部API场景，优势是参数名和代码变量名完全一致，不需要额外做映射转换；但存在兼容性隐患：部分老旧反向代理、网关会自动将URL中的大写字母转为小写，导致参数匹配失败
• kebab-case（短横线命名）：多用于URL路径段的命名，不推荐用于查询参数，因为短横线在绝大多数编程语言中不能作为合法变量名，服务端接收参数时需要额外做映射处理，增加不必要的开发成本
• snake_case（蛇形命名）：是当前行业内最通用的查询参数命名方案，适配所有编程语言的变量命名规则，不需要额外做转换，且全小写的格式完全规避了大小写敏感的问题，兼容性最好，GitHub、Stripe等主流公网开放API均采用该方案。如果团队没有特殊的历史技术包袱，优先选择该方案。

URL最终呈现形式 #

查询参数全小写、单词之间以下划线分隔，不需要任何大写字母，也不需要额外转义，示例如下：
https://api.example.com/v1/users?page=1&page_size=20&is_active=true&created_after=1698768000

内容的提问来源于stack exchange，提问作者user1354825