首页 / knowledge/代码解析/common
json.h
源文件路径：
common/json.h所属模块：common（通用工具库） 代码行数：23
1. 文件职责
本文件是 common/json.c 的对外头文件，只做两件事：一是用两个宏定义 JSON 报文的长度基准，二是声明 5 个 JSON 取值函数供全工程使用。它处在 EMS 数据流的最外圈——任何需要从云端/上位机下发 JSON 里抠字段的模块（net/server.c、midware/interface/modbus/modbus.c、midware/ethernt/wireless/wireless_driver.c）都要先 #include "json.h"。文件本身没有可执行代码、没有全局变量，不参与任何任务调度。注意它与 json.c 之间存在一处不一致：json.c:99 定义的 json_check_value() 并没有在这里声明。
2. 关键数据结构与宏
| 名称 | 类型(结构体/枚举/宏/联合体) | 说明 |
|---|---|---|
__JSON_H__ | 宏（include guard） | 头文件防重包含开关，json.h:9-10 |
LEN_REQ_FILE | 宏 | json.h:13，值 1024。注释与命名暗示它是「单次请求文件长度」，在 net/server.c 的固件升级流程中被复用为报文长度基准 |
MAX_LEN_JSON_CONNENT | 宏 | json.h:14，值 LEN_REQ_FILE * 2 = 2048。json.c 中三个取值函数把键值长度的第一道上限卡在这个值上（json.c:74、json.c:142、json.c:209） |
本文件不定义结构体、枚举或联合体。
3. 函数清单
本文件是头文件，不含函数定义，仅含 5 个函数原型声明：
| 函数名 | 作用域(static/全局) | 说明(一句话) |
|---|---|---|
json_check | 全局（声明，json.h:17） | 以首尾大括号判断字符串是否为一个 JSON 对象 |
json_get_value | 全局（声明，json.h:18） | 提取 "key":"value" 形式（值带双引号）的字符串字段 |
json_get_value_check_len_input | 全局（声明，json.h:19） | 同上，但多带一个 len_in_MAX 做目的缓冲长度保护 |
json_get_int_len_input | 全局（声明，json.h:20） | 提取 "key":value 形式（值无引号）的数值字段，带 len_in_MAX 保护 |
json_get_time_value_from_fw_temp | 全局（声明，json.h:21） | 按 'Y'/'M'/'D'/'H'/'F'/'S' 从时间字符串中拆出对应分量，返回 s8 |
未在头文件声明的实现：json_check_value（实现见 common/json.c:99）。这是一处头文件与实现不同步的遗留。
4. 核心逻辑解析
本文件无逻辑代码，此处说明两个宏在调用链上的实际作用：
MAX_LEN_JSON_CONNENT（2048）在json.c里被用作键值长度的「第一道上限」，只有长度不超过它，才继续判断调用方传入的len_in_MAX（json.c:144、json.c:211）。也就是说它实际是防御云端下发超长字段的兜底值，而不是目的缓冲区的真实大小。若某个调用方传入的json_value缓冲小于 2048 且使用的是不带len_in_MAX的json_get_value()，就没有任何保护。LEN_REQ_FILE（1024）在json.h里没有被json.c直接引用，只是MAX_LEN_JSON_CONNENT的组成因子；其真正的语义载体是网络层收发缓冲区尺寸，属于跨模块的隐式耦合。
与任务/调度的配合
无。头文件不参与 uCOS-II 任务、信号量、消息邮箱的定义或使用。
5. 对外接口
导出（供外部调用）
| 符号 | 类型 | 使用者 |
|---|---|---|
LEN_REQ_FILE | 宏 | 间接通过 MAX_LEN_JSON_CONNENT 使用；工程内无直接引用 |
MAX_LEN_JSON_CONNENT | 宏 | common/json.c（json.c:74、json.c:142、json.c:209） |
json_check | 函数原型 | net/server.c:2615, 3442, 3684 |
json_get_value | 函数原型 | net/server.c（约 250 处）、midware/interface/modbus/modbus.c:8632, 8645, 8658、midware/ethernt/wireless/wireless_driver.c:99 |
json_get_value_check_len_input | 函数原型 | 无调用点 |
json_get_int_len_input | 函数原型 | 无调用点 |
json_get_time_value_from_fw_temp | 函数原型 | net/server.c:2715-2720 |
本文件不导出任何全局变量。
被本文件调用（外部依赖）
本文件只引用类型别名 s8（json.h:21 原型返回类型），该类型由包含链上游的 includes.h / chip.h 提供。因此 json.h 必须在使用方已经包含平台类型头之后才能编译通过，它自身没有 #include。
6. 依赖关系
- 依赖：无
#include；隐式依赖调用方先提供u8/s8类型定义（实际来自includes.h→chip.h）。 - 被依赖：
common/json.c（唯一实现者）；net/server.c、midware/interface/modbus/modbus.c、midware/ethernt/wireless/wireless_driver.c等通过#include "json.h"使用其宏与原型。
7. 备注与风险点
- 头文件缺少
#include：json.h:21的原型用了s8，但文件里没有任何#include。这迫使每个使用方必须先包含includes.h（或chip.h），包含顺序稍有变化即编译报错，属脆弱设计。 - 实现与声明不同步：
json_check_value（common/json.c:99）未在本文件声明，其他模块无法通过正规途径调用它；若将来有人手工写extern声明使用，会出现「有实现无契约」的隐患。 LEN_REQ_FILE命名与用途不符：宏名描述的是「请求文件长度」，但json.h里实际只用它推导 JSON 内容长度上限。若日后固件升级报文长度基准调整，会连带改变本轮 JSON 取值的长度上限，属隐式耦合。json_get_value缺少长度参数：本文件提供的两个带保护变体（json_get_value_check_len_input/json_get_int_len_input）在工程内零调用，而唯一被大量使用的json_get_value没有任何目的缓冲长度参数。这表明「加长度保护」的重构做了一半就停下来了，历史遗留代码仍走不安全路径。MAX_LEN_JSON_CONNENT拼写：CONNENT应为CONTENT，属长期未修正的拼写错误，改名会牵动json.c三处引用。- 其余：暂无。