RESTful API 命名规范核心是资源导向：URI 用复数名词标识资源（如/users），不用动词；路径全小写、短横线分隔（如/user-profiles）；嵌套不超过两层（如/users/{id}/orders）；版本显式置于路径前（如/api/v1/users）。
RESTful API 的命名规范核心是“资源导向”——URI 只标识**什么**，不描述**怎么做**。动词交给 HTTP 方法（GET/POST/PUT/DELETE），名词交给路径本身。规范得当，接口自然清晰、易懂、易维护。
资源用复数名词，不用动词
URI 表达的是资源本身，不是动作。重点是“用户”“订单”“商品”，不是“获取用户”“创建订单”。
- ✅ 正确：/users、/orders、/products
- ❌ 错误：/getUser、/createOrder、/listProducts
把操作语义放进路径，会破坏统一接口原则，也容易导致同一资源多个入口（比如 /users 和 /getAllUsers），增加维护负担。
路径全部小写，单词间用短横线（kebab-case）
避免大小写敏感问题和视觉混淆，统一风格提升可读性与协作效率。
- ✅ 推荐：/user-profiles、/order-items、/api/v1/product-categories
- ❌ 避免：/UserProfile（驼峰）、/user_profiles（下划线）、/API/V1/Users（大小混用）
嵌套层级合理，一般不超过两层
体现资源从属关系时可用嵌套，但过深会降低可读性、增加路由复杂度，也违背“简洁即可靠”的工程直觉。
- ✅ 合理：/users/{id}/orders（某用户的订单）
/orders/{id}/items（某订单的条目） - ❌ 过深：/users/123/orders/456/items/789/attributes（四层以上，应拆解或用查询参数替代）
若需更复杂关联，优先考虑用查询参数表达，例如：/items?order_id=456&status=shipped。
版本控制显式体现在 URI 中
API 迭代不可避免，版本号前置到路径（如 /api/v1/users）是最直观、兼容性最好的方式。
- ✅ 明确：/api/v1/users、/api/v2/users（v2 可调整字段、状态码或行为）
- ❌ 模糊：/users?version=2（不易缓存、日志难追踪）、Accept: application/vnd.myapp.v2+json（Header 版本化对前端不友好）
注意：v1 应尽早锁定，避免频繁 breaking change；新功能尽量向后兼容，非必要不删字段。
