物联网 Protobuf实战第一篇

物联网 protobuf 相关约定和定义

项目结构

定义相关protobuf文件说明

├── common/                          # 公共基础类型
│   ├── header.proto                # 消息头定义
│   ├── device_status.proto         # 设备状态
│   ├── ack.proto                   # 确认响应
│   └── enums.proto                 # 通用枚举
├── upload/                          # 上行消息（设备→云）
│   ├── device_upload.proto         # 上传消息主结构
│   ├── sensor_data.proto           # 传感器数据
│   └── event_data.proto            # 事件数据
├── command/                         # 下行消息（云→设备）
│   ├── device_command.proto        # 命令消息主结构
│   ├── config_update.proto         # 配置更新
│   ├── fota_update.proto           # 固件升级
│   └── control_command.proto       # 控制命令
└── response/                        # 响应消息
    └── response.proto      # 命令响应

🎯 设计规范的目的

1. 模块化分离（Modular Separation）

目的：将不同职责的消息类型分离到独立目录，提高可维护性和可扩展性
实现：
- common/：存放所有模块共享的基础类型（消息头、枚举、设备状态等）
- upload/：专门处理设备到云平台的上行数据（传感器数据、事件上报）
- command/：专门处理云平台到设备的下行指令（配置更新、FOTA、控制命令）
- response/：统一处理设备响应消息
优势：
- ✅ 职责清晰，每个目录专注单一业务领域
- ✅ 降低耦合，修改某个模块不影响其他模块
- ✅ 便于团队协作，不同开发人员可并行工作

2. 版本化管理（Versioning）

目的：支持协议演进和多版本共存，避免破坏性变更影响现有设备
实现：使用 v1/ 目录标识协议版本，未来可并行存在 v2/、v3/ 等
版本演进策略：
- 向后兼容：新增字段使用可选字段或 oneof 扩展，不删除已有字段
- 废弃标记：使用 reserved 关键字标记已废弃的字段编号
- 多版本共存：v1 设备和 v2 设备可同时接入，服务端根据 Header.version 路由
优势：
- ✅ 平滑升级，新旧设备可同时运行
- ✅ 灰度发布，逐步推广新协议
- ✅ 回滚能力，出现问题可快速切回旧版本

3. 单向依赖原则（Unidirectional Dependency）

目的：避免循环依赖，确保编译顺序清晰
实现：
- 业务模块（upload/command）依赖 common 模块
- common 模块不依赖任何业务模块
- 同一层级模块间互不依赖
依赖关系图：
优势：
- ✅ 编译顺序明确，避免循环引用错误
- ✅ 层次清晰，易于理解和维护
- ✅ 便于单元测试，可独立测试各模块

4. 消息完整性（Message Integrity）

目的：每条消息包含完整的上下文信息，支持追踪、认证、QoS 保障
实现：
- 所有上行消息包含 Header（消息ID、时间戳、trace_id、QoS等级）
- 支持 need_ack 标志位实现可靠传输
- 内置 auth_token 支持设备认证
优势：
- ✅ 全链路追踪，便于故障排查和性能分析
- ✅ 可靠传输，关键消息不丢失
- ✅ 安全认证，防止非法设备接入