直接用 gin.default() 创建路由引擎后，调用 r.get、r.post、r.put、r.delete 等方法注册对应 http 方法的接口，首参为路径（支持 /user/:id 等参数），次参为处理函数；务必调用 r.run() 启动服务。
怎么配 Gin 的 r.GET、r.POST 等基础路由
直接用 gin.Default() 创建引擎后，调用 r.GET、r.POST、r.PUT、r.DELETE 就能注册对应 HTTP 方法的接口。每个方法第一个参数是路径（支持路径参数，如 /users/:id），第二个是处理函数。
常见错误：把 r.POST("/user", handler) 写成 r.GET("/user", handler) 却用 POST 请求测试，返回 404；或者路径末尾多写斜杠（/user/ 和 /user 是两个不同路由）。
- 路径参数用冒号声明，取值用
c.Param("id") - 查询参数用
c.Query("key")或c.DefaultQuery("key", "default") - POST 表单数据用
c.PostForm("field")；JSON 体需先BindJSON到结构体 - 别漏掉
r.Run(":8080")，否则服务根本没启动
为什么 r.Group 要配合前缀和中间件一起用
真实项目里不会把所有路由平铺在根引擎上。r.Group("/api/v1") 返回一个子路由组，后续所有 .GET、.POST 都自动带 /api/v1 前缀。更重要的是，它能局部挂载中间件——比如只给 /api/v1/admin 加鉴权，不影响 /api/v1/public。
容易踩的坑：在 group 里调用 r.Use(middleware)（用了全局引擎变量），结果中间件作用到整个服务；正确写法是 adminGroup := r.Group("/admin"); adminGroup.Use(authMiddleware)。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- group 不会继承父级中间件，必须显式调用
.Use() - 多个 group 可嵌套，但路径前缀会叠加，比如
r.Group("/v1").Group("/users")对应/v1/users - 不要在 group 外部定义 handler 函数再传入，闭包捕获外部变量容易引发并发问题
r.Run() 启动时端口被占或绑定失败怎么办
r.Run() 默认监听 :8080，如果该端口正被占用，程序 panic 并输出 listen tcp :8080: bind: address already in use。这不是 Gin 的 bug，而是底层 net.Listen 的系统错误。
解决方式不是硬改端口重试，而是提前检查或交由环境控制：
- 用
r.Run("0.0.0.0:6666")显式指定非默认端口（参考知识库中ServerOptions.Addr的配置习惯） - 从环境变量读取：
os.Getenv("PORT")，没设则 fallback 到":8080" - 启动前用
net.Listen("tcp", addr)尝试监听并关闭，快速判断端口可用性（适合 CLI 工具场景） - 注意
0.0.0.0和127.0.0.1的区别：前者允许外部访问，后者仅本机
Swagger 文档注释加在哪、swag init 生成失败怎么查
Swagger 注释必须写在 handler 函数上方，且以 // @ 开头（如 // @Summary），不能写在路由注册行或函数内部。swag init 扫描的是 Go 源码注释，不是运行时行为。
最常卡住的点：没导入生成的 docs 包，或 swag init 执行路径不对。
- 确保执行
swag init时当前目录是模块根目录（含go.mod） - 生成后必须在 main 包中
import _ "your-module-name/docs"（下划线导入，触发init()） -
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))这一行不能漏，且路径必须是/swagger/*any - 修改注释后必须重新运行
swag init，不会自动热更新
