go-zero生成HTTP服务需严格遵循.api文件规范：首行必须为syntax = "v1"；info块仅可出现一次且字段名小写、date格式为YYYY-MM-DD；service块定义接口，含@handler、路径方法及请求响应结构体，并支持@server配置prefix和jwt鉴权。
要让 go-zero 正确生成 HTTP 服务骨架，必须手写一份合法的 .api 文件，它不是文档草稿，而是会被 goctl 解析并直接覆写代码的执行脚本——写错一个空格、少一个引号、version 不匹配，goctl 就会报错退出，后续所有 handler、types、routes 都不会生成。
syntax 声明必须放在第一行且格式严格
在文件最开头（不能有任何空行、注释或空格前置）写：syntax = "v1"。
这行不是可选注释，是 goctl 解析器识别语法版本的唯一入口。当前所有稳定版 goctl（包括 v1.7.x 及以上）只支持 【v1】，写成 "v2"、"V1"、"v1 "（末尾带空格）、syntax="v1"（等号紧贴）都会导致解析失败。
如果完全省略 syntax 行，解析器会默认按 v1 处理，但官方明确要求“必须显式声明”，否则未来开启严格模式后将被拒绝。
info 块用于标记元信息，仅允许出现一次
info 块不是生成代码的必要条件，但它会出现在最终生成的 Go 注释头和 Swagger 文档中。
写法必须是括号包裹的键值对形式，例如：
info( author: "zhangsan" date: "2026-11-12" desc: "用户中心核心 API")
注意：author 和 date 字段名必须小写，不能写成 Author 或 DATE；date 值必须是 YYYY-MM-DD 格式字符串，【不能是时间戳或中文日期】；整个 info 块在单个 .api 文件里最多只能出现一次，重复声明会导致 goctl 解析报错。
service 块定义接口行为，是生成路由与 handler 的核心
service 块描述“谁在什么路径上用什么方法收发什么数据”，它驱动 goctl 创建 handler 函数、绑定路由、注入中间件。
第一步：用 service 服务名 { 开启块，服务名将作为生成目录名和 package 名，必须是合法 Go 包名（只含小写字母、数字、下划线，不能以数字开头）。
第二步：在 service 块内，每条接口声明必须包含三要素：@handler 标识符、HTTP 方法 + 路径、请求/响应结构体括号对。
例如：@handler login post /user/login (LoginReq) returns (LoginReply) 这一行就决定了：生成 internal/handler/user/login.go 文件、注册 POST /user/login 路由、自动绑定 LoginReq 解析与 LoginReply 序列化。
第三步：如果需要统一前缀或鉴权，必须在 service 上方添加 @server 块，例如：@server(prefix: /v1, jwt: Auth)。prefix 会拼接到每条路由前面，而 jwt: Auth 会让 goctl 在 handler 中自动插入 JWT 校验逻辑——不加这行，即使路径写了 /v1/user/login，实际注册的仍是 /user/login。
