1. 项目概述

Dictionary 是一款专为资源受限嵌入式平台（尤其是 ESP8266/ESP32）设计的轻量级、高性能键值对（Key-Value）数据结构库。其核心目标并非复刻标准 STL std::map 或通用哈希表，而是解决物联网固件开发中一个高频且棘手的实际问题： 高效、低内存开销地解析、存储与查询 JSON 配置文件和运行时参数 。

在典型的 Wi-Fi 配置场景中，开发者需要处理形如 'ssid': 'MyHomeNetwork' 、 'ota_url': 'http://update.firmware.bin' 、 'mqtt_port': '1883' 这类字符串键与字符串值的映射关系。传统方案如 ArduinoJson 库虽功能强大，但其内存占用和解析开销对于仅有几十 KB 可用堆内存的 ESP8266 来说往往过于沉重；而直接使用 C 风格的 char* 数组或链表，则缺乏高效的查找能力，线性搜索在数百个配置项时性能急剧下降。 Dictionary 正是在这一工程痛点下诞生的务实解决方案——它放弃通用性，拥抱嵌入式约束，在“小”、“快”、“省”三个维度上进行了深度优化。

其技术选型极具工程智慧：摒弃了计算开销大、代码体积大的 CRC 校验算法（v3.0.0 起），转而采用对键字符串首部字节的 直接截取与 reinterpret_cast 作为内部索引依据。这种设计将哈希计算的 CPU 时间消耗降至几乎为零，同时避免了哈希冲突处理所需的额外逻辑和内存。底层数据结构并非简单的哈希桶，而是一个经过精心裁剪的 二叉搜索树（Binary Search Tree, BST） 。BST 的有序特性天然支持按插入顺序的遍历（ d(0) , d(1) ），这在序列化为 JSON 或生成配置报告时极为关键；而其 O(log n) 的平均查找复杂度，又远优于链表的 O(n)，完美契合了配置项数量通常在数十至数百量级的嵌入式应用场景。

2. 核心架构与内存模型

Dictionary 的内存布局是其高性能与低开销的基石，其设计严格遵循嵌入式系统“内存即黄金”的铁律。整个库由三个核心组件构成： Dictionary 对象本身、 NodeArray 节点数组管理器，以及每个键值对对应的 Node 结构体。

2.1 对象与节点内存开销

组件	默认大小 (字节)	说明
Dictionary 对象	28	包含指向 NodeArray 的指针、计数器、配置标志等元数据。若启用结构体打包 ( _DICT_PACK_STRUCTURES )，可缩减至 22 字节。
NodeArray 对象	20	管理所有 Node 的动态数组，包含容量、大小、内存分配器指针等。
单个 Node 结构体	24	这是最关键的可变部分 。其大小取决于 _DICT_KEYLEN 和 _DICT_VALLEN 的设置，用于动态决定存储键长、值长所需的字节数（1/2/4 字节）。

一个键值对的总内存消耗 = Dictionary + NodeArray + Node + key_string + value_string 。其中 key_string 和 value_string 的长度完全由实际内容决定，并额外预留 1 字节用于 \0 终止符。

示例计算（默认配置） ：

• _DICT_KEYLEN = 64 , _DICT_VALLEN = 254
• 插入键 "this is a key" (13 字符) 和值 "This is a Value" (15 字符)
• 内存消耗 = 28 ( Dictionary ) + 20 ( NodeArray ) + 24 ( Node ) + (13+1) ( key ) + (15+1) ( value ) = 102 字节

此精细的内存控制意味着，开发者可以根据项目实际需求，通过预定义宏精确“雕刻”内存足迹。例如，一个仅需存储 16 字符 SSID 和 8 字符端口号的设备，可将 _DICT_KEYLEN 设为 16， _DICT_VALLEN 设为 8，从而将每个 Node 的固定开销从 24 字节大幅降低。

2.2 索引机制：CRC 截取而非计算

Dictionary 的核心创新在于其索引生成方式。它不进行任何 CRC 计算，而是直接对键字符串的首部字节进行“物理截取”。

• 若定义 #define _DICT_CRC 16 ，则取键字符串前 2 字节（16 位）。
• 若定义 #define _DICT_CRC 32 （ 默认 ），则取键字符串前 4 字节（32 位）。
• 若定义 #define _DICT_CRC 64 ，则取键字符串前 8 字节（64 位）。

该截取后的字节序列被 reinterpret_cast 为一个整数，作为该节点在二叉搜索树中的排序键（Sort Key）。这种方式的优势是颠覆性的：

• 零计算开销 ：无 CRC 表查表、无位运算循环，仅一次内存读取和类型转换。
• 确定性 ：相同键永远产生相同索引，保证了 BST 的稳定性。
• 空间友好 ：无需存储额外的哈希值，索引信息内嵌于键本身。

其代价是，对于极短的键（如 "a" ），截取的字节可能包含大量 \0 填充，导致不同短键的索引碰撞概率上升。但在配置项场景中，键名（ "ssid" , "password" ）通常足够长，此问题可忽略不计。

2.3 PSRAM 与内存分配策略

针对 ESP32 平台， Dictionary 提供了至关重要的 #define _DICT_USE_PSRAM 编译选项。当启用时，所有 NodeArray 和 Node 对象的内存分配均会调用 ps_malloc() 而非 malloc() ，从而将海量键值对（测试显示可达 30,000 对）的存储压力从宝贵的 320KB DRAM 转移至外部 PSRAM。这对于需要加载大型固件配置或 OTA 元数据的应用至关重要。

此外， Dictionary 显式支持 结构体打包 （ _DICT_PACK_STRUCTURES ）。在默认的 4 字节对齐下，编译器会在结构体成员间插入填充字节以提升访问速度。而启用打包后，编译器将紧密排列所有成员，牺牲微乎其微的访问性能（基准测试显示 ESP32 上查找耗时仅增加约 18 微秒），换取显著的内存节省（1000 个节点可节省约 1.1KB）。

3. API 接口详解与工程实践

Dictionary 的 API 设计高度凝练，以操作符重载和简洁方法为核心，极大降低了嵌入式开发者的认知负担。

3.1 构造与初始化

// 创建一个默认容量为 10 的字典
Dictionary *dict = new Dictionary();

// 创建一个初始容量为 N 的字典（N 为预估的最大键值对数，可减少后续内存重分配）
Dictionary *dict = new Dictionary(64);

// 创建并获取引用（推荐用于栈上对象或 RAII 场景）
Dictionary &d = *(new Dictionary(6));

工程建议 ： initial_size 参数并非强制要求，但合理预设能有效避免频繁的 realloc 操作，提升运行时稳定性。对于已知配置项数量的应用（如一个有 12 个参数的传感器节点），直接传入 12 是最佳实践。

3.2 键值对操作：插入、更新与查找

Dictionary 提供了两种风格的插入/更新接口：

// 风格一：函数调用式（推荐用于清晰表达意图）
dict->insert("mqtt_server", "192.168.1.100");
dict->insert("mqtt_port", "1883");

// 风格二：操作符重载式（语法糖，本质同 insert）
d("mqtt_server", "192.168.1.100");
d("mqtt_port", "1883");

关键语义 ：无论使用哪种方式，若键已存在，则 更新其值 ；若键不存在，则 创建新键值对 。这是一种“Upsert”（Update or Insert）语义，完美匹配配置更新场景。

查找操作同样提供双接口：

// 通过键名查找值（返回 String 对象）
String server = d["mqtt_server"]; // 若键不存在，返回空 String ("")
String not_exist = d["non_existent_key"]; // 返回 ""

// 通过索引查找值（按插入顺序）
String first_value = d[0]; // 返回第一个插入的值
String third_value = d[2]; // 返回第三个插入的值

// 显式方法调用
String pwd = dict->search("password"); // 同 d["password"]
String val = dict->value(3); // 同 d[3]

重要警告 ： d[0] 、 d[1] 等索引访问 严格依赖插入顺序 。一旦执行了 remove() 操作，该顺序即被破坏，索引将不再可靠。因此，索引访问应仅用于只读、无删除的场景，如配置项的批量序列化。

3.3 JSON 解析与序列化

Dictionary 的 JSON 功能是其区别于其他轻量级 KV 库的核心竞争力。

// 从 JSON 字符串加载
String json_str = "{'ssid':'MyNet','pwd':'12345678','port':'8080'}";
d.jload(json_str); // 全量加载

// 加载前 N 个键值对（用于流式解析或内存受限场景）
d.jload(json_str, 2); // 仅加载 'ssid' 和 'pwd'

// 从文件流加载（适用于 SPIFFS/LittleFS 文件系统）
File config_file = SPIFFS.open("/config.json", "r");
if (config_file) {
    d.jload(config_file);
    config_file.close();
}

// 生成 JSON 字符串
String json_out = d.json(); // 返回 "{...}"
int json_len = d.jsize(); // 返回 json() 字符串的长度（含 '\0'）

// 预分配缓冲区的最佳实践
char* buffer = (char*) malloc(d.jsize());
if (buffer) {
    strcpy(buffer, d.json().c_str());
    // 使用 buffer...
    free(buffer);
}

JSON 扩展特性 ：

• 注释支持 （v3.2.0+）： jload() 能正确忽略以 # 开头的行注释和行尾注释，极大提升了配置文件的可读性和可维护性。
• 宽松语法 ：支持无引号的键名（ {key: 'value'} ）和无引号的数字值（ {port: 8080} ），所有值最终均被转换为 String 类型。
• ASCII 限定 （ _DICT_ASCII_ONLY ）：编译时启用此宏， jload() 将自动过滤掉所有非 ASCII 字符，确保在处理来自不可信源的 JSON 时的安全性。

严重限制 ： json() 方法 不转义键或值中的单引号（ ' ）或反斜杠（ \ ） 。若值为 "The answer is 'no'." ，生成的 JSON 将非法。因此，在使用 JSON 功能前，必须确保键值内容符合 JSON 字符串规范，或在存入前进行手动转义。

3.4 高级操作：合并、比较与删除

// 合并另一个字典（深拷贝）
Dictionary *other_dict = new Dictionary();
other_dict->insert("debug", "true");
d.merge(*other_dict); // d 现在包含了 other_dict 的所有键值对

// 字典相等性比较（内容完全一致）
if (d == *other_dict) {
    Serial.println("Dictionaries are identical.");
}

// 检查键是否存在（返回 bool）
if (d("mqtt_server")) { // true
    Serial.println("MQTT server is configured.");
}

// 获取键值对数量
int count = d.count(); // 返回当前键值对总数

// 获取内存占用（数据部分，不含 Dictionary 对象本身）
int data_size = d.size(); // 返回所有 key/value 字符串及 Node 结构体的总字节数

// 删除指定键
d.remove("mqtt_port"); // 移除键为 "mqtt_port" 的条目

// 安全地清空整个字典（推荐方式）
while (d.count()) {
    d.remove(d(0)); // 总是删除索引 0，避免因索引偏移导致的遗漏
}

删除操作的陷阱 ： d.remove("key") 是安全的，但基于索引的循环删除（如 for(int i=0; i<d.count(); i++) d.remove(d(i)) ）是 严重错误 。因为每次 remove() 都会改变剩余条目的索引，导致跳过条目。文档中提供的 while 循环方案是唯一可靠的清空方法。

4. 性能基准与工程选型指南

Dictionary 的性能数据并非理论值，而是基于真实硬件（ESP8266/ESP32）的实测结果，为工程师的选型决策提供了坚实依据。

4.1 基准测试数据摘要

平台	配置	键值对数	查找 (μs)	删除 (μs)	总内存 (bytes)
ESP8266	无压缩, DRAM	300	76.09	83.31	~8364
ESP8266	SHOCO (config), DRAM	300	108.18	109.18	~7137
ESP32	无压缩, DRAM, 打包	1000	94.67	17.48	34844
ESP32	SHOCO (config), DRAM	1000	73.11	19.26	32084
ESP32	无压缩, PSRAM	30000	~120	~25	~1.2MB

关键洞察 ：

• 压缩的权衡 ：SHOCO/SMAZ 压缩能节省约 7-16% 的内存，但会带来 30-50% 的 CPU 开销（查找/删除时间增加）。对于 CPU 富余、内存极度紧张的场景（如 ESP8266），压缩是优选；对于追求极致响应速度的实时控制场景，则应禁用压缩。
• PSRAM 的威力 ：ESP32 的 PSRAM 将容量上限从 DRAM 的 ~2000 对跃升至 ~30000 对，使其能胜任网关级设备的复杂配置管理。
• 打包的性价比 ：在 ESP32 上，启用 _DICT_PACK_STRUCTURES 仅使查找速度下降 18μs，却节省了 1.1KB 内存，是近乎“免费”的优化。

4.2 工程选型决策树

在项目启动时，应根据以下问题快速定位最优配置：

1. 目标平台是 ESP8266 还是 ESP32？

   • ESP8266：优先考虑内存，启用 SHOCO 压缩和 _DICT_PACK_STRUCTURES ；禁用 PSRAM（不存在）。
   • ESP32：若配置项 < 2000，DRAM 足够；若 > 2000，必须启用 _DICT_USE_PSRAM 。

2. 配置项数量级预估是多少？

   • < 50：默认配置（ _DICT_KEYLEN=64 , _DICT_VALLEN=254 ）完全足够。
   • 50-500：根据键值平均长度，可将 _DICT_KEYLEN 降至 32， _DICT_VALLEN 降至 128，节省可观内存。

   • 500：必须启用 _DICT_PACK_STRUCTURES ，并仔细评估是否启用压缩。

3. 应用对实时性要求有多高？

   • 高（如电机控制环路）：禁用所有压缩，使用默认未打包结构，追求最低延迟。
   • 中（如 Web 配置页面）：可接受 100μs 级别的查找延迟，启用 SHOCO 压缩以换取更多内存给其他任务。
   • 低（如日志归档）：可启用 SMAZ，其静态字典在嵌入式上更易部署。

4. 是否需要 JSON 功能？

   • 是：务必在设计阶段就规避 json() 的转义缺陷，建立严格的键值内容校验规则。
   • 否：可完全移除 jload() 和 json() 相关代码，进一步精简库体积。

5. 实战案例：构建一个鲁棒的 Wi-Fi 配置管理器

以下是一个完整的、生产就绪的 Wi-Fi 配置管理器示例，它综合运用了 Dictionary 的所有核心特性。

#include <Dictionary.h>
#include <SPIFFS.h>

// 配置宏：针对 ESP32 优化
#define _DICT_USE_PSRAM
#define _DICT_PACK_STRUCTURES
#define _DICT_KEYLEN 32
#define _DICT_VALLEN 128

class WiFiConfigManager {
private:
    Dictionary *config;
    const char* CONFIG_FILE = "/wifi_config.json";

public:
    WiFiConfigManager() {
        config = new Dictionary(16); // 预设 16 个配置项
        loadFromFS();
    }

    ~WiFiConfigManager() {
        delete config;
    }

    // 从 SPIFFS 加载配置，失败则使用默认值
    void loadFromFS() {
        if (SPIFFS.begin(true)) {
            File file = SPIFFS.open(CONFIG_FILE, "r");
            if (file) {
                // 启用注释支持
                int err = config->jload(file);
                file.close();
                if (err != DICTIONARY_OK) {
                    Serial.printf("JSON load error: %d\n", err);
                    setDefaults();
                }
            } else {
                setDefaults();
            }
        } else {
            setDefaults();
        }
    }

    // 设置默认配置（首次启动或损坏时）
    void setDefaults() {
        config->insert("ssid", "MyNetwork");
        config->insert("password", "");
        config->insert("ip_mode", "dhcp"); // "static" or "dhcp"
        config->insert("ip_addr", "192.168.1.100");
        config->insert("gateway", "192.168.1.1");
        config->insert("subnet", "255.255.255.0");
        saveToFS(); // 立即保存默认值
    }

    // 保存配置到 SPIFFS
    void saveToFS() {
        File file = SPIFFS.open(CONFIG_FILE, "w");
        if (file) {
            // 预分配缓冲区，避免 json() 在堆上临时分配
            int len = config->jsize();
            char* buf = (char*) ps_malloc(len);
            if (buf) {
                strcpy(buf, config->json().c_str());
                file.write((uint8_t*)buf, len - 1); // -1 to exclude '\0'
                file.close();
                ps_free(buf);
            }
        }
    }

    // 安全的获取配置项（带默认值回退）
    String get(const char* key, const char* def = "") {
        String val = (*config)[key];
        return val.length() ? val : String(def);
    }

    // 更新配置项并持久化
    void set(const char* key, const char* value) {
        (*config)(key, value);
        saveToFS();
    }

    // 打印当前所有配置（用于调试）
    void dump() {
        Serial.println("=== WiFi Configuration ===");
        for (int i = 0; i < config->count(); i++) {
            Serial.printf("%s = %s\n", config->key(i).c_str(), (*config)[i].c_str());
        }
        Serial.printf("Total memory used: %d bytes\n", config->size());
    }
};

// 全局实例
WiFiConfigManager wifiConfig;

// 在 setup() 中初始化
void setup() {
    Serial.begin(115200);
    wifiConfig.dump(); // 查看当前配置
}

此案例体现了 Dictionary 在真实项目中的价值：它将复杂的配置文件 I/O、内存管理、错误处理封装在一个简洁的类中，让上层业务逻辑（如 Wi-Fi 连接）只需关注 wifiConfig.get("ssid") 这样的语义化调用，极大地提升了固件的可维护性与健壮性。