规范路由入门：g.Meta 定义 method/path 与 Req/Res 自动路由

引言

从 v2 开始，GoFrame 官方主推"规范路由"（标准路由）：接口的请求/响应结构体、路径、方法全都声明在结构体上，路由自动注册。本章讲清它的最小模型。

概念

规范路由的核心是 Req/Res 模式：

• 请求结构体：字段是入参，内嵌 g.Meta，用标签声明路由信息，如 method（HTTP 方法）、path（访问路径）。
• 响应结构体：字段即返回给客户端的 JSON 数据。
• 控制器对象：一个结构体的方法形如 func(ctx, *Req) (res *Res, err error)，框架自动完成参数绑定、校验与响应序列化。
• 自动路由：把控制器对象通过 group.Bind(obj) 注册后，每个方法按 Req 的 meta 声明自动生成路由。

g.Meta 支持多个标签（method/path/summary/middleware 等，完整清单以官方文档规范路由章节为准）。本章用官方风格的 Hello 示例演示最小用法。

代码示例

package main

import (
	"context"

	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
)

// 请求结构体：g.Meta 声明路由信息，其余字段为入参
type HelloReq struct {
	g.Meta `path:"/hello" method:"get"`
	Name   string `v:"required" json:"name"`
}

// 响应结构体：字段会序列化为 JSON 返回
type HelloRes struct {
	Reply string `json:"reply"`
}

// 控制器：方法即一个接口处理逻辑
type Hello struct{}

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

func main() {
	s := g.Server()

	s.Group("/", func(group *ghttp.RouterGroup) {
		// 注册控制器，自动生成 GET /hello 路由
		group.Bind(new(Hello))
	})

	s.SetPort(8000)
	s.Run()
}

访问 GET /hello?name=GoFrame，返回：

{"reply":"Hi GoFrame"}

不带 name 时，框架依据 v:"required" 自动校验并返回校验错误，无需手写判断。想注册更多接口，就继续加 Req/Res 与控制器方法：

type UserGetReq struct {
	g.Meta `path:"/user/{id}" method:"get"`
	Id     int64 `json:"id"`
}

type UserGetRes struct {
	Id   int64  `json:"id"`
	Name string `json:"name"`
}

控制器 User 中实现对应方法即可，路径占位符 {id} 会自动绑定到 Id 字段。

注意点

• Req 结构体必须内嵌 g.Meta，否则无法声明 path/method。
• 处理器方法签名固定为 func(ctx context.Context, req *XxxReq) (res *XxxRes, err error)，返回 err != nil 时框架走错误处理流程。
• 需要统一样式的 code/message/data 响应时，注册官方默认返回中间件（脚手架默认已做），详见下一章。
• 路径参数用 {name} 语法（如 /user/{id}），与其它路由框架的 :id 不同。

小结

规范路由把"路由声明"与"数据结构"合并：一个 Req/Res + 一个方法就是一个接口。它也是 gf gen 代码生成体系的基础。中间件、校验与统一返回在规范路由中的完整写法，见下一章。