2. 核心数据结构设计

业务环境回放工程的核心是数据的准确捕获与还原。数据结构设计的优劣直接决定了回放系统的可扩展性、存储效率以及后续分析的准确性。本章将详细定义请求/响应模型、通用回放记录结构体，并探讨序列化方案与唯一标识的生成策略。

2.1 请求/响应模型定义

为了统一不同业务协议的接入，我们定义一套抽象的请求与响应模型。该模型不绑定具体传输协议（HTTP/gRPC/Thrift），而是提取出业务回放所需的通用字段。

2.2 通用回放记录结构体

回放记录是存储与传输的基本单元。它除了包含请求/响应外，还需携带上下文信息，以支持流量筛选、回放比对与结果分析。

// Record 定义一条完整的回放记录
type Record struct {
    // 全局唯一标识，用于去重与追踪
    ID        string `json:"id" protobuf:"1"`
    // 业务环境标识，如 prod、staging、canary
    Env       string `json:"env" protobuf:"2"`
    // 服务名称，标识流量来源
    Service   string `json:"service" protobuf:"3"`
    // 请求详情
    Request   Request `json:"request" protobuf:"4"`
    // 响应详情
    Response  Response `json:"response" protobuf:"5"`
    // 捕获时间戳（Unix 纳秒）
    CapturedAt int64 `json:"captured_at" protobuf:"6"`
    // 自定义标签，用于过滤与分组
    Tags      map[string]string `json:"tags" protobuf:"7"`
    // 预留扩展字段，支持未来协议升级
    Ext       []byte `json:"ext,omitempty" protobuf:"8"`
}

2.3 序列化与反序列化

回放系统需要同时支持高性能存储与跨语言消费。我们采用双序列化策略：内部存储与传输使用 Protobuf，外部调试与日志输出使用 JSON。

2.3.1 JSON 序列化

JSON 主要用于开发调试、日志打印以及与其他非 Go 系统的轻量交互。Go 标准库 encoding/json 即可满足需求，但需注意大 Body 场景下的内存分配优化。

// 序列化 Record 为 JSON
func (r *Record) MarshalJSON() ([]byte, error) {
    type Alias Record // 避免递归调用
    return json.Marshal(&struct {
        *Alias
    }{
        Alias: (*Alias)(r),
    })
}

// 反序列化 JSON 为 Record
func (r *Record) UnmarshalJSON(data []byte) error {
    type Alias Record
    aux := &struct {
        *Alias
    }{
        Alias: (*Alias)(r),
    }
    return json.Unmarshal(data, aux)
}

2.3.2 Protobuf 序列化

Protobuf 是回放系统的核心序列化格式，用于消息队列传输、文件存储以及回放引擎的内存交换。其二进制编码体积小、解析速度快，且支持向前/向后兼容。

// 使用 protobuf 序列化 Record
func (r *Record) MarshalProtobuf() ([]byte, error) {
    pb := recordToProto(r) // 转换为 protobuf 生成的结构体
    return proto.Marshal(pb)
}

// 反序列化 protobuf 为 Record
func (r *Record) UnmarshalProtobuf(data []byte) error {
    pb := &proto.Record{}
    if err := proto.Unmarshal(data, pb); err != nil {
        return err
    }
    protoToRecord(pb, r)
    return nil
}

2.4 时间戳与唯一 ID 生成

2.4.1 时间戳规范

所有时间戳统一使用 Unix 纳秒（int64），避免时区歧义与精度丢失。捕获时间戳 CapturedAt 在捕获层生成，请求时间戳 Request.Timestamp 由业务方传入，两者之差可用于评估捕获延迟。

// 生成当前时间的 Unix 纳秒时间戳
func NowUnixNano() int64 {
    return time.Now().UnixNano()
}

// 将纳秒时间戳转换为可读格式（仅用于日志）
func FormatTimestamp(nano int64) string {
    sec := nano / 1e9
    nsec := nano % 1e9
    return time.Unix(sec, nsec).Format("2006-01-02 15:04:05.000000000")
}

2.4.2 唯一 ID 生成策略

回放记录 ID 需要满足全局唯一、单调递增趋势、可排序、分布式无冲突等特性。我们采用 Snowflake 算法 的变体，结合业务标识生成 64 位整数 ID。

// Snowflake ID 生成器核心逻辑
type Snowflake struct {
    mu        sync.Mutex
    epoch     int64 // 自定义纪元（毫秒）
    nodeID    int64 // 工作节点 ID
    sequence  int64 // 当前毫秒内的序列号
    lastStamp int64 // 上次生成 ID 的时间戳
}

func (s *Snowflake) NextID() (int64, error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    now := time.Now().UnixMilli()
    if now < s.lastStamp {
        return 0, fmt.Errorf("clock moved backwards: %d < %d", now, s.lastStamp)
    }

    if now == s.lastStamp {
        s.sequence = (s.sequence + 1) & 0xFFF // 12 位序列号
        if s.sequence == 0 {
            // 当前毫秒序列号耗尽，等待下一毫秒
            for now <= s.lastStamp {
                now = time.Now().UnixMilli()
            }
        }
    } else {
        s.sequence = 0
    }

    s.lastStamp = now
    id := ((now - s.epoch) << 22) | (s.nodeID << 12) | s.sequence
    return id, nil
}

2.5 数据结构关系总览

下图展示了核心数据结构之间的依赖关系与数据流向，帮助理解各模块在回放系统中的位置。