2. Go语言基础回顾：结构体(struct)、方法(method)、接口(interface)、错误处理(error)基础

在构建REST API时，参数校验并非孤立的字符串检查，而是贯穿请求解析、数据绑定与业务逻辑验证的完整链路。Go语言的结构体、方法、接口与错误处理构成了这一链路的基石。本章将快速回顾这四大核心特性，为后续的校验框架搭建提供坚实的语法与设计基础。

2.1 结构体：参数校验的数据载体

结构体是Go中定义复合数据类型的主要方式。在REST API中，每个请求体、查询参数或路径参数几乎都对应一个结构体。结构体通过字段标签（Tag）为校验规则提供了声明式入口。

核心要点：结构体字段的json、form、validate等标签是参数校验的元数据来源，校验库通过反射读取这些标签来执行规则。 
// 定义用户注册请求的结构体
type CreateUserRequest struct {
    Username string `json:"username" validate:"required,min=3,max=20"`
    Email    string `json:"email"    validate:"required,email"`
    Age      int    `json:"age"      validate:"gte=18,lte=120"`
    Password string `json:"password" validate:"required,min=8"`
}
结构体特性 在参数校验中的作用 示例
字段标签（Tag） 声明校验规则、序列化名称 validate:"required,email"
嵌套结构体 表达复杂请求体的层级关系 Address struct { ... }
匿名字段 实现字段复用与组合校验 type AdminReq struct { UserInfo; Role string }
导出字段（大写开头） 确保反射包可访问，校验库才能读取 Name string 而非 name string
实践建议：为每个API端点定义专用的请求结构体，而非复用同一个结构体。这能避免字段污染，使校验规则与业务场景精确对应。

2.2 方法：为结构体注入校验行为

Go的方法允许为结构体绑定特定的函数。在参数校验场景中，方法常用于实现自定义校验逻辑或业务规则验证，这些逻辑无法通过标签声明完成。

type OrderRequest struct {
    ProductID string  `json:"product_id" validate:"required"`
    Quantity  int     `json:"quantity"    validate:"required,gt=0"`
    CouponCode string `json:"coupon_code"`
}

// Validate 方法：执行自定义业务校验
func (o *OrderRequest) Validate() error {
    // 校验优惠券与商品的关联关系（标签无法表达的逻辑）
    if o.CouponCode != "" {
        if !isCouponValidForProduct(o.CouponCode, o.ProductID) {
            return fmt.Errorf("优惠券 %s 不适用于商品 %s", o.CouponCode, o.ProductID)
        }
    }
    // 校验库存
    if !hasEnoughStock(o.ProductID, o.Quantity) {
        return fmt.Errorf("商品 %s 库存不足", o.ProductID)
    }
    return nil
}

方法接收者可以是值类型或指针类型。在参数校验中，指针接收者更常见，因为校验逻辑可能需要修改结构体字段（如格式化、脱敏），且避免大结构体的值拷贝。

接收者类型 适用场景 校验中的典型用途
值接收者 (s MyStruct) 只读校验、不修改字段 检查字段间逻辑关系
指针接收者 (s *MyStruct) 需要修改字段、避免拷贝 字段格式化、默认值填充、脱敏

2.3 接口：定义校验器的统一契约

接口是Go实现多态与解耦的核心。在参数校验架构中，接口定义了校验行为的抽象契约，使得不同的校验实现可以无缝替换。

// Validator 接口：定义校验器的统一行为
type Validator interface {
    Validate(i interface{}) error
}

// 基于标签的校验器实现
type TagValidator struct{}

func (v *TagValidator) Validate(i interface{}) error {
    // 使用反射读取结构体标签，执行校验规则
    return validate.Struct(i)
}

// 自定义业务校验器实现
type BusinessValidator struct{}

func (v *BusinessValidator) Validate(i interface{}) error {
    // 类型断言，调用结构体的 Validate 方法
    if v, ok := i.(interface{ Validate() error }); ok {
        return v.Validate()
    }
    return nil
}
校验器接口与实现关系 Validator 接口 TagValidator BusinessValidator CustomValidator 接口解耦：业务层只依赖 Validator 接口， 不依赖具体实现，便于切换校验策略
设计启示：在REST API参数校验中，接口使得我们可以组合多种校验策略：先用TagValidator做基础格式校验，再用BusinessValidator做业务规则校验，最后用CustomValidator做第三方服务校验。

2.4 错误处理：校验结果的标准化输出

Go的错误处理哲学是显式处理。在参数校验中，错误处理不仅关乎程序健壮性，更直接影响API的响应质量。标准化的错误结构能让客户端精确理解校验失败的原因。

// ValidationError 自定义校验错误类型
type ValidationError struct {
    Field   string `json:"field"`
    Tag     string `json:"tag"`
    Value   interface{} `json:"value"`
    Message string `json:"message"`
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("字段 %s 校验失败: %s", e.Field, e.Message)
}

// 收集多个校验错误
type ValidationErrors []ValidationError

func (ve ValidationErrors) Error() string {
    var msgs []string
    for _, e := range ve {
        msgs = append(msgs, e.Error())
    }
    return strings.Join(msgs, "; ")
}

// 使用示例
func validateUser(req *CreateUserRequest) error {
    var errs ValidationErrors
    if len(req.Username) < 3 {
        errs = append(errs, ValidationError{
            Field: "username", Tag: "min", Value: req.Username,
            Message: "用户名长度不能少于3个字符",
        })
    }
    if !strings.Contains(req.Email, "@") {
        errs = append(errs, ValidationError{
            Field: "email", Tag: "email", Value: req.Email,
            Message: "邮箱格式不正确",
        })
    }
    if len(errs) > 0 {
        return errs
    }
    return nil
}
错误处理模式 适用场景 API响应示例
单一错误返回 第一个校验失败即终止 {"error": "用户名不能为空"}
聚合错误返回 收集所有校验失败项 {"errors": [{"field":"email","message":"..."}, ...]}
自定义错误类型 需要携带额外上下文 {"field":"age","tag":"gte","value":15}
错误包装（Wrap） 保留原始错误链 fmt.Errorf("校验失败: %w", err)
常见陷阱：不要直接返回校验库的原始错误信息给客户端。这些信息可能包含内部字段名（如gte标签）、技术细节或敏感数据。始终将校验错误转换为业务友好的、结构化的响应格式。

2.5 四大特性的协作流程

在REST API参数校验中，结构体、方法、接口和错误处理并非孤立存在，而是形成一个完整的协作链条：

  1. 结构体承载请求数据，通过标签声明基础校验规则。
  2. 接口定义校验器的统一契约，实现校验策略的可替换性。
  3. 方法在结构体上实现自定义业务校验逻辑，补充标签无法表达的规则。
  4. 错误处理将校验结果标准化，输出结构化的错误响应。
参数校验四大特性协作流程 结构体 数据载体+标签 接口 校验契约 方法 自定义逻辑 错误处理 标准化输出 协作流程： 1. 结构体定义数据模型 → 2. 接口定义校验器契约 3. 方法实现业务校验 → 4. 错误处理输出标准化结果
← 上一章 📖 返回目录 下一章 →