文章目录YAML、JSON、TOML 到底怎么选一份机器人协议配置讲明白一、一个真实场景描述一份通信协议二、从 .txt 到 YAML配置文件的进化三、YAML 到底是什么四、配置表居然能自动生成代码五、为什么要这么设计六、YAML vs JSON vs TOML对比表使用场景YAML 的一个坑知道就行七、总结YAML、JSON、TOML 到底怎么选一份机器人协议配置讲明白最近接触了一个机器人的通信协议 SDK第一次见到「用 YAML 写配置文件、还能自动生成 C 代码」的操作彻底搞懂后写成这篇记录。适合还没分清楚 YAML / JSON / TOML 区别、或者好奇「配置表为啥能自动生成代码」的同学。一、一个真实场景描述一份通信协议一个机器人系统有三个「端」要互相通信上位机C主控板跑 ROS单片机固件C下位机它们之间传的数据帧格式是固定的AA 55 | ver | len | type | payload | crc16其中 payload 又分两种帧控制指令上位机发下去模式、使能、各方向速度、目标值……遥测数据板子回上来姿态、位置、电量、温度、各电机输出……这么多字段还带单位、范围、说明怎么把它「描述」清楚、并且让三个端都用上同一份答案就是一个 YAML 配置文件 代码生成。二、从 .txt 到 YAML配置文件的进化很多人以前写配置用的是.txt纯文本CmdPacket.type0x01 CmdPacket.field1.namemode CmdPacket.field1.typeu8 CmdPacket.field2.namevx CmdPacket.field2.typef32纯文本没有结构程序要「看懂」它得自己写解析代码而且层级只能靠名字硬拼一长串又丑又容易错。YAML 用缩进自然表达层级一眼看清「谁属于谁」CmdPacket:type:0x01fields:-name:modetype:u8-name:vxtype:f32-name:vytype:f32哪种好读、哪种不容易写错一目了然。三、YAML 到底是什么YAMLYAML Ain’t Markup Language是一种数据描述格式不是编程语言。你可以把它理解成一份「用缩进和冒号写的配置表」。语法其实就 4 种key: value—— 键值对缩进—— 表示层级谁属于谁-—— 列表项#—— 注释四、配置表居然能自动生成代码这是最有意思的部分。这份protocol.yaml不是给人手写的代码而是**「唯一的真相」single source of truth**。一个叫codegen.py的脚本读它自动生成C 头文件上位机用C 头文件单片机用ROS 的.msg主控板用协议文档测试用的 golden 字节向量YAML 里这一行-name:vxtype:f32codegen 自动生成 Cfloatvx{};// 前后速度再看几个对应关系YAML 里写的生成的 C- name: enabledtype: u8uint8_t enabled{};- name: vxtype: f32float vx{};- name: motorstype: f32count: 8float motors[8]{};五、为什么要这么设计核心就一句话多个端共用同一份协议必须字节级一致手写多份必出错。多个端必须「字节级一致」—— 通信靠的是字节。如果 C 里vx排第 4 个字段、C 里排第 5 个上位机发的数据单片机就解析错了设备直接失控。手写多份必出错—— 在 C / C / .msg 几个地方各写一遍十几个字段的结构体字段顺序写反、类型写错、漏加一个字段任何一个小错都是「上位机能发、板子解析不对」这种极难排查的 bug。改协议只改一处—— 假设要加一个字段只在 YAML 加 3 行-name:lighttype:u8跑一下 codegen所有端的代码、文档、测试向量全部自动更新不可能漏。文档永远不过时—— 文档是从 YAML 自动生成的永远和协议一致。这个套路很经典protobuf就是这么干的写.proto描述文件protoc生成各语言代码。你现在遇到它以后还会在数据库 schema、OpenAPI 这些地方反复见到。六、YAML vs JSON vs TOML同样是「结构化文本格式」区别在语法风格和适用场景。同一份数据三种写法JSON花括号、方括号、双引号、逗号{name:robot,version:2,fields:[{name:mode,type:u8},{name:vx,type:f32}]}YAML缩进、冒号、短横线name:robotversion:2fields:-name:modetype:u8-name:vxtype:f32TOMLkey value、[表头]name robot version 2 [[fields]] name mode type u8 [[fields]] name vx type f32对比表特性JSONYAMLTOML可读性中标点符号多最高高支持注释❌ 不支持✅✅表达层级花括号/方括号缩进自然[section]表头缩进敏感否✅缩进即结构否通用性最高Web 标准高配置/CI中配置使用场景格式典型场景JSONWeb API 数据交换、程序间通信机器对机器首选YAML给人读/写的配置文件、CI/CDGitHub Actions、Docker Compose、K8sTOML配置里想要「注释 明确类型 不踩缩进坑」Rust 的 Cargo.toml、Python 的 pyproject.toml一句话记JSON 给机器用YAML 给人看TOML 折中。YAML 的一个坑知道就行YAML 缩进必须用空格、不能用 Tab而且yes/no这种裸字符串会被解析成布尔值true/false叫「挪威问题」。所以写 YAML 时字符串最好加引号、缩进统一用空格。七、总结.txt无结构简单键值对够用。YAML / JSON / TOML有结构复杂配置更清晰。选谁机器对机器用 JSON给人读的配置用 YAML想要注释又怕缩进坑用 TOML。代码生成当一份数据要多处一致、频繁修改、还要配套文档测试时用「单一数据源 代码生成」能省大量心、也杜绝不一致的 bug。如果你也在做多端通信协议强烈建议试试「一份 YAML 当唯一真相、代码自动生成」这个套路。