3.4 请求与校验

概述

本项目没有独立的"验证器文件"——请求校验由 api/v1 请求结构体上的 gvalid 标签完成，路由/权限/日志元数据由内嵌 gmeta.Meta 声明。一个结构体即接口契约的全部。

请求结构体解剖（真实代码，摘自 api/v1/example.go）

// ============================== 案例演示模块（goframe_example） ==============================

// ExamplePageReq 案例演示分页请求
type ExamplePageReq struct {
	gmeta.Meta `method:"get" path:"/api/example/page" summary:"案例演示分页" permission:"sys:example:page" log:"案例演示-查询分页记录" logType:"query"`
	PageReq
	Name    string `json:"name" dc:"案例名称"`   // 案例名称
	Type    int    `json:"type" dc:"案例类型"`   // 案例类型
	Status  int    `json:"status" dc:"案例状态"` // 案例状态
	Keyword string `json:"keyword" dc:"关键词"` // 关键词
}

// ExampleDetailReq 案例演示详情请求
type ExampleDetailReq struct {
	gmeta.Meta `method:"get" path:"/api/example/detail/:id" summary:"案例演示详情" permission:"sys:example:detail" log:"案例演示-查询详情" logType:"query"`
	Id         int64 `json:"id" v:"required#缺少ID" dc:"记录ID"` // 记录ID
}

// ExampleAddReq 新增案例演示请求
type ExampleAddReq struct {
	gmeta.Meta `method:"post" path:"/api/example/add" summary:"新增案例演示" permission:"sys:example:add" log:"案例演示-新增记录" logType:"add"`
	Name       string `json:"name" v:"required#请输入案例名称" dc:"案例名称"` // 案例名称
	Avatar     string `json:"avatar" dc:"案例图片"`                    // 案例图片
	Type       int    `json:"type" dc:"案例类型"`                      // 案例类型
	Status     int    `json:"status" dc:"案例状态"`                    // 案例状态
	Sort       int    `json:"sort" dc:"案例排序"`                      // 案例排序
}

标签体系一览

标签	来源	作用
gmeta.Meta	gf 框架	内嵌后由本项目 bind.go 扩展解析
method/path/summary	gmeta	HTTP 方法、路由模板（:id 路由参数）、OpenAPI 摘要
permission	gmeta	权限节点 sys:{module小驼峰}:{action}；空 = 登录即可
log/logType	gmeta	操作日志标题与类型（query/add/update/delete/import/export…）
public	gmeta	"true" = 免登录（须与 middleware/public.go 白名单一致）
json	标准	出入参字段名，一律驼峰（例外仅登录/令牌接口的下划线字段）
v	gvalid	校验规则，如 required#请输入案例名称（# 后为自定义错误文案）
dc	goai	OpenAPI 文档中的字段说明
p	ghttp	multipart 上传字段名（如 p:"file"）

gvalid 常用规则

Id     int64  `json:"id" v:"required#缺少ID"`              // 必填
Age    int    `json:"age" v:"min:0#年龄不能为负"`            // 数值范围
Ids    []int64 `json:"ids" v:"required#缺少ID列表"`          // 数组必填
Email  string `json:"email" v:"email#邮箱格式不正确"`         // 格式
Status int    `json:"status" v:"in:1,2#状态值不合法"`        // 枚举（如角色 dataScope 用 in:1,2,3,4）

校验失败由框架返回 code=400 信封，错误文案取 # 后缀；无需在业务代码里手写 if 判断。

路由参数承接

gmeta path 中的 :id 由请求结构体同名（驼峰 json）字段承接：

路由模板  GET /api/example/detail/:id
       └─▶  ExampleDetailReq.Id int64 `json:"id"`   ← r.Parse 自动绑定

请求解析流程（Bind 包装层完成）

1. r.Parse(req)：路由参数 + query + body 一次性绑定（含 gvalid 校验）
2. 实现 BodyUnmarshaler 接口的请求对象走自定义解析逃生舱
   （请求体顶层形态无法用结构体标签表达时使用，gvalid 需在实现内自完成）
3. 校验失败 → response.Fail(code=400) 短路返回，业务方法不执行

响应结构体（真实代码，摘自 api/v1/example.go）

// ExamplePageRes 案例演示分页结果
// 统一壳：records/total/size/current/pages
type ExamplePageRes = PageData[ExampleItem]

// ExampleListRes 案例演示平铺列表结果
// data 直接为数组，树形结构由前端 buildTree 构建
type ExampleListRes = []ExampleItem

// ExampleIdRes 新增返回ID结构
type ExampleIdRes struct {
	Id int64 `json:"id"` // 主键ID
}

// ExampleUpdateRes 修改案例演示结果
type ExampleUpdateRes struct{}

要点：

• 分页结果统一用泛型壳 PageData[T]（v1.NewPageData 构造）
• 新增返回统一 {id} 结构（模块自定义 XxxIdRes；公共场景用 common.IdRes）
• 修改/删除等空结果返回空结构体 struct{}
• 行结构体含 {Field}Text string 字段时由基座自动填字典显示名

行结构体示例（含字典文本字段）

// ExampleItem 案例演示行数据
// 用于分页列表等场景的基础信息
type ExampleItem struct {
	Id         int         `json:"id"`         // 主键ID
	Name       string      `json:"name"`       // 案例名称
	Avatar     string      `json:"avatar"`     // 案例图片
	Type       int         `json:"type"`       // 案例类型
	Status     int         `json:"status"`     // 案例状态
	Sort       int         `json:"sort"`       // 案例排序
	CreateUser string      `json:"createUser"` // 创建人
	CreateTime *gtime.Time `json:"createTime"` // 创建时间
	StatusText string      `json:"statusText"` // 状态显示名（dict_item 解析）
}

StatusText 与 Status 配对，配合 logic 里 SerializeMaps = {"status": "example_status"} 声明，读取时自动填充（见 3.5 逻辑层开发）。