API接口命名该用中划线还是下划线？

Question

在设计RESTful API时，路径命名常面临使用中划线（kebab-case）还是下划线（snake_case）的选择问题。例如，应定义为 `/get-user-info` 还是 `/get_user_info`？虽然两者在技术上均可正常工作，但业界更推荐使用中划线，因其符合HTTP URI的可读性与规范惯例（如RFC 3986）。许多主流API（如GitHub、Google APIs）均采用kebab-case。而snake_case更多用于变量命名（如JSON响应体中的字段）。混淆使用风格可能导致接口不一致，影响可维护性与客户端调用体验。因此，统一命名风格至关重要。应优先选择中划线用于URL路径，下划线保留在数据载荷中，以保持清晰的语义分离与行业一致性。

Answer 1

RESTful API 路径命名规范：中划线 vs 下划线的深度解析

1. 命名风格的基本概念与常见形式

在设计 RESTful API 时，路径命名风格的选择直接影响接口的可读性、一致性和维护成本。常见的命名风格包括：

• kebab-case（中划线）：如 /get-user-info
• snake_case（下划线）：如 /get_user_info
• camelCase：如 /getUserInfo
• PascalCase：如 /GetUserInfo

尽管这些格式在技术实现上均无问题，但其语义和适用场景存在显著差异。

2. URI 设计原则与 RFC 3986 规范支持

RFC 3986 是定义统一资源标识符（URI）的标准文档，虽未强制规定命名风格，但推荐使用小写字母和连字符来增强可读性与互操作性。

风格	符合 RFC 推荐	可读性	文件系统友好
kebab-case	✅ 强烈推荐	高	是
snake_case	⚠️ 可接受但非主流	中	部分系统不友好
camelCase	❌ 不推荐	低（大小写易混淆）	否

从协议层面看，kebab-case 更贴近标准对“分隔符清晰”的隐含要求。

3. 主流平台实践分析

观察行业领先者的 API 设计有助于形成最佳实践共识：

1. GitHub API：https://api.github.com/user/repos 使用 kebab-case 和小写路径
2. Google APIs：https://www.googleapis.com/storage/v1/buckets 完全采用小写+中划线
3. Stripe API：https://api.stripe.com/v1/customers 路径简洁且无下划线
4. Twitter API v2：/tweets/search/recent 遵循资源层级与 kebab-case

可以看出，顶级服务普遍避免使用 snake_case 在 URL 路径中。

4. 技术细节对比：解析、路由与安全性

// 示例：Express.js 中两种风格均可正常匹配
app.get('/get-user-info', (req, res) => { ... });   // ✅ 推荐
app.get('/get_user_info', (req, res) => { ... });   // ⚠️ 不推荐

然而，在反向代理（如 Nginx）、CDN 缓存或日志分析系统中，下划线可能被特殊处理（例如某些配置默认忽略 "_"），导致潜在行为不一致。此外，DNS 和域名本身不区分大小写但对符号敏感，kebab-case 更具兼容性。

5. 语义分离原则：路径 vs 数据载荷

一个成熟的 API 设计应遵循关注点分离原则：

图：路径使用 kebab-case，响应体使用 snake_case 实现清晰语义隔离

这种分工既满足前端调用便利（JS 可自动转换 camelCase），也适配后端数据库字段习惯（Python/Django 常用 snake_case）。

6. 团队协作与规范制定建议

为确保长期一致性，建议在团队内部建立 API 设计手册，明确以下规则：

• 所有公开 API 路径必须使用 kebab-case
• 查询参数允许使用 snake_case（如用于兼容旧系统）
• JSON 响应体字段统一使用 snake_case（或根据客户端需求提供 camelCase 映射）
• 禁止混合使用多种风格于同一资源层级

可通过 Swagger/OpenAPI 文档工具进行自动化校验。

7. 演进式架构中的命名策略迁移

对于已有系统若存在命名混乱，可采用渐进式重构策略：

graph LR A[旧路径 /get_user_info] --> B[新增重定向 /get-user-info → 301] B --> C[双写期：同时支持两种路径] C --> D[废弃旧路径并更新文档] D --> E[完全切换至 kebab-case]

此方式保障平滑过渡，不影响现有客户端。