1. 为什么在 STM32 上用一个代码开发工具解析 JSON,而不是手拼字符串
设备通过串口收到上位机下发的一串配置,形如 {"device_id":"stm32-001","interval":500},字段少的时候用 strstr 找冒号、atoi 转数字还能凑合;字段一多、嵌套一层、数组一出现,手写解析就开始翻车。cJSON 是这类场景里移植成本最低的代码开发工具之一:纯 C、只依赖标准库的 malloc/free、把 cJSON.c 和 cJSON.h 拖进工程就能编。它不负责网络、不负责协议,只做一件事——把 JSON 字符串变成可遍历的树,再把树变回字符串。适合手里有串口或网口、需要和上位机交换结构化数据,又不想在 MCU 上引入重量级框架的嵌入式工程师。接下来按「移植进 MDK → 解析取字段 → 序列化上报 → 避坑」这条线走一遍,每一步都给出可照做的代码和参数说明。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 把 cJSON 纳入 MDK 工程:一个代码开发工具的移植清单
cJSON 的移植本身不复杂,翻车多半不在算法,而在头文件路径、堆大小和重复文件这三件小事上。我一般会先做一个只包含 Parse/Delete 的空壳验证,确认编译链和堆能跑通,再往上写业务字段。这样出问题时边界很清楚:空壳都跑不过,先查工程配置;空壳能过、业务字段取不到,再查 JSON 报文和字段名。
2.1 只搬两个文件:cJSON.c 与 cJSON.h 的落位
拿到 cJSON 源码后,真正需要进工程的通常只有两个文件,不要整个目录一股脑拖进去:
| 文件 | 作用 | 放置位置 |
|---|---|---|
| cJSON.c | 解析、构建、打印的实现 | 工程目录/ThirdParty/cJSON/ |
| cJSON.h | 对外类型和函数声明 | 同上 |
操作步骤不复杂,但每一步都有对应的失败现象:
- 在工程根目录建
ThirdParty/cJSON,把cJSON.c、cJSON.h复制进去。只复制.h不复制.c,链接期会报一堆undefined symbol。 - 在 MDK 里右键目标 Group,选 Add Existing Files,把
cJSON.c加进去。不要在两个 Group 里重复添加同一个文件,否则链接期报L6200E: Symbol ... multiply defined。 - 打开 Options for Target → C/C++ → Include Paths,把
ThirdParty/cJSON加进去。路径要按工程文件所在目录算相对路径,不能按你当前打开的文件算。 - 编译。如果报
cJSON.h: No such file or directory,先回头查 Include Paths;如果报重复定义,先查是不是工程里还留着一份旧副本。 - 如果工程里已经有别的 JSON 库,注意符号冲突。常见做法是给 cJSON 的函数加统一前缀,或者把它单独编成静态库再链接,避免和现有代码撞名。
这一步做完,先别急着写业务。加一个最小验证函数,确认三个入口能编能跑:
c复制#include "cJSON.h"
void cjson_smoke_test(void)
{
const char *text = "{\"ok\":1}";
cJSON *root = cJSON_Parse(text);
if (root == NULL) {
const char *err = cJSON_GetErrorPtr();
printf("smoke parse failed near: %s\r\n", err ? err : "unknown");
return;
}
cJSON *ok = cJSON_GetObjectItem(root, "ok");
if (cJSON_IsNumber(ok)) {
printf("ok=%d\r\n", (int)cJSON_GetNumberValue(ok));
}
cJSON_Delete(root);
}
这段代码只验证 cJSON_Parse、cJSON_GetObjectItem、cJSON_Delete 三个入口。cJSON_Parse 接收以 '\0' 结尾的字符串;cJSON_GetObjectItem 的第二个参数是字段名,返回的是树内节点,不要单独释放;cJSON_GetNumberValue 返回 double,打印前按业务需要转成 int。如果这一步就 HardFault,先查堆,不要查 JSON 语法。
2.2 堆从哪里来:Heap_Size 与峰值估算
cJSON 默认走 malloc/free,在 STM32 上就是启动文件里的 Heap。启动文件里通常能看到这样一行:
asm复制; startup_<device>.s
Heap_Size EQU 0x00000400
这个值不是给 cJSON 专用的,但你要把 JSON 的峰值算进去。峰值大致由三块组成:输入字符串本身(cJSON_Parse 内部会复制一份)、解析树的节点开销(每个节点有类型、兄弟/子节点指针、字符串指针等)、序列化输出缓冲(cJSON_PrintUnformatted 返回的 char *)。常见做法是先把 Heap_Size 调大,跑通业务,再用自己包的 malloc/free 计数把峰值压回来;不要一上来就抠到刚好,解析大报文时偶发返回 NULL 很难查。
cJSON 提供了 cJSON_InitHooks 用来替换分配器,我一般在调试阶段把 malloc_fn 和 free_fn 换成带计数的版本,每次解析前后打印一次堆用量。这样能直接看到「解析前多少、解析峰值多少、释放后有没有回到基线」。如果释放后回不到基线,基本就是某条 return 分支漏了 cJSON_Delete,不用怀疑玄学。
2.3 为什么选 cJSON 而不是自己写状态机
自己写一个只认固定字段的解析器当然可以,但 JSON 的边界情况比想象的多:字符串里的转义引号、嵌套对象、数组、数字和字符串的类型区分。这些边界在联调时不一定一次暴露,等上位机换一版报文格式,手写解析就要重写。cJSON 的 API 少,解析和生成对称,报文格式变化时通常只改字段提取部分,解析骨架不用动。
它的限制也要提前知道:cJSON 是 DOM 模式,整棵树都在堆上,不适合超大报文;没有流式解析,报文必须一次性拿到完整字符串;数字统一用 double,在 MCU 上做大量浮点运算要考虑开销。知道这些边界,才不会在选型之后又回头怪工具。
3. 解析链路:从字符串到结构体的最小可运行代码
解析要分两层看:第一层是语法,第二层是业务类型。很多人把两层混在一起,cJSON_Parse 返回非 NULL 就直接取字段,字段不存在或类型不对就崩。下面按「先过语法、再过类型、最后取字段」的顺序写,每一层失败都有独立的出口。
3.1 cJSON_Parse 返回非 NULL 只代表语法通过
c复制cJSON *root = cJSON_Parse(json_str);
if (root == NULL) {
const char *err_pos = cJSON_GetErrorPtr();
printf("json parse failed near: %s\r\n", err_pos ? err_pos : "unknown");
return;
}
if (!cJSON_IsObject(root)) {
printf("root is not object\r\n");
cJSON_Delete(root);
return;
}
cJSON_Parse 成功只说明括号、引号、逗号这些语法层面没问题,不代表根是对象,也不代表业务字段存在。cJSON_GetErrorPtr 返回的指针只在解析失败时有效,而且指向输入串内部,不要存到全局日志结构体里。cJSON_IsObject 失败也必须 cJSON_Delete(root),这一步漏了,后面每解析一次错报文就漏一棵树。
实际调试时,我习惯在失败分支里把 err_pos 附近的内容打印出来,而不是只打印一个「parse failed」。比如 err_pos 指向的字符和它后面十几个字节,能很快看出是少了逗号、多了个未转义引号,还是报文根本没发全。
3.2 取字段:GetObjectItem 之后必须做类型判断
c复制cJSON *id_item = cJSON_GetObjectItem(root, "device_id");
if (!cJSON_IsString(id_item)) {
printf("device_id missing or not string\r\n");
goto cleanup;
}
const char *device_id = cJSON_GetStringValue(id_item);
cJSON *interval_item = cJSON_GetObjectItem(root, "interval");
if (!cJSON_IsNumber(interval_item)) {
printf("interval missing or not number\r\n");
goto cleanup;
}
int interval = (int)cJSON_GetNumberValue(interval_item);
cJSON_GetObjectItem 返回的是树内节点,生命周期跟随 root;cJSON_GetStringValue 返回的指针也指向树内,root 被 cJSON_Delete 之后不能再用。数字用 double 取再转,注意业务范围,比如 interval 如果约定是 0 到 3600000,取出来之后要自己夹一下,不要直接拿去开定时器。
字段可选时,先判断 item 是否为 NULL,再判断类型。比如 device_id 是必填,缺失就返回错误;interval 有默认值,缺失时用默认值,不要直接判成报文错误。
3.3 嵌套对象和数组:一层一层取,不要跨层猜
c复制cJSON *config = cJSON_GetObjectItem(root, "config");
if (cJSON_IsObject(config)) {
cJSON *mode = cJSON_GetObjectItem(config, "mode");
if (cJSON_IsString(mode)) {
const char *mode_str = cJSON_GetStringValue(mode);
/* 按 mode_str 分支 */
}
}
cJSON *samples = cJSON_GetObjectItem(root, "samples");
if (cJSON_IsArray(samples)) {
int n = cJSON_GetArraySize(samples);
for (int i = 0; i < n; i++) {
cJSON *item = cJSON_GetArrayItem(samples, i);
if (cJSON_IsNumber(item)) {
/* 处理第 i 个元素 */
}
}
}
cJSON_GetArraySize 返回元素个数,cJSON_GetArrayItem 按下标取;不要对非数组节点调用这两个接口,先 cJSON_IsArray。嵌套对象也是同理,先取父节点、判断是对象,再取子字段,不要拿一个可能为 NULL 的节点直接往下取,那是 HardFault 的常见来源。
3.4 统一出口:每个 return 前都要 Delete
c复制int parse_device_config(const char *json_str, device_cfg_t *cfg)
{
cJSON *root = NULL;
int ret = -1;
root = cJSON_Parse(json_str);
if (root == NULL) {
goto cleanup;
}
if (!cJSON_IsObject(root)) {
goto cleanup;
}
/* 业务字段提取,失败时 goto cleanup */
ret = 0;
cleanup:
if (root != NULL) {
cJSON_Delete(root);
}
return ret;
}
在 MCU 上,goto cleanup 的可读性比每个分支重复 cJSON_Delete 好,也更不容易漏。ret 表示业务结果,root 是否为空决定要不要释放。这个骨架可以直接复用到多条报文的解析入口,字段提取部分按业务替换。
4. 序列化上报:用 cJSON 这个代码开发工具自底向上建树
设备上报和解析是反方向。解析是树到字段,上报是字段到树再到字符串。cJSON 的构建 API 都围着节点转,每个创建函数都可能返回 NULL,链式写法看着短,失败时很难查。我一般把创建和挂接拆开写,先判空,再挂接。
4.1 Print 与 PrintUnformatted:调试口和业务口分开
cJSON 提供两个输出接口,本质区别只在于是否格式化:
| 接口 | 输出形态 | RAM 占用 | 适用场景 |
|---|---|---|---|
| cJSON_Print | 带缩进和换行 | 较高 | 人工看日志、调试 |
| cJSON_PrintUnformatted | 紧凑字符串 | 较低 | 串口、网络上报 |
两者都返回 malloc 出来的 char *,用完必须释放。格式化输出的空格和换行在协议对端可能造成解析失败,尤其是按行处理的简单协议。业务上报一律用 PrintUnformatted,只有调试口才用 Print,这样 RAM 峰值也可控。
4.2 自底向上构建:先建叶子,再挂到父节点
c复制void build_and_send_report(void)
{
cJSON *root = NULL;
cJSON *samples = NULL;
char *out = NULL;
root = cJSON_CreateObject();
if (root == NULL) {
return;
}
samples = cJSON_CreateArray();
if (samples == NULL) {
cJSON_Delete(root);
return;
}
cJSON_AddStringToObject(root, "device_id", "stm32-001");
cJSON_AddNumberToObject(root, "temperature", 26.5);
if (cJSON_AddItemToObject(root, "samples", samples) == 0) {
/* 挂接失败,samples 还归自己管 */
cJSON_Delete(samples);
cJSON_Delete(root);
return;
}
cJSON_AddItemToArray(samples, cJSON_CreateNumber(1));
cJSON_AddItemToArray(samples, cJSON_CreateNumber(2));
out = cJSON_PrintUnformatted(root);
if (out != NULL) {
uart_send_string(out);
cJSON_free(out);
}
cJSON_Delete(root);
}
cJSON_AddItemToObject 成功后,samples 的所有权转移给 root,cJSON_Delete(root) 会连它一起释放;失败则要自己 cJSON_Delete(samples)。cJSON_AddItemToArray 创建的数字节点也一样,Add 成功后归数组管。cJSON_PrintUnformatted 返回的 out 是独立缓冲区,要单独 cJSON_free。
4.3 输出长度和发送时机:别把 free 放在 DMA 发送之前
cJSON_PrintUnformatted 返回的是以 '\0' 结尾的字符串,长度用 strlen,不要用 sizeof。如果串口用 DMA 发送,必须等发送完成再 cJSON_free(out),否则 DMA 还在读一块已经释放的内存,现象是偶发乱码或 HardFault。阻塞发送则可以直接发完再释放。这个坑不玄学,但很容易在「先跑通再说」的阶段埋进去,等上报频率一高就翻车。
4.4 构建失败的分支:每个创建都要判 NULL
cJSON_CreateObject、cJSON_CreateArray、cJSON_CreateNumber、cJSON_CreateString 都可能返回 NULL。链式写法 cJSON_AddItemToArray(arr, cJSON_CreateNumber(x)) 如果 cJSON_CreateNumber 返回 NULL,Add 会失败,但代码没有检查,数组里少一个元素,上报数据静默丢失。常见做法是拆开写:先创建、判空,再挂接;挂接失败时把子节点释放掉,避免泄漏。
5. 避坑:cJSON 在单片机上最容易翻车的五个点
cJSON 的 API 少,但内存和指针的坑不少。下面五条都是我在联调时真实遇到过的,按「现象 → 原因 → 解决」写,每条都能从接口行为和参数约束上找到依据。
5.1 只取了一个字段,就以为不用 Delete
现象:设备连续运行几小时,malloc 开始返回 NULL,解析随机失败;重启后恢复正常。
原因:cJSON_Parse 在堆上建了整棵树,哪怕你只取了一个字段,树还在。只释放自己取的节点或完全不释放,都会泄漏。cJSON_Delete 释放的是整棵树,不是单个字段。
解决:统一 cleanup,所有解析路径最终都走 cJSON_Delete(root)。可以用第 3 章的 goto cleanup 结构。验证方法是连续跑一千次解析/释放,观察堆是否回到基线;如果每次下降一点,就是有分支漏了释放。
5.2 把 GetErrorPtr 的返回值存到全局日志
现象:解析成功后,日志里打印错误位置,出现乱码或 HardFault。
原因:错误指针只在解析失败时有效,而且指向输入缓冲区内部;输入 buffer 被复用或释放后,指针就悬空。把它存到全局结构体,等于保存了一个随时会失效的地址。
解决:只在失败分支里立即把 err_pos 附近的内容格式化到本地 buffer,成功分支不要碰它;不要把指针存到全局。日志里只保留格式化后的文本,不保留指针。
5.3 周期上报用 cJSON_Print
现象:串口抓包看到 JSON 里有换行和缩进,对端按行解析失败;RAM 峰值比预期高,偶发 malloc 失败。
原因:cJSON_Print 会格式化,输出的空格和换行占额外 RAM;协议对端通常只认紧凑 JSON。
解决:业务上报一律 cJSON_PrintUnformatted,只有调试口才用 cJSON_Print。两者返回的缓冲区都要释放,不能因为输出短就省略。
5.4 创建节点不判 NULL,直接 Add
现象:内存紧张时,cJSON_CreateObject 返回 NULL,后面 Add 触发 HardFault;或者数组少元素,上报数据静默丢失。
原因:每个创建函数都可能返回 NULL,链式写法把创建和挂接压在一行,失败没有分支。
解决:创建和挂接拆开,先判空再 Add;cJSON_AddItemToObject 失败时,子节点还归自己管,要手动 cJSON_Delete。上报数据静默丢失比 HardFault 更难查,因为设备看起来还在正常跑。
5.5 大报文一次 Parse,堆不够却当成语法错误
现象:同一条 JSON,小报文正常,大报文 cJSON_Parse 返回 NULL,cJSON_GetErrorPtr 指向开头或中间;换台内存更大的板子又正常。
原因:cJSON_Parse 内部会复制输入字符串,峰值内存是原串 + 树 + 节点开销;堆不够时返回 NULL,不一定是语法错。
解决:先按最大报文估算峰值,调大 Heap_Size;或者把大报文拆成多次解析;用分配计数确认峰值和回落。不要一看到返回 NULL 就去改 JSON 格式,先看堆。
6. 上线前的一道检查:把解析封装成可重复验证的入口
解析代码写完不等于能上线。我一般会把返回值分类,让上层能区分「报文语法错」「字段类型错」「内存不够」,而不是所有失败都打印成一句「解析失败」。下面这个封装骨架可以直接套:
c复制typedef enum {
JSON_RESULT_OK = 0,
JSON_RESULT_SYNTAX,
JSON_RESULT_TYPE,
JSON_RESULT_MEM
} json_result_t;
json_result_t parse_device_config(const char *text, device_cfg_t *cfg)
{
cJSON *root = cJSON_Parse(text);
if (root == NULL) {
return JSON_RESULT_SYNTAX;
}
if (!cJSON_IsObject(root)) {
cJSON_Delete(root);
return JSON_RESULT_TYPE;
}
cJSON *id_item = cJSON_GetObjectItem(root, "device_id");
if (!cJSON_IsString(id_item)) {
cJSON_Delete(root);
return JSON_RESULT_TYPE;
}
/* 其余字段提取
