企业级校验需耦合业务规则，原生validator仅支持结构校验，故需设计支持上下文注入与链式拦截的可插拔校验执行器，核心是分离声明式规则与运行时执行。
为什么直接用 validator 包还不够？
因为企业级场景下，校验不只是“字段非空”或“长度范围”，它要和业务规则强耦合：比如 order_id 必须是当前用户可操作的、amount 要经过风控阈值拦截、timestamp 不能偏离服务端时间超过 5 分钟。原生 validator（如 go-playground/validator）只做结构校验，不支持动态上下文注入和链式拦截。
所以真正需要的不是“封装 validator”，而是设计一个能插入业务钩子的校验执行器。
如何定义可插拔的校验器接口？
核心是把校验逻辑拆成“声明式规则”和“运行时执行”两层。推荐定义如下接口：
type Validator interface {
Validate(ctx context.Context, data interface{}) error
}
type Rule interface {
Name() string
Check(ctx context.Context, field string, value interface{}) error
}
这样做的好处是：Validator 可统一接入 HTTP 中间件、gRPC 拦截器、消息消费入口；Rule 可按需组合，比如复用同一个 NotZeroRule 校验 int64 和 uint32，也方便单元测试 mock。
- 不要把所有校验逻辑塞进 struct tag（如
validate:"required,email"），tag 只保留基础约束，业务规则走代码注册 - 每个
Rule必须接收context.Context，否则无法透传 traceID、用户身份、租户信息 - 避免在
Rule.Check里做 DB 查询——应提前把依赖数据加载到ctx中（例如用context.WithValue注入预查的用户权限 map）
怎么让错误提示既统一又可读？
企业系统最怕报错返回 "Key: 'User.Email' Error:Field validation for 'Email' failed on the 'email' tag" 这种开发友好但前端崩溃的格式。必须重写错误渲染逻辑。
建议用结构化错误码 + 映射表：
var ErrMap = map[string]string{
"email": "邮箱格式不正确",
"phone": "手机号格式不正确",
"amount_gt_limit": "交易金额超出单笔限额",
}
func (v *DefaultValidator) FormatError(err error) []*ValidationError {
ve := &validator.FieldError{}
if errors.As(err, &ve) {
return []*ValidationError{{
Field: ve.Field(),
Code: ve.Tag(),
Msg: ErrMap[ve.Tag()],
}}
}
// ... 处理自定义 Rule 的 error（需实现 Unwrap 或 type assert）
}
- 不要直接返回
err.Error()给前端，所有错误都走ValidationError结构体，含Field、Code、Msg三字段 -
Code必须是英文短标识（如"user_not_found"），用于前端 i18n 映射，Msg是 fallback 中文提示 - 如果用了多个校验器（如先结构校验再业务校验），错误合并时注意去重——相同
Field+ 相同Code只保留第一个
HTTP 层怎么无缝集成？
别写一个 ValidateRequest 函数到处调用。直接做成 Gin 或 Chi 的中间件，但要注意两点：一是绑定时机，二是错误返回格式。
Gin 示例：
func ValidationMiddleware(v Validator) gin.HandlerFunc {
return func(c *gin.Context) {
// 注意：必须在 c.ShouldBind() 之前执行，否则 body 已被读取
if err := v.Validate(c.Request.Context(), c.MustGet("parsed_body")); err != nil {
c.AbortWithStatusJSON(http.StatusBadRequest, map[string]interface{}{
"code": 40001,
"msg": "参数校验失败",
"data": v.FormatError(err),
})
return
}
c.Next()
}
}
- 不要在中间件里调用
c.Bind()—— 它会触发默认校验，和你的模块冲突；应在上层 handler 解析完 body 后显式塞入c.Set("parsed_body", obj) - gRPC 场景类似，用 UnaryServerInterceptor，但注意
ctx是 RPC 上下文，需从metadata提取租户 ID 再注入校验器 - 如果请求体是 multipart/form-data 或文件上传，校验器必须支持
multipart.FileHeader类型，不能只认 JSON struct
真正的难点不在代码量，而在于校验边界：哪些该由参数模块拦，哪些该交给 service 层做最终一致性校验。比如“库存是否充足”必须查 DB，但“下单数量 > 0” 就该在这里挡掉。这个分界点，得和产品、测试一起对齐，不是纯技术能定的。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
