2. Go 基础回顾：结构体、标签、接口与错误类型

在构建 REST API 服务时，结构体用于定义请求/响应模型，标签提供元数据（如字段名、校验规则），接口抽象行为，错误类型则统一处理异常。本章快速回顾这四个核心概念，为后续参数校验与错误处理打下基础。

2.1 结构体 (struct) 与标签 (tag)

结构体是 Go 中聚合不同类型字段的复合类型，常用于映射 JSON 请求体或数据库记录。标签（Tag）是附加在字段后的字符串，通过反射机制在运行时读取，广泛用于序列化、校验和 ORM 映射。

2.1.1 结构体定义与标签语法

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"`
    Role     string `json:"role"     validate:"oneof=admin user"`
}

标签格式：key:"value"，多个 key 用空格分隔。常用标签包括：

2.1.2 标签读取与反射

标签通过 reflect 包在运行时读取，这是校验库和序列化库的核心机制：

import "reflect"

func readTag(s interface{}) {
    t := reflect.TypeOf(s).Elem()
    for i := 0; i < t.NumField(); i++ {
        field := t.Field(i)
        jsonTag := field.Tag.Get("json")
        validateTag := field.Tag.Get("validate")
        fmt.Printf("Field: %s, json: %s, validate: %s\n", field.Name, jsonTag, validateTag)
    }
}

2.2 接口 (interface) 的概念

Go 的接口是隐式实现的——只要类型实现了接口的所有方法，就自动满足该接口。这种“鸭子类型”风格让代码更灵活，是依赖注入、中间件和策略模式的基础。

2.2.1 接口定义与实现

// 定义校验器接口
type Validator interface {
    Validate() error
}

// 结构体实现接口
type User struct {
    Name  string
    Email string
}

func (u User) Validate() error {
    if u.Name == "" {
        return errors.New("name is required")
    }
    if !strings.Contains(u.Email, "@") {
        return errors.New("invalid email")
    }
    return nil
}

// 使用接口
func process(v Validator) error {
    return v.Validate()
}

2.2.2 接口在 REST API 中的典型应用

• 校验器接口：所有请求 DTO 实现 Validate() error，统一校验入口。
• 存储层接口：定义 UserRepository 接口，支持 mock 测试和切换实现。
• 中间件接口：Handler 或 Middleware 接口抽象 HTTP 处理逻辑。
• 错误处理接口：自定义错误类型实现 Error() string 和状态码方法。

2.3 错误 (error) 类型基础

Go 的 error 是一个内置接口：

type error interface {
    Error() string
}

任何实现了 Error() string 方法的类型都可以作为错误值。这是 Go 错误处理的核心抽象。

2.3.1 创建错误的常用方式

2.3.2 自定义错误类型示例

type APIError struct {
    HTTPStatus int    `json:"-"`
    Code       string `json:"code"`
    Message    string `json:"message"`
    Err        error  `json:"-"` // 内部原始错误
}

func (e *APIError) Error() string {
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

func (e *APIError) Unwrap() error {
    return e.Err
}

// 使用
func findUser(id int) (*User, error) {
    if id <= 0 {
        return nil, &APIError{
            HTTPStatus: 400,
            Code:       "INVALID_ID",
            Message:    "用户 ID 必须为正整数",
        }
    }
    // ...
}

2.4 核心概念关系图

下图展示了结构体、标签、接口和错误类型在 REST API 请求处理中的协作关系：

2.5 本章小结

• 结构体 + 标签：定义数据模型，标签提供元数据驱动校验和序列化。
• 接口：隐式实现，抽象行为（如校验、存储），便于测试和扩展。
• 错误类型：error 接口是基础，自定义错误可携带 HTTP 状态码、错误码等上下文。
• 三者结合：结构体承载数据 → 标签描述规则 → 接口定义行为 → 错误类型统一异常路径。