3. 核心数据结构设计：回放事件（Event）模型设计、元数据（Metadata）定义、时间戳与序列号处理、使用 Protobuf 定义数据结构

在业务环境回放系统中，数据结构是系统的骨架。一个设计不良的数据结构会导致回放失真、存储膨胀、序列化性能低下。本章将深入定义回放事件（Event）模型、元数据（Metadata）、时间戳与序列号的处理策略，并最终使用 Protobuf 进行工程落地。

3.1 回放事件（Event）模型设计

回放事件是系统中最核心的实体，它记录了业务系统中发生的每一次状态变更。一个完整的事件模型需要包含“发生了什么”、“何时发生”、“谁触发的”以及“上下文是什么”。

我们采用分层设计来组织事件结构，分为 事件头（EventHeader） 和 事件体（EventBody）。

• 事件头（EventHeader）： 包含全局唯一标识、时间戳、序列号、事件来源、版本号等元信息。这部分是每个事件的固定开销。
• 事件体（EventBody）： 包含业务相关的具体数据，如订单状态变更、用户操作指令、数据库变更记录等。这部分是可变长度的，根据业务类型不同而不同。

3.2 元数据（Metadata）定义

元数据是描述事件数据的数据。在回放系统中，元数据不仅用于索引和检索，还用于控制回放的行为，例如过滤、重放速率、依赖注入等。

我们将元数据分为两类：系统元数据 和 业务元数据。

3.3 时间戳与序列号处理

时间戳和序列号是保证回放顺序和一致性的关键。在分布式系统中，单纯依赖系统时间戳是不可靠的，因为不同机器之间存在时钟漂移。

3.3.1 时间戳策略

• 业务时间戳（Business Timestamp）： 记录业务实际发生的时间，由业务系统生成，用于回放时的“时间轴”对齐。
• 记录时间戳（Record Timestamp）： 记录事件被持久化到存储系统的时间，由中间件或存储层生成，用于监控和延迟分析。

3.3.2 序列号策略

序列号用于解决同一时间戳下多个事件的顺序问题。我们采用 全局递增序列号 结合 分片序列号 的方案。

• 全局序列号（Global Sequence）： 由中心化发号器（如 Redis INCR、Snowflake）生成，保证全局唯一且递增。
• 分片序列号（Shard Sequence）： 在同一个业务实体（如某个订单）内递增，用于保证单个实体的事件顺序。

3.4 使用 Protobuf 定义数据结构

Protobuf（Protocol Buffers）是 Google 推出的语言中立、平台中立、高效的序列化框架。相比 JSON，Protobuf 具有更小的数据体积、更快的解析速度以及强类型约束，非常适合回放事件这种高频写入和读取的场景。

3.4.1 核心 Protobuf 定义

syntax = "proto3";
package replay.v1;
option go_package = "github.com/example/replay/proto/v1;replayv1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/any.proto";

// 事件头
message EventHeader {
  string event_id = 1;                    // 全局唯一事件ID (UUID)
  google.protobuf.Timestamp business_time = 2; // 业务时间戳
  int64 global_sequence = 3;             // 全局递增序列号
  int32 shard_sequence = 4;              // 分片序列号 (实体内递增)
  string source_system = 5;              // 来源系统
  int32 event_version = 6;               // 事件版本号
  string trace_id = 7;                   // 分布式追踪ID
}

// 元数据
message Metadata {
  string entity_type = 1;                // 业务实体类型
  string entity_id = 2;                  // 业务实体ID
  map<string, string> tags = 3;         // 自定义标签
}

// 回放事件
message ReplayEvent {
  EventHeader header = 1;                // 事件头
  Metadata metadata = 2;                 // 元数据
  google.protobuf.Any payload = 3;       // 业务负载 (支持多类型)
}

// 示例：订单状态变更事件体
message OrderStatusChanged {
  string order_id = 1;
  string old_status = 2;
  string new_status = 3;
  int64 changed_at_unix = 4;
}

3.4.2 关键设计决策

3.4.3 Go 代码集成示例

package main

import (
    "fmt"
    "time"
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/types/known/anypb"
    "google.golang.org/protobuf/types/known/timestamppb"
    replayv1 "github.com/example/replay/proto/v1"
)

func main() {
    // 构造业务事件体
    orderEvent := &replayv1.OrderStatusChanged{
        OrderId:    "ORD-2024-001",
        OldStatus:  "PENDING",
        NewStatus:  "PAID",
        ChangedAtUnix: time.Now().Unix(),
    }

    // 将业务事件体包装为 Any 类型
    payloadAny, _ := anypb.New(orderEvent)

    // 构造完整回放事件
    event := &replayv1.ReplayEvent{
        Header: &replayv1.EventHeader{
            EventId:       "evt-abc-123",
            BusinessTime:  timestamppb.Now(),
            GlobalSequence: 10001,
            ShardSequence:  1,
            SourceSystem:   "order-service",
            EventVersion:   1,
            TraceId:        "trace-xyz-789",
        },
        Metadata: &replayv1.Metadata{
            EntityType: "order",
            EntityId:   "ORD-2024-001",
            Tags:       map[string]string{"env": "production"},
        },
        Payload: payloadAny,
    }

    // 序列化为二进制
    data, _ := proto.Marshal(event)
    fmt.Printf("Serialized size: %d bytes\n", len(data))

    // 反序列化
    newEvent := &replayv1.ReplayEvent{}
    proto.Unmarshal(data, newEvent)
    fmt.Printf("Event ID: %s\n", newEvent.Header.EventId)
}

3.5 本章小结

本章完成了回放系统核心数据结构的完整设计：

• 采用 EventHeader + EventBody 的分层模型，分离元信息与业务数据。
• 明确定义了 系统元数据 和 业务元数据 的职责边界。
• 使用 业务时间戳 + 全局序列号 + 分片序列号 的组合策略，解决了分布式环境下的顺序问题。
• 通过 Protobuf 实现了高效、强类型、可扩展的序列化方案，并给出了完整的 Go 集成示例。