30 lines
3.8 KiB
Markdown
30 lines
3.8 KiB
Markdown
---
|
||
tags: []
|
||
aliases:
|
||
- 2.5 数据结构定义与序列化规范 (Data Structure Definition & Serialization Specification)
|
||
date created: 星期一, 十一月 24日 2025, 5:21:10 下午
|
||
date modified: 星期一, 十一月 24日 2025, 5:21:21 下午
|
||
---
|
||
|
||
# 2.5 数据结构定义与序列化规范 (Data Structure Definition & Serialization Specification)
|
||
|
||
- **覆盖范围**：定义系统内外部数据交互的**静态契约**。该规范严格区分 **“内部原生对象（In-Memory Native Objects）”** 与 **“外部传输契约（On-Wire Contracts）”**，并界定两者之间的**转换边界**。内部关注极致的计算性能（SIMD 对齐、零拷贝），外部关注跨语言/跨平台的互操作性（Protobuf）。
|
||
- **2.5.1 内部高性能业务对象模型 (Internal High-Performance Business Object Model)**
|
||
- **核心指向**：定义在 `DataReceiver` -> `SignalProcessor` -> `DataProcessor` 流水线中流转的 C++ 原生结构体（DTO）。涵盖 `DetectionResult`（点迹）和 `TrackData`（航迹）的内存布局设计，强制使用 **POD (Plain Old Data)** 类型，并应用 `alignas(16/32)` 以适配 **SIMD (AVX/NEON)** 向量化指令优化，严禁在核心计算路径上使用虚函数或复杂对象。
|
||
- **2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)**
|
||
- **核心指向**：定义在 `EventBus` 上流转的控制信令结构。所有事件必须继承自 `BaseEvent`，并强制包含 **全链路追踪 ID (`TraceID`)** 和 **高精度时间戳**。事件负载（Payload）必须保持轻量（通常仅包含状态码、配置键值对或对象 ID），严禁携带大块业务数据（如 I/Q 波形），以保障控制平面的低延迟响应。
|
||
- **2.5.3 外部数据交换契约 (External Data Exchange Contract)**
|
||
- **核心指向**：定义系统向外部（显控终端、API 网关）输出数据的接口定义语言 (IDL)。强制选用 **Google Protobuf (v3)** 作为唯一标准。涵盖 `.proto` 文件的版本管理规范（语义化版本控制），以及字段的 **向前/向后兼容性** 设计原则（如使用 `optional` 字段，保留 `reserved` 标识符），确保前后端可独立演进。
|
||
- **2.5.4 零拷贝数据容器规范 (Zero-Copy Data Container Specification)**
|
||
- **核心指向**：定义承载内部业务对象的通用包装器 `DataPacket<T>`。涵盖其 **Header** 的标准化元数据（序列号、源模块、TraceID），以及 **Payload** 的所有权管理机制——必须使用 `std::unique_ptr` 配合 **自定义删除器 (Custom Deleter)**，以实现内存块在生命周期结束时的自动归还（回收到 `MemoryPool`），彻底消除内存泄漏风险。
|
||
- **2.5.5 序列化边界与映射策略 (Serialization Boundary & Mapping Strategy)**
|
||
- **核心指向**：定义“内部对象”转换为“外部格式”的**唯一合法位置**。明确规定 **仅在 `DisplayController`（数据网关）** 和 **`ApiCommandService`（API 响应）** 处进行序列化操作。涵盖从 C++ Struct 到 Protobuf Message 的字段映射逻辑（Mapping Logic），以及在边界处进行 **数据清洗与脱敏** 的安全规范。
|
||
|
||
---
|
||
|
||
**核心变更点解析：**
|
||
|
||
1. **分离定义**：明确将 2.5.1 (内部高性能 C++) 与 2.5.3 (外部 Protobuf) 分开。旧设计可能在内部也混用了序列化对象，这是性能杀手，新设计予以纠正。
|
||
2. **容器规范**：新增 2.5.4，将 `DataPacket<T>` 和智能指针管理提升为核心规范，这是“零拷贝”落地的关键载体。
|
||
3. **边界管控**：新增 2.5.5，显式定义“序列化边界”。这是架构师视角的管控点，防止开发人员在内部模块（如信号处理）随意进行序列化导致性能劣化。
|