★ 规范路由与 OpenAPI 自动接口文档

面试问法：GoFrame v2 的“规范路由”是什么？接口文档是怎么做到自动生成的？ 一句话结论：规范路由把“接口定义”收敛成一组结构体——handler 固定签名 (ctx, req) (res, err)，路由地址与方法写在 Req 嵌入的 g.Meta 标签里；框架据此自动注册路由、自动校验参数，并自动产出 OpenAPIv3 文档与内置 Swagger UI。文档、校验与代码同源，是 v2 官方主推且完整支持的一等特性。

核心要点

• handler 签名四件套缺一不可：接收者 + ctx context.Context + req *XxxReq + 返回 (res *XxxRes, err error)。
• g.Meta 标签声明 path、method、tags、summary、dc 等路由与描述信息。
• 接口文档与 Swagger 默认关闭，用 server.openapiPath / server.swaggerPath 开启。
• 请求对象进入 handler 前框架自动绑定并校验（带 bail 修饰，失败即停、返回错误）。
• goai 把字段校验规则映射成 OpenAPI 约束：required→required:true、between:18,60→minimum/maximum、in:a,b→enum、length→minLength/maxLength。

最短示例

type HelloReq struct {
    g.Meta `path:"/hello" method:"get" tags:"Hello" summary:"say hello"`
    Name   string `v:"required" dc:"your name"`
}
type HelloRes struct{ Reply string `json:"reply"` }

type Hello struct{}

func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
    return &HelloRes{Reply: "hi " + req.Name}, nil
}

s := g.Server()
s.Use(ghttp.MiddlewareHandlerResponse) // 统一 {code,message,data}
s.Group("/", func(g *ghttp.RouterGroup) { g.Bind(new(Hello)) })
s.Run()

server:
  address: ":8000"
  openapiPath: "/api.json"   # OpenAPIv3 文档地址
  swaggerPath: "/swagger"    # Swagger UI 地址

启动后 /api.json 返回自动生成的规范文档，/swagger 在线调试，全程零手写。

常见追问

• 追问：文档如何补全或自定义？——s.GetOpenApi() 拿文档对象补充全局信息（如公共响应包 code/message/data）；响应结构体实现 IEnhanceResponseStatus 可为不同状态码补充响应示例。
• 追问：线上不想公开文档怎么办？——文档默认关闭；需要开启时在钩子里给 /api.json 加鉴权即可。
• 追问：为什么叫“同源”？——路径、参数、校验约束全部来自同一份 Req 定义，改代码即改文档，不会出现文档过期。

记忆点

• 规范路由 = 结构体即接口定义，OpenAPI/Swagger 是自动产物而非额外维护项。
• 高频追问围绕 g.Meta 标签、校验标签与 OpenAPI 的映射、统一返回包装，细节以官方文档为准。