设计restful api路由需遵循语义化命名、合理嵌套、复数形式、版本控制等原则。首先使用名词而非动词命名资源，如推荐写法：/users、/posts，避免出现操作描述；其次通过http方法表达动作，如get获取、post创建、put更新、delete删除；接着对关联资源合理嵌套，如get /users/123/posts，但避免三层以上嵌套；同时统一使用复数形式如/users保持一致性；此外建议在url中加入版本号如/v1/users以支持演进；最后注意使用连字符分隔单词、id简洁、查询参数用于过滤排序等细节。
在用 Golang 构建 RESTful API 时，设计资源路由是整个架构中非常关键的一环。好的路由设计不仅让接口清晰易懂，也方便后期维护和扩展。接下来我们从实际开发角度出发，聊聊怎么设计出符合最佳实践的资源路由。
使用语义化的资源命名
RESTful 的核心理念之一就是“资源”，而 URL 应该反映这些资源的结构。所以尽量使用名词而不是动词，避免在路径中出现操作行为的描述。
建议：
立即学习“go语言免费学习笔记（深入）”；
- ✅ 推荐写法：
/users
、/posts
、/comments
- ❌ 不推荐写法：
/getAllUsers
、/createPost
URL 应该表示资源的位置，而不是执行的动作。动作应该由 HTTP 方法（GET、POST、PUT、DELETE）来表达。
举个例子：
// 获取所有用户 GET /users // 获取某个用户 GET /users/123 // 创建用户 POST /users // 更新用户 PUT /users/123 // 删除用户 DELETE /users/123
这样设计的好处是统一、直观，并且容易与其他系统对接。
合理嵌套资源关系
当资源之间存在关联时，可以通过嵌套路由来体现这种关系。比如一个用户有很多帖子，可以这样设计：
GET /users/123/posts
这表示获取 ID 为 123 的用户的所有帖子。
但注意不要过度嵌套，两层已经足够清晰。三层以上会增加理解成本，也不利于维护。
例如：
- ✅
/users/123/posts/456/comments
- ⚠️ 尽量避免：
/users/123/posts/456/comments/789/replies
如果确实需要处理更深层的关系，可以考虑用查询参数来简化路径。
使用复数形式保持一致性
RESTful API 中的资源名通常使用复数形式，这是社区普遍接受的做法。它能更好地表达集合概念，也更容易让人理解。
例如：
- ✅
/users
表示多个用户 - ✅
/user
则可能让人误以为是一个单例资源
虽然技术上不影响功能，但统一使用复数可以让整个 API 看起来更规范、专业。
合理使用版本控制
API 是会演进的，为了保证向后兼容性，最好一开始就加上版本号。常见做法是在 URL 或请求头中加入版本信息。
URL 中加版本号（推荐）：
/v1/users /v2/users
这种方式简单直接，便于缓存、日志等系统的识别和处理。
如果你希望更灵活地控制版本，也可以通过
Accept请求头来做内容协商，但这对客户端要求更高，实现起来也更复杂一些。
其他实用小技巧
-
使用连字符分隔单词：比如
/user-profiles
而不是/userProfiles
，更易读。 - 避免使用下划线：虽然技术上没问题，但部分系统或代理可能对大小写敏感，容易出问题。
-
ID 字段保持简洁：如
/users/123
比/users?id=123
更适合用于获取单一资源。 -
查询参数用于过滤排序等：例如
/users?role=admin&sort=name
，这样不会污染路径结构。
基本上就这些。设计好资源路由不难，关键是遵循一套清晰的规则，并在整个项目中保持一致。只要一开始就有意识地规划，后续维护起来就会轻松很多。
