嵌入式JSON解析库：零内存分配、状态机驱动的确定性解析方案

1. 项目概述

Json是一个轻量级、零依赖、面向嵌入式场景设计的 JSON 解析库，核心目标是在资源受限的 MCU（如 Cortex-M0/M3/M4）上实现高效、安全、可预测的 JSON 数据解析能力。它不依赖标准 C 库的malloc/free，不使用递归调用，不分配动态内存，所有解析过程均在预分配的静态缓冲区中完成，符合 IEC 61508 SIL-3 和 ISO 26262 ASIL-B 等功能安全开发要求。

该库并非通用 JSON 库（如 cJSON 或 JSMN），其设计哲学是“确定性优先、内存可控、边界严防”。它不支持 JSON 生成（序列化），仅提供单向解析（deserialization）；不支持浮点数解析（避免 IEEE 754 实现差异与精度陷阱）；不支持嵌套深度超过编译期配置值的文档（防止栈溢出与不可控循环）；所有字符串访问均通过const char *+size_t len的零拷贝方式提供，避免隐式strlen调用与内存越界风险。

典型应用场景包括：

• 工业网关接收 Modbus TCP/HTTP REST 接口下发的设备配置指令（如{"cmd":"set_param","id":123,"value":45}）
• 汽车 TCU 从车载以太网 OTA 服务解析固件升级策略（如{"fw_version":"2.1.7","partition":"APP","crc32":3829471205}）
• 智能电表通过 LoRaWAN 接收远程抄表参数（如{"interval_s":300,"report_mode":"on_change"}）
• BLE Mesh 设备解析 provisioning 数据包中的网络密钥与地址分配信息

其最小 RAM 占用可低至192 字节（含 128 字节 token 缓冲 + 64 字节解析上下文），Flash 占用约1.8 KB（ARM GCC -Os 编译，Cortex-M4），可在 STM32F030F4（16KB Flash / 4KB SRAM）、Nordic nRF52810（192KB Flash / 24KB RAM）等主流低端 MCU 上稳定运行。

2. 核心设计原理与工程约束

2.1 零动态内存模型

嵌入式系统最严峻的挑战之一是动态内存管理的不确定性：malloc可能失败、碎片化导致后续分配失败、free引发内存泄漏或双重释放。Json库彻底规避该问题，采用静态上下文 + 用户提供缓冲区双层内存控制机制：

// 用户定义解析上下文（全局或静态变量） typedef struct { const char *json; // 指向原始 JSON 字符串首地址（必须生命周期长于解析过程） size_t len; // JSON 字符串总长度（非 null-terminated！） size_t pos; // 当前解析位置（字节偏移） uint8_t depth; // 当前嵌套深度（对象/数组层级） uint8_t max_depth; // 编译期配置的最大允许深度（默认 8） JsonToken tokens[JSON_MAX_TOKENS]; // 令牌池，存储 key/value/token 位置信息 uint8_t token_count; // 当前已识别令牌数量 } JsonParser; #define JSON_MAX_TOKENS 32 // 可解析的最大键值对+结构体元素总数（编译期常量）

所有解析状态（位置、深度、令牌索引）均保存在JsonParser结构体内，用户需在栈或.bss段中静态分配该结构体，并传入指向原始 JSON 数据的指针及长度。库内部绝不调用malloc、calloc、realloc或任何间接调用它们的函数（如strdup、asprintf）。

2.2 基于状态机的线性扫描解析器

Json不采用递归下降或 LL(1) 文法分析，而是实现一个确定性有限状态机（DFA），逐字节扫描输入流，根据当前状态和输入字符决定下一个状态与动作。状态机共定义 12 个核心状态（JSON_STATE_START,JSON_STATE_OBJECT_START,JSON_STATE_KEY,JSON_STATE_COLON,JSON_STATE_VALUE_STRING,JSON_STATE_VALUE_NUMBER,JSON_STATE_VALUE_TRUE,JSON_STATE_VALUE_FALSE,JSON_STATE_VALUE_NULL,JSON_STATE_ARRAY_START,JSON_STATE_ARRAY_VALUE,JSON_STATE_END），每个状态转移均经过严格边界检查。

关键工程保障：

• 无栈溢出风险：状态机为纯迭代实现，无函数递归调用；
• O(n) 时间复杂度：单次遍历完成全部解析，无回溯；
• 强错误定位：解析失败时返回pos偏移量，精确定位语法错误位置（如Unexpected character 'x' at offset 47）；
• UTF-8 兼容性：正确处理多字节 UTF-8 字符（如中文 key"温度"），但不对 Unicode 进行规范化，仅确保字节序列合法性。

2.3 零拷贝字符串访问与类型安全提取

为避免字符串复制开销与潜在越界，Json所有字符串访问均返回const char *指针与size_t len长度对，由用户自行决定是否复制或直接用于比较：

// 示例：安全提取并比较字符串值 const char *val_ptr; size_t val_len; if (json_get_string(&parser, "mode", &val_ptr, &val_len) == JSON_OK) { // 安全比较，无需 strlen 或 strcpy if (val_len == 4 && memcmp(val_ptr, "auto", 4) == 0) { set_mode(AUTO); } else if (val_len == 3 && memcmp(val_ptr, "off", 3) == 0) { set_mode(OFF); } }

数值解析同样遵循确定性原则：

• json_get_int32()：严格解析十进制整数（支持+/-符号），范围限定在INT32_MIN~INT32_MAX，溢出返回JSON_ERR_NUMBER_OVERFLOW；
• json_get_uint32()：仅接受无符号十进制，范围0~UINT32_MAX；
• 不支持浮点数：明确拒绝123.45、1e2等格式，返回JSON_ERR_UNSUPPORTED_TYPE，强制用户使用整数缩放（如temp_cx100: 2545表示 25.45℃）。

3. API 接口详解与使用范式

3.1 解析器初始化与主解析流程

Json的使用严格遵循三步式流程：初始化 → 解析 → 提取，确保状态清晰、资源可控。

典型初始化代码（HAL 风格）：

// 在 .c 文件顶部定义静态解析器（避免栈空间不足） static JsonParser g_json_parser; static char g_json_buffer[256]; // 用户提供的 JSON 输入缓冲区 void parse_received_json(const uint8_t *data, size_t data_len) { // 1. 复制数据到安全缓冲区（假设 data 来自 UART DMA，需保证 null-terminated？不！） // 注意：g_json_buffer 必须容纳 data_len 字节，且无需 '\0' if (data_len >= sizeof(g_json_buffer)) { return; // 缓冲区溢出保护 } memcpy(g_json_buffer, data, data_len); // 2. 初始化解析器 json_init(&g_json_parser, g_json_buffer, data_len); // 3. 执行解析 JsonResult res = json_parse(&g_json_parser); if (res != JSON_OK) { // 记录错误：res 与 g_json_parser.pos log_error("JSON parse failed at %u: %d", g_json_parser.pos, res); return; } // 4. 后续调用 json_get_* 系列函数提取数据 extract_payload(&g_json_parser); }

3.2 键值提取 API 族

所有json_get_*函数均采用路径式查找，支持点号分隔的嵌套路径（如"sensor.temp.value"），但不支持数组索引（如"list[0].name"）。这是为保持解析器极简性与确定性而做的主动取舍——若需数组访问，用户需先获取整个数组 token，再手动遍历。

嵌套对象提取示例（工业配置场景）：

typedef struct { uint16_t period_ms; uint8_t retry_count; bool enable_crc; } CommConfig; void extract_comm_config(const JsonParser *p, CommConfig *cfg) { // 提取顶层字段 json_get_uint32(p, "period_ms", &cfg->period_ms); json_get_uint32(p, "retry_count", &cfg->retry_count); // 提取嵌套字段（自动处理 {"comm": {"enable_crc": true}}） json_get_bool(p, "comm.enable_crc", &cfg->enable_crc); // 安全默认值设定（未提供时保持原值） if (cfg->period_ms == 0) cfg->period_ms = 1000; // 默认 1s if (cfg->retry_count == 0) cfg->retry_count = 3; }

3.3 高级 API：令牌遍历与类型查询

当需要动态处理未知结构（如通用配置下发）时，可绕过路径查找，直接遍历解析器生成的令牌列表：

// 获取令牌总数（即解析出的键值对与结构体元素总数） uint8_t json_token_count(const JsonParser *p); // 获取第 i 个令牌的详细信息 JsonTokenType json_token_type(const JsonParser *p, uint8_t index); const char* json_token_key(const JsonParser *p, uint8_t index, size_t *key_len); const char* json_token_value(const JsonParser *p, uint8_t index, size_t *val_len);

JsonTokenType枚举定义了所有可能的令牌类型：

typedef enum { JSON_TOKEN_OBJECT_START, // { 开始 JSON_TOKEN_OBJECT_END, // } 结束 JSON_TOKEN_ARRAY_START, // [ 开始 JSON_TOKEN_ARRAY_END, // ] 结束 JSON_TOKEN_KEY, // 字符串键（如 "name"） JSON_TOKEN_STRING, // 字符串值（如 "John"） JSON_TOKEN_NUMBER, // 数字值（如 42） JSON_TOKEN_TRUE, // true 字面量 JSON_TOKEN_FALSE, // false 字面量 JSON_TOKEN_NULL // null 字面量 } JsonTokenType;

动态配置处理示例（FreeRTOS 任务中）：

void dynamic_config_task(void *pvParameters) { for(;;) { // 从队列接收 JSON 配置数据 JsonConfigMsg_t msg; if (xQueueReceive(config_queue, &msg, portMAX_DELAY) == pdTRUE) { json_init(&g_parser, msg.payload, msg.len); if (json_parse(&g_parser) == JSON_OK) { uint8_t count = json_token_count(&g_parser); for (uint8_t i = 0; i < count; i++) { JsonTokenType type = json_token_type(&g_parser, i); const char *key; size_t key_len; const char *val; size_t val_len; if (type == JSON_TOKEN_KEY) { key = json_token_key(&g_parser, i, &key_len); // 下一个令牌必为值，获取其类型与内容 if (i+1 < count) { JsonTokenType next_type = json_token_type(&g_parser, i+1); switch(next_type) { case JSON_TOKEN_STRING: val = json_token_value(&g_parser, i+1, &val_len); handle_string_config(key, key_len, val, val_len); break; case JSON_TOKEN_NUMBER: int32_t num; if (json_token_to_int32(&g_parser, i+1, &num) == JSON_OK) { handle_int_config(key, key_len, num); } break; // ... 其他类型处理 } } } } } } } }

4. 配置选项与编译期裁剪

Json库通过一组预处理器宏提供精细的编译期配置，所有宏均在json_config.h中定义，用户可通过修改该头文件或在编译器命令行中定义来调整行为。

RAM 占用计算示例：

// 假设 JSON_MAX_TOKENS = 32, sizeof(JsonToken) = 12 bytes // 则 tokens[] 数组占用：32 * 12 = 384 bytes // 加上 JsonParser 结构体其他成员（约 20 bytes） // 总 RAM 占用 ≈ 404 bytes // 若将 JSON_MAX_TOKENS 降至 16，则 tokens[] 占用 192 bytes，总 RAM ≈ 212 bytes

编译裁剪实践（STM32CubeIDE）：在Project Properties → C/C++ Build → Settings → Tool Settings → ARM GCC C Compiler → Symbols中添加：

JSON_MAX_TOKENS=16 JSON_MAX_DEPTH=4 JSON_ENABLE_COMMENTS=0 JSON_STRICT_MODE=1

此配置可将 Flash 占用进一步压缩至1.4 KB，RAM 占用压至224 字节，完美适配超低资源 MCU。

5. 与主流嵌入式生态的集成实践

5.1 与 STM32 HAL 库协同工作

在基于 STM32 的项目中，Json常与 HAL UART/USB CDC 配合接收 JSON 数据。关键在于数据接收完整性判断与零拷贝解析：

// HAL_UART_RxCpltCallback 中处理接收到的 JSON 片段 uint8_t rx_buffer[128]; size_t rx_len = 0; void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart == &huart1) { // 假设使用 \n 作为 JSON 结束符（常见于调试终端） if (rx_buffer[rx_len-1] == '\n') { // 移除换行符，获取真实 JSON 长度 size_t json_len = rx_len - 1; // 确保不越界 if (json_len > 0 && json_len < sizeof(rx_buffer)) { json_init(&g_parser, (const char*)rx_buffer, json_len); if (json_parse(&g_parser) == JSON_OK) { process_command(&g_parser); } } } // 重新启动接收 HAL_UART_Receive_IT(&huart1, rx_buffer, sizeof(rx_buffer)); } }

5.2 与 FreeRTOS 的安全集成

在多任务环境中，需确保JsonParser实例的独占访问。推荐两种模式：

1. 任务局部实例（推荐）：每个需要解析 JSON 的任务拥有自己的JsonParser实例，避免共享与同步开销。
2. 临界区保护的全局实例：若 RAM 极其紧张，可使用全局实例，但所有json_*调用必须包裹在taskENTER_CRITICAL()/taskEXIT_CRITICAL()中。

// 全局实例 + 临界区（仅当 RAM < 2KB 时考虑） static JsonParser g_shared_parser; static StaticSemaphore_t xJsonMutexBuffer; static SemaphoreHandle_t xJsonMutex; void json_mutex_init(void) { xJsonMutex = xSemaphoreCreateMutexStatic(&xJsonMutexBuffer); } JsonResult safe_json_parse(const char *json, size_t len) { JsonResult res; xSemaphoreTake(xJsonMutex, portMAX_DELAY); json_init(&g_shared_parser, json, len); res = json_parse(&g_shared_parser); xSemaphoreGive(xJsonMutex); return res; }

5.3 与传感器驱动的数据桥接

以 BME280 环境传感器为例，将读取的温湿度数据封装为 JSON 并通过 MQTT 发送（虽本库不支持生成，但可与轻量级生成器组合）：

// 读取传感器数据 float temp, humi, press; bme280_read_data(&temp, &humi, &press); // 使用 sprintf 构建最小 JSON（因本库只解析，生成由用户负责） char json_out[128]; int len = snprintf(json_out, sizeof(json_out), "{\"t\":%d,\"h\":%d,\"p\":%d}", (int)(temp * 100), // 温度放大100倍存整数 (int)(humi * 100), (int)(press * 100) ); // 确保不溢出 if (len > 0 && len < sizeof(json_out)) { mqtt_publish("sensor/bme280", json_out, len); }

6. 错误处理与调试技巧

Json库定义了 11 个精确的错误码，覆盖从内存不足到语法错误的全场景：

生产环境错误日志增强：

const char* json_strerror(JsonResult res) { switch(res) { case JSON_OK: return "OK"; case JSON_ERR_INVALID_CHAR: return "Invalid character"; case JSON_ERR_UNEXPECTED_EOF: return "Unexpected end of input"; case JSON_ERR_DEPTH_EXCEEDED: return "Max depth exceeded"; case JSON_ERR_NUMBER_FORMAT: return "Invalid number format"; case JSON_ERR_STRING_UNTERMINATED: return "Unterminated string"; default: return "Unknown error"; } } // 日志输出包含关键上下文 log_error("JSON fail [%s] at pos %u in %.*s", json_strerror(res), parser.pos, (int)MIN(parser.len, 32U), parser.json);

7. 性能实测与选型建议

在 STM32F407VG（168MHz）平台上，使用不同复杂度 JSON 进行基准测试（GCC 10.3 -Os）：

选型决策树：

• ✅首选Json：资源紧张（RAM < 4KB）、安全性要求高（汽车/工业）、JSON 结构相对固定、无需浮点、无需生成。
• ⚠️谨慎评估：需解析超 32 个字段、需处理浮点传感器数据、需生成 JSON、需 XPath 查询。
• ❌不适用：Web 前端、PC 应用、需处理 GB 级 JSON、需严格 RFC 7159 兼容性。

对于Json的局限性，工程实践中常采用组合策略：

• 浮点数据 → 使用定点数缩放（temp_cx100）；
• 大型配置 → 分片传输，每片独立 JSON；
• 生成需求 → 集成jsmn的轻量生成分支或手写sprintf模板。

该库的价值不在于功能完备，而在于其在确定性、安全性、资源效率三角关系中做出的清醒取舍——这正是嵌入式底层工程师每日直面的核心命题。