第19章：路由注册与版本分组
本章分析 internal/routes/v1/routes.go 与 v2/routes.go：路由的注册风格（函数式批量注册而非散装 r.GET）、鉴权分组的组织方式、路由顺序的陷阱规避，以及 API 面的全景图。路由文件是 API 的目录页，读完本章可按图索骥找到任何接口的 handler。
流程
路由注册发生在 main 装配的末端：r.Group("/openapi/live-mixer") 建立统一前缀，v1/v2 各自 RegisterRoutes(api.Group("/v1")...)。RegisterRoutes 接收已构造好的全部 handler 实例作为参数——路由函数只做「路径→方法」的映射，不做任何构造；依赖装配全部留在组合根（第 5 章），路由层保持纯声明。
v1 的注册结构分两段：
- 免鉴权段：
POST /auth/login（登录）、POST /asr（同步转写）、POST /chat（同步对话）——三个都是「拿到结果就走」的同步接口。 - 鉴权段：
authorized := rg.Group("", middleware.JWTAuth(jwtSecret))，其下按资源分五组：accounts、live-materials、llm-system-prompts、video-projects、tasks。
一个被注释显式记录的顺序陷阱：tasks 组里 /ai-slice、/draft、/ai-slice-draft 三个具体路径必须注册在 /:id 之前——Gin 的路由树会把 GET /tasks/ai-slice 匹配到 /tasks/:id（如果 :id 先注册），注释原文「具体路径须注册在 /:id 之前，避免被当成 id」。这类坑写进注释，是给未来加路由的人留的路标。
实现
API 全景（v1）：
| 资源 | 路径 | 能力 |
|---|---|---|
| 认证 | POST /auth/login | 登录换 token |
| 同步 | POST /asr · POST /chat | 直通 ASR / LLM |
| 账号 | /accounts CRUD | 管理员维护账号 |
| 素材 | /live-materials CRUD + asr/retry + asr/subtitle + video-projects | 素材与 ASR 联动 |
| 提示词 | /llm-system-prompts CRUD | 切片策略管理 |
| 项目 | /video-projects CRUD + running-tasks | 加工单 |
| 任务 | POST /tasks/ai-slice·draft·ai-slice-draft + GET /tasks(/:id) | 异步任务入口与轮询 |
设计细节：
- 版本分组即演进策略：v2 目前只有账号接口（
v2/routes.go），与 v1 并行注册、互不影响。不兼容改动走新版本目录（handler/v2 + routes/v2），老版本保持冻结——比在 v1 里加 flag 语义清晰得多。 - 素材接口的联动子资源：
POST /:id/asr/retry（失败重跑）、GET /:id/asr/subtitle（字幕下载）体现了「ASR 是素材的一部分」的领域建模；GET /:id/video-projects挂在素材下则是「从素材查项目」的反向导航。 GET /:id/running-tasks挂在项目组：前端在项目页展示「该项目运行中任务」，避免全量拉任务列表再过滤。- handler 签名一致性：所有 handler 构造函数形如
NewXxxHandler(svc, accountRepo)——service + 查 created_by 用的账号仓储，是横切关注点的统一注入模式。 - 路由测试
routes_test.go直接构造 gin engine + stub handler 断言路由表，防止「删路由忘改文档」类漂移。
📌 设计决策
- 函数式批量注册（RegisterRoutes(rg, h1, h2, ...)）而非每个 handler 自带 RegisterRoutes 方法：路由全景集中在一个文件、一眼看全 API 面；代价是参数列表长（9 个），但换来「增删接口改一处」的收敛。
- 统一前缀 /openapi/live-mixer：为网关（nginx PROXY_LOCATION_5）与未来多服务共存的路径规划预留结构。
- 免鉴权白名单显式列出而非配置：三个接口是稳定事实，配置化反而增加被误开的面。
代码示例
v1 注册骨架（保留关键注释）：
// internal/routes/v1/routes.go（节选）
func RegisterRoutes(rg *gin.RouterGroup, /* 8 个 handler */, jwtSecret string) {
// 登录接口无需 JWT 鉴权
rg.POST("/auth/login", authHandler.Login)
// ASR 同步识别接口无需 JWT 鉴权
rg.POST("/asr", asrHandler.Transcribe)
// 大模型同步对话接口无需 JWT 鉴权
rg.POST("/chat", chatHandler.Chat)
// 其余 v1 接口均需 JWT 鉴权
authorized := rg.Group("", middleware.JWTAuth(jwtSecret))
tasks := authorized.Group("/tasks")
{
// 具体路径须注册在 /:id 之前，避免被当成 id。
tasks.POST("/ai-slice", taskHandler.CreateAISliceTask)
tasks.POST("/draft", taskHandler.CreateDraftTask)
tasks.POST("/ai-slice-draft", taskHandler.CreateAISliceDraftTask)
tasks.GET("", taskHandler.ListTasks)
tasks.GET("/:id", taskHandler.GetTask)
}
}
素材组的联动子资源：
liveMaterials := authorized.Group("/live-materials")
{
liveMaterials.GET("", liveMaterialHandler.ListLiveMaterials)
liveMaterials.POST("", liveMaterialHandler.CreateLiveMaterial)
liveMaterials.PUT("/:id", liveMaterialHandler.UpdateLiveMaterial)
liveMaterials.POST("/:id/asr/retry", liveMaterialHandler.RetryASR)
liveMaterials.GET("/:id/asr/subtitle", liveMaterialHandler.DownloadASRSubtitle)
liveMaterials.GET("/:id/video-projects",
videoProjectHandler.ListVideoProjectsByLiveMaterial)
}
小结
- 路由层纯声明：组合根注入 handler，RegisterRoutes 只做路径映射。
- 免鉴权白名单三接口 + JWTAuth 分组覆盖其余全部。
- 具体路径先于 :id 注册、版本分组隔离演进是两条硬规则。
思考题
- 若新增 websocket 进度推送接口，放在免鉴权段还是鉴权段？鉴权 token 如何在握手期传递？
- v2 已经存在却几乎为空，什么时候值得真正启用 v2（举一个必须走 v2 的改动例子）？
项目信息
- GitHub仓库：Chyona/live-mixer
