Gin框架RESTful接口设计需遵循五项规范：1.路径用复数名词且嵌套≤2层；2.HTTP方法严格绑定操作语义；3.路径参数须转换校验；4.版本控制置于路径首级；5.查询参数小写下划线命名，错误响应用标准HTTP状态码。
设计Gin框架的RESTful接口路径时，必须让客户端仅凭URL和HTTP方法就能准确理解资源操作意图，避免出现/getUserById或/updateOrderStatus这类动词式路径——这类写法会让权限控制失效、缓存策略混乱、Swagger文档无法自动生成、前端SDK难以泛化封装。
资源路径必须用复数名词，且禁止嵌套过深
第一步：所有顶层资源路径使用英文复数形式，如/users、/products、/orders，哪怕只操作单个实例也保持复数，因为REST语义中/users/123表示“users集合中的第123号成员”，不是“user单数资源”。
第二步：嵌套层级严格限制在两层以内。允许/users/123/posts（用户拥有的文章），但禁止/users/123/posts/456/comments/789/likes——这种路径已超出REST表达力，应拆为独立资源/likes?post_id=456&comment_id=789或聚合接口/posts/456/summary。
第三步：避免静态路径与参数路径注册顺序错误。若同时存在/users/me和/users/:id，必须先注册/users/me，否则:id会匹配me字符串并传入handler，导致逻辑错乱。
HTTP方法语义必须严格绑定操作类型
GET /users → 获取用户列表，支持分页参数?page=1&limit=20，不可修改数据，响应可被CDN缓存。
POST /users → 创建新用户，成功后返回201 Created状态码，并在Location头中写入新资源路径/users/123。
PUT /users/:id → 全量替换指定用户，要求客户端提交完整字段；若仅需局部更新，改用PATCH。
DELETE /users/:id → 幂等删除，无论调用几次都返回204 No Content，而非404 Not Found——资源不存在本身已是合法状态。
【路径参数提取后必须转换并校验】直接使用c.Param("id")返回的字符串调用数据库查询，可能触发strconv.Atoi panic或SQL注入；务必用strconv.ParseUint(c.Param("id"), 10, 64)并检查error。
版本控制必须放在路径第一级
方法一：采用路径前缀/v1/users，配合Gin Group实现：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
v1 := r.Group("/v1")→v1.GET("/users", handler)→v1.POST("/users", handler)
方法二：禁用/api/v1/users或/users/v1——前者冗余/api前缀，后者破坏资源稳定性；更不能用查询参数/users?version=v2，因CDN和反向代理无法区分缓存键。
注意：版本升级时，旧版路由不得直接删除，而应保留至少一个大版本周期，通过中间件记录deprecated调用日志。
查询参数命名统一小写下划线
过滤用?status=active&category_id=5，排序用?sort_by=created_at&order=desc，分页用?page=2&per_page=15。
禁止驼峰式sortBy或混合大小写CategoryID，Gin默认不自动转换字段名，前端传sort_by后端结构体必须定义SortBy string `form:"sort_by"`才能正确绑定。
这一步操作起来很简单，直接把查询参数名写成小写下划线格式就行。
错误响应必须用标准HTTP状态码
资源不存在返回http.StatusNotFound(404)，别用200加{"code":404,"msg":"not found"}——fetch API的.catch()不会捕获这种“成功状态码+业务错误”的响应，前端重试逻辑直接失效。
业务校验失败（如邮箱格式错误）返回http.StatusUnprocessableEntity(422)，比400 Bad Request语义更精准。
数据库连接失败返回http.StatusServiceUnavailable(503)，而非500 Internal Server Error——后者应仅用于未捕获panic，便于SRE快速定位崩溃点。
