// ❌ 反例：坐标用双精度浮点 + 字符串设备ID
message LocationBad {
  double latitude = 1;   // 固定8字节
  double longitude = 2;  // 固定8字节
  string device_id = 3;  // 长度前缀 + UTF-8字节
}

// ✅ 正例：定点整数 + 定长Bytes
message LocationGood {
  // 经纬度乘1e6存为sint32，ZigZag编码后±180°仅需3~4字节
  sint32 latitude_e6  = 1;
  sint32 longitude_e6 = 2;
  // 设备ID改为16字节固定Bytes（UUID/MD5），省去长度前缀
  bytes  device_id    = 3;  
}

// ❌ 多层嵌套
message SignalBad {
  Header header = 1;      // +1字节tag +1字节len
  Body   body   = 2;      // +1字节tag +1字节len
}
message Header { uint32 version = 1; uint32 seq = 2; }
message Body   { Payload payload = 1; }
message Payload { bytes data = 1; }

// ✅ 扁平化合并
message SignalGood {
  uint32 version = 1;
  uint32 seq     = 2;
  bytes  data    = 3;     // 直接内联
}

// Proto3 默认已开启 packed，Proto2 需显式声明
repeated uint32 sensor_readings = 10 [packed = true];

message DeviceStatus {
  // 仅在异常时填写，正常上报自动省略
  uint32 error_code      = 10;  // 0 = 正常，不编码
  string error_detail    = 11;  // 空串不编码
  repeated uint32 warn_list = 12; // 空数组不编码
}

message SignalEnvelope {
  uint32 seq_id = 1;
  // 仅下发设备关心的字段集合
  google.protobuf.FieldMask field_mask = 2;
  // 核心字段常驻，扩展字段按需挂载
  oneof payload {
    CoreSignal   core   = 10;
    ExtendedSignal ext  = 11;
    MinimalSignal min   = 12;  // 极简模式仅含 seq+cmd
  }
}

                    ┌─ 对延迟极度敏感(<1ms) ──► LZ4 HC
                    │
    信令链路类型 ───┤
                    │        ┌─ 需浏览器原生支持 ──► Brotli
                    └─ 通用长连接/HTTP ──► Zstd (默认首选)

// Go 服务端：Zstd 流式压缩，零拷贝复用缓冲区
import (
    "github.com/klauspost/compress/zstd"
    "google.golang.org/protobuf/proto"
)

var encoder, _ = zstd.NewWriter(nil, zstd.WithEncoderLevel(zstd.SpeedBetterCompression))
var decoder, _ = zstd.NewReader(nil)

func EncodeAndCompress(msg proto.Message) ([]byte, error) {
    pbData, err := proto.Marshal(msg)
    if err != nil { return nil, err }
    // 原地压缩，避免二次分配
    return encoder.EncodeAll(pbData, make([]byte, 0, len(pbData)*2/3)), nil
}

// 单次信令处理周期复用同一 Arena，批量释放零碎片
google::protobuf::ArenaOptions opts;
opts.initial_block_size = 4096;   // 匹配典型MTU
opts.max_block_size     = 16384;
google::protobuf::Arena arena(opts);

// 解析直接落在 Arena 上，无需逐字段 malloc
SignalMessage* msg = google::protobuf::Arena::CreateMessage<SignalMessage>(&arena);
bool ok = msg->ParseFromArray(zbuf, zlen);  // 零拷贝解析（配合 Zstd 流式解压）
// 业务逻辑处理...
// 作用域结束自动销毁 Arena，一次性归还内存，耗时 < 1 μs

// 终端侧 .proto 文件头部强制声明
option optimize_for = CODE_SIZE;   // 生成最小化序列化代码，牺牲约 15% 速度换 40% 体积
option cc_enable_arenas = true;    // 必须开启，配合 Arena 使用

message UnreliableSignal {
  // 5bit seq + 3bit type = 1字节包头（手工位域编码，非标准Protobuf）
  // 仅在应用层做去重，不依赖TCP重传
  uint32 seq_type_packed = 1;  
  bytes  payload         = 2;   // 业务载荷
}

// ❌ 反例：双拷贝（网络buf -> string -> pb结构体）
func HandleBad(conn net.Conn) {
    buf := make([]byte, 4096)
    n, _ := conn.Read(buf)
    var msg Signal
    proto.Unmarshal(buf[:n], &msg)  // 内部再次拷贝
}

// ✅ 正例：零拷解析 + 对象池复用
var msgPool = sync.Pool{New: func() any { return &Signal{} }}

func HandleGood(conn net.Conn) {
    // 1. 直接读入预分配缓冲区
    buf := bufferPool.Get().([]byte)[:cap(buf)]
    n, _ := conn.Read(buf)
    
    // 2. 从池取对象，反序列化复用内存
    msg := msgPool.Get().(*Signal)
    msg.Reset()          // 重置而非新建
    proto.UnmarshalOptions{Merge: true}.Unmarshal(buf[:n], msg)
    
    // 3. 业务处理完归还
    defer func() { bufferPool.Put(buf); msgPool.Put(msg) }()
    process(msg)
}

# Go 编译标签开启 SIMD（需 CPU 支持）
go build -tags=avx2,avx512 ./...

// 根据 Profile 热度排序字段（高频在前）
message HotSignal {
  uint64 timestamp   = 1;  // 100% 命中
  uint32 seq_id      = 2;  // 100% 命中
  int32  temperature = 3;  // 95% 命中
  // 低频诊断字段置后，冷数据不污染 L1 Cache
  bytes  diag_log    = 100; 
}

message SecureSignal {
  // 明文字段：路由、调度所需
  uint32 device_id   = 1;
  uint32 timestamp   = 2;
  
  // 密文字段：AES-GCM 加密后的 Payload
  // 格式：[Nonce(12B) || Ciphertext || Tag(16B)]
  bytes  enc_payload = 10 [(encrypt) = true];  // 自定义 Option 标记
  
  // 密钥版本，支持平滑轮换
  uint32 key_version = 11;
}

// 基于 Protobuf 插件生成的 FieldMask 自动识别敏感字段
public class FieldEncryptInterceptor implements ServerInterceptor {
  @Override
  public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
      ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
    return new ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT>(
        next.startCall(new ForwardingServerCall.SimpleForwardingServerCall<ReqT, RespT>(call) {
          @Override
          public void sendMessage(RespT message) {
            // 响应前自动加密标注字段
            CryptoUtils.encryptSensitiveFields(message); 
            super.sendMessage(message);
          }
        }, headers));
  }
}

// Go 服务端强制限制
opts := proto.UnmarshalOptions{
    DiscardUnknown: true,        // 忽略未知字段，防止字段注入攻击
    MaxDepth:       32,          // 防止深度嵌套 DoS (CVE-2021-22569 类)
    MaxSize:        64 * 1024,   // 单条信令硬性上限 64KB
}
msg := &Signal{}
if err := opts.Unmarshal(data, msg); err != nil {
    metrics.Inc("signal.parse.fail", "reason", err.Error())
    return ErrMalformedSignal
}

Parser<Signal> parser = Signal.parser()
    .setRecursionLimit(32)
    .setSizeLimit(64 * 1024);

START
  │
  ├─ 需零拷贝/微秒级延迟？ ──Yes──► FlatBuffers / Cap'n Proto
  │                                    (需自行维护 Schema 迁移工具)
  │
  ├─ 设备端 < 64KB RAM？ ──Yes──► NanoPB / upb (Protobuf 子集)
  │
  ├─ 跨语言/长期维护/运维成熟度优先？ ──Yes──► **Protobuf (推荐基线)**
  │
  ├─ 纯内部高性能 RPC？ ──Yes──► Cap'n Proto (配合 RPC 框架)
  │
  └─ 前端直连/调试友好/无代码生成？ ──Yes──► MessagePack / JSON

# buf.yaml (根目录)
version: v1
name: buf.build/your-org/signaling
deps:
  - buf.build/googleapis/googleapis
  - buf.build/protocolbuffers/wellknowntypes
lint:
  use:
    - DEFAULT
    - PACKAGE_VERSION_SUFFIX
    - FIELD_NOT_REQUIRED      # 禁用 required (Proto3 已移除)
    - ENUM_ZERO_VALUE_SUFFIX  # 枚举首项必须为 _UNSPECIFIED
  except:
    - FIELD_LOWER_SNAKE_CASE  # 兼容历史驼峰字段
breaking:
  use:
    - FILE        # 文件级破坏性检测
    - PACKAGE     # 包级
    - WIRE_JSON   # 兼容 JSON 映射
    - WIRE        # 二进制兼容

- name: Buf Lint & Breaking
  uses: bufbuild/buf-action@v1
  with:
    args: "lint breaking --against '.git#branch=main'"

// Pact / Spring Cloud Contract 片段
@Pact(consumer = "Gateway", provider = "SignalService")
V4Pact signalContract() {
    return ConsumerPactBuilder
        .consumer("Gateway")
        .hasPactWith("SignalService")
        .given("设备在线")
        .uponReceiving("心跳上报")
        .path("/api/v1/signal")
        .method("POST")
        .body(newJsonBody { o ->
            o.stringType("cmd", "HEARTBEAT")
            o.numberType("seq", 12345)
            o.object("payload") { p ->
                p.numberType("battery", 85)
                p.stringType("firmware", "v2.1.0")
            }
        })
        .willRespondWith()
        .status(200)
        .body(newJsonBody { o ->
            o.stringType("status", "ACK")
        })
        .toPact(V4Pact.class)
}

graph LR
    A[开发提交 .proto 变更] --> B{buf breaking 检测}
    B -- 通过 --> C[生成多语言 SDK 发布至私有仓库]
    B -- 失败 --> D[阻断合并/要求 reserved 标记]
    C --> E[Canary 部署网关 5% 流量]
    E --> F{监控指标<br/>解码失败率/体积/延迟}
    F -- 正常 --> G[全量发布]
    F -- 异常 --> H[自动回滚+告警]