Go-Zero参数校验需区分请求校验与配置加载；用validate tag配合httpx.Parse实现声明式校验，缺失json tag会导致校验失效；复杂规则应在logic层或独立validator中处理。
在 Go-Zero 项目中实现参数校验，必须明确区分请求参数校验与配置文件加载——前者发生在每次 HTTP 请求进入 handler 前，后者仅在服务启动时执行一次；混淆二者会导致 validate 标签被忽略、错误不触发、或校验逻辑根本没运行。
用 go-zero 自带 validator 实现声明式校验
第一步：在 .api 文件中定义请求结构体，并添加 validate tag
例如，在 user.api 中写：
type CreateUserReq struct {<br> Name string `json:"name" validate:"required,min=2,max=20"`<br> Age int64 `json:"age" validate:"gte=1,lte=130"`<br> Email string `json:"email" validate:"required,email"`<br>}
注意：tag 必须写在结构体字段上，且 json tag 与 validate tag 需共存；【缺少 json tag 会导致 httpx.Parse 无法正确绑定字段，validate 根本不会触发】
第二步：运行 goctl api go -api user.api -dir . 生成代码
生成的 types/types.go 中会自动包含该结构体，且已带完整 tag；无需手动补全
第三步：确保 handler 中调用的是 httpx.Parse（而非 httpx.ParseJsonBody 或裸 json.Unmarshal）
httpx.Parse 是 go-zero 的封装入口，它会在解析完所有来源（path/query/header/body）后，自动检查结构体是否实现了 Validate() error 方法并调用——这是校验生效的唯一路径。
自定义复杂业务规则校验
当内置规则（如 required、email）无法覆盖业务逻辑时，需手动实现 Validate() 方法。
方法一：在生成的 types 结构体上直接扩展（推荐用于简单逻辑）
编辑 types/types.go，为结构体添加方法：
func (r *CreateUserReq) Validate() error {<br> if r.Age == 0 {<br> return errors.New("age cannot be zero")<br> }<br> if r.Name == "admin" {<br> return errors.New("name cannot be 'admin'")<br> }<br> return nil<br>}
⚠️ 注意：此方式修改的是生成文件，下次 goctl 重生成会被覆盖；仅适合临时验证或原型阶段。
方法二：在 logic 层做二次校验（生产环境首选）
在 internal/logic/createuserlogic.go 的 Handle 方法开头加入：
if req.Age return nil, errors.New("age must be at least 18")<br>}
这一步不依赖 validator 库，可自由访问数据库、缓存、其他服务，适合强业务耦合判断。
方法三：封装独立校验器，注入到 logic 中复用
新建 internal/validator/user_validator.go：
type UserValidator struct{}<br>func (v *UserValidator) ValidateCreate(req *types.CreateUserReq) error {<br> if !strings.HasPrefix(req.Email, "company.com") {<br> return errors.New("email must be from company.com")<br> }<br> return nil<br>}
在 servicecontext.go 中初始化并注入：Validator: &validator.UserValidator{}，然后在 logic 中调用 l.svcCtx.Validator.ValidateCreate(req)。
关键配置与易错点排查
① 确保 go-zero 版本 ≥ v1.7.0 —— 旧版本中 optional 字段若未传值，会导致整个结构体解析失败，而非跳过校验。
② 若使用 form 类型参数（Content-Type: multipart/form-data），validate tag 仍生效，但必须配合 form tag 使用：form:"name"，否则字段无法绑定。
③ default tag 不触发校验，仅填充零值；omitempty 影响 JSON 序列化，不影响校验流程。
④ 自定义错误返回时，go-zero 默认将 error 转为 HTTP 400 响应体，内容为 {"code":400,"message":"xxx"}；如需定制格式，需替换全局 httpx.Error 处理函数。
⑤ 当校验失败时，日志中会出现 invalid request: xxx，但默认不打印具体字段；可在 handler 中捕获 httpx.Parse 错误并打点：logx.WithContext(r.Context()).Errorf("parse failed: %v", err)。
