Go-Zero路由定义须严格遵循路径格式、分组语义和版本前缀规则：路径必须以/开头且无多余斜杠；参数名需与path tag一致；prefix和group不自动补/；版本控制推荐路径级prefix，多文件隔离可实现强隔离。
在 Go-Zero 项目中定义路由时，必须严格遵循路径格式、分组语义和版本前缀规则，否则 goctl 生成的路由注册代码会缺失 handler 或 panic 报错。
基础路由路径定义
路由必须以 / 开头，节点间用 / 分隔，不允许多余斜杠或空节点。
例如：get /users/:id 合法，get users/:id（缺开头/）或 get //users/:id（双斜杠）均会导致 goctl 解析失败。
路径中可含字母、数字、下划线、中划线；若需接收参数，必须使用 : 开头的命名节点，如 :id、:tenant_code。
【: 后面的参数名必须与请求结构体中 path tag 的值完全一致】，否则运行时提取不到值，逻辑层收到空字符串或零值。
服务分组与 prefix 前缀配置
service 块上方的 @server 注解用于声明分组上下文，其中 prefix 字段决定该 service 下所有路由的统一前缀。
方法一：静态 prefix（最常用）
在 @server 中直接写死字符串：@server(prefix: v1) → 所有路由自动拼接为 v1/users/:id、v1/orders 等。
方法二：组合 prefix + group
@server(prefix: api/v1, group: user) → 实际注册路径为 api/v1/user/users/:id，group 会作为二级路径追加。
注意：prefix 和 group 均不自动补斜杠，prefix: api/v1 与 prefix: api/v1/ 效果不同——后者会在末尾多出一个 /，可能引发 404。
API 版本控制的三种落地方式
第一步：在 .api 文件顶部声明语法版本
syntax = "v1" —— 这是硬性前提，缺此行或写成 syntax="v1"（等号无空格）都会导致 goctl 解析中断。
第二步：选择版本承载位置
① 路径级版本（推荐）：通过 @server(prefix: v1) 统一控制，适合灰度发布或大版本切换。
② 接口级版本（细粒度）：在单个 handler 注解中叠加 @handler getUserV2 并配独立路由 get /v2/users/:id，但需手动维护路由一致性。
③ 多文件隔离（强隔离）：为 v1、v2 分别建立 user_v1.api 和 user_v2.api，用不同 goctl api go 命令生成独立 service 包，物理隔离避免任何冲突。
第三步：确保类型定义兼容性
若 v2 接口新增字段，不要直接修改原 type User，而应新建 type UserV2 或用 optional 标签标记新字段，否则 v1 客户端调用会因字段缺失解析失败。
