Spring Boot中REST API的URL与参数命名规范咨询

问题1：URL使用kebab-case比camelCase更合适，是否属实？ #

属实。REST API的URL遵循Web领域通用规范，kebab-case（短横线分隔）是行业主流命名风格，像GitHub、Stripe等公开API都采用这种方式。它的优势很明确：

• 可读性更强，短横线分隔的单词在URL里比camelCase更容易区分
• 符合URL的语义习惯，Web服务器、代理对短横线的处理更友好，不会出现识别歧义
• 能和代码里的变量命名（通常用camelCase）划清边界，避免混淆

问题2：URL中路径参数用camelCase，其余部分用kebab-case是否规范？ #

这种用法是规范的，也是行业常用实践。原因如下：

• 路径参数本质是业务变量，和代码中的变量命名保持一致（Java变量默认用camelCase），在控制器方法里接收参数时可以直接用@PathVariable String customerId，不需要额外做名称映射，减少代码冗余
• URL静态部分用kebab-case符合URL规范，两者各司其职，既保证了URL的可读性，又保持了代码变量的一致性

问题3：两个接口参数类型相同，无法用@GetMapping("/{userId}")和@GetMapping("/{referenceId}")映射，添加前缀是否为最佳实践？ #

添加资源前缀是非常推荐的最佳实践，也是REST资源导向设计的核心原则之一。

• 这种方式能让URL语义更清晰，比如@GetMapping("/users/{userId}")和@GetMapping("/references/{referenceId}")，一眼就能区分是获取用户资源还是参考记录资源，从根源上避免路由冲突
• 相比用请求参数（比如@GetMapping("/")配合?id=xxx或?reference=xxx）的方案，路径前缀的方式更符合REST的资源定位逻辑，可读性和可维护性更强
• 还有利于后续API扩展，比如后续要加创建用户、创建参考记录的接口，直接沿用/users和/references的前缀即可，保持API风格统一

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