1726 字

9 分钟

嵌入式 WebSocket 命令处理的扁平化设计：映射表 + 分发表实战

2026-03-26

Lark云雀物联网全栈

esp32

/

c

1. 问题：嵌套地狱#

一个典型的 WebSocket 文本帧协议长这样：

1
{
2
  "code": 0,
3
  "item": "camera",
4
  "key": "frame_size",
5
  "values": "FRAMESIZE_VGA"
6
}

code：0 查询，1 设定
item：模块名（status / camera / device）
key：参数名
values：参数值

最朴素的实现方式是：

1
if (code == 0) {
2
    if (strcmp(item, "status") == 0) {
3
        if (strcmp(key, "status") == 0) { /* ... */ }
4
    } else if (strcmp(item, "camera") == 0) {
5
        if (strcmp(key, "frame_size") == 0) { /* ... */ }
6
        else if (strcmp(key, "jpeg_quality") == 0) { /* ... */ }
7
        // ...
8
    }
9
} else if (code == 1) {
10
    // 再来一遍……
11
}

三层嵌套，每增加一个 item 或 key 就要在两处（查询/设定）各加一段。 模块一多，这个函数轻松突破 300 行，可读性和可维护性直线下降。

2. 解法概览：两级扁平化#

整体思路是将「嵌套分支」拆成两级独立的 表驱动（Table-Driven） 结构：

层级	职责	数据结构
映射表	枚举值 ↔ 字符串的双向转换	`FrameSizeEntry_t[]`
分发表	`item` → 对应的查询/设定处理函数	`ItemDispatch_t[]`

入口函数 ws_text_handler 只做三件事：解析 JSON → 查分发表 → 调用处理函数，不含任何业务逻辑。

1
┌─────────────────────┐
2
│  ws_text_handler()  │  入口：JSON 解析 + 字段校验
3
└────────┬────────────┘
4
         │ 遍历 dispatch_table[]
5
         ▼
6
┌────────────────────────────────────────┐
7
│  dispatch_table[i].query / .set        │  按 code 选择查询或设定
8
│  ┌──────────┬──────────┬────────────┐  │
9
│  │ status   │ camera   │ device     │  │  每个 item 一行
10
│  └──────────┴──────────┴────────────┘  │
11
└────────┬───────────────────────────────┘
12
         │ 在具体 handler 中按 key 处理
13
         ▼
14
   query_camera() / set_camera() / ...

3. 映射表：枚举 ↔ 字符串的零成本转换#

嵌入式开发中经常需要在「人类可读的字符串」和「C 枚举值」之间转换。传统做法是写一大堆 switch-case，每增加一个枚举值就要改两处（to_str 和 from_str）。

定义#

1
typedef struct {
2
    const char    *name;
3
    framesize_t    fs;
4
} FrameSizeEntry_t;
5

6
static const FrameSizeEntry_t fs_table[] = {
7
    { "FRAMESIZE_128X128", FRAMESIZE_128X128 },
8
    { "FRAMESIZE_240X240", FRAMESIZE_240X240 },
9
    { "FRAMESIZE_VGA",     FRAMESIZE_VGA     },
10
    { "FRAMESIZE_SVGA",    FRAMESIZE_SVGA    },
11
    { "FRAMESIZE_HD",      FRAMESIZE_HD      },
12
    { "FRAMESIZE_FHD",     FRAMESIZE_FHD     },
13
};

正反查找#

1
// 枚举 → 字符串
2
static const char *framesize_to_str(framesize_t fs) {
3
    for (size_t i = 0; i < FS_TABLE_SIZE; i++)
4
        if (fs_table[i].fs == fs) return fs_table[i].name;
5
    return "unknown";
6
}
7

8
// 字符串 → 枚举
9
static framesize_t str_to_framesize(const char *str) {
10
    for (size_t i = 0; i < FS_TABLE_SIZE; i++)
11
        if (strcasecmp(str, fs_table[i].name) == 0) return fs_table[i].fs;
12
    return FRAMESIZE_INVALID;
13
}

优势：

单一数据源：新增分辨率只需在 fs_table[] 加一行，正反查找自动生效。
编译期可见：表是 const 数组，存储在 .rodata，不占 RAM。
大小写容错：查找使用 strcasecmp，协议鲁棒性更好。

4. 分发表：item × code 的扁平路由#

这是整个设计的核心。我们定义一个统一的处理函数签名，然后用结构体数组把 item 名称和对应的查询、设定函数关联起来。

处理函数签名#

1
typedef void (*query_handler_t)(const char *key, cJSON *values_item);

所有查询和设定 handler 都遵守同一签名（入参为 key 和 values），确保可以用函数指针统一调用。

分发表定义#

1
typedef struct {
2
    const char      *item;     // 模块名称
3
    query_handler_t  query;    // code == 0 时调用
4
    query_handler_t  set;      // code == 1 时调用
5
} ItemDispatch_t;
6

7
static const ItemDispatch_t dispatch_table[] = {
8
    { "status", query_status, (query_handler_t)set_status },
9
    { "camera", query_camera, (query_handler_t)set_camera },
10
    { "device", query_device, NULL },  // device 的 set 需要特殊处理
11
};

入口函数中的调度逻辑#

1
// 1. 遍历分发表，O(n) 查找 item
2
const ItemDispatch_t *entry = NULL;
3
for (size_t i = 0; i < DISPATCH_TABLE_SIZE; i++) {
4
    if (strcasecmp(item, dispatch_table[i].item) == 0) {
5
        entry = &dispatch_table[i];
6
        break;
7
    }
8
}
9

10
// 2. 未找到 → 统一错误响应
11
if (!entry) {
12
    ws_reply(0, "不支持的item", key, "");
13
    cJSON_Delete(json);
14
    return;
15
}
16

17
// 3. 按 code 分发
18
if (code == 0) {
19
    entry->query(key, values_item);
20
} else if (code == 1) {
21
    // device 模块的 set 需要额外传入 json（支持重启前释放资源）
22
    if (strcasecmp(item, "device") == 0) {
23
        if (set_device(key, values_item, json)) return;
24
    } else if (entry->set) {
25
        entry->set(key, values_item);
26
    }
27
}

入口函数体只有约 50 行，且不含任何具体业务分支。 所有业务逻辑都下沉到各个 handler 中。

5. 业务 Handler 内部：key 级别的平铺#

每个 handler 内部再按 key 做一层 if-else，但此时每个函数只关心自己模块的字段，职责单一：

1
static void query_camera(const char *key, cJSON *values_item) {
2
    sensor_t *s = esp_camera_sensor_get();
3
    if (!s) { ws_reply(0, "相机未初始化", key, ""); return; }
4

5
    char vbuf[32];
6
    if (strcasecmp(key, "frame_size") == 0) {
7
        ws_reply(1, "OK.", key, framesize_to_str(s->status.framesize));
8
    } else if (strcasecmp(key, "jpeg_quality") == 0) {
9
        snprintf(vbuf, sizeof(vbuf), "%d", s->status.quality);
10
        ws_reply(1, "OK.", key, vbuf);
11
    } else {
12
        ws_reply(0, "未知的camera键", key, "");
13
    }
14
}

每个 handler 不超过 30 行，context 清晰
错误处理统一走 ws_reply 返回标准格式

6. 统一响应：ws_reply#

所有对外输出都通过一个函数完成，保证协议格式一致：

1
static void ws_reply(int ok, const char *msg, const char *key, const char *values) {
2
    char buf[256];
3
    snprintf(buf, sizeof(buf),
4
             "{\"code\":%d,\"msg\":\"%s\",\"key\":\"%s\",\"values\":\"%s\"}",
5
             ok ? 1 : 0, msg, key ? key : "", values ? values : "");
6
    WebsocketSendText(buf, strlen(buf));
7
}

这带来的好处：

修改响应格式只改一处
不会出现某个分支忘了返回 code 字段的问题
调用处代码极其简洁

7. 特殊分支的优雅处理#

并非所有模块都能完美套入统一签名。device 模块的 restart 指令需要在重启前手动释放 JSON 对象，函数签名多了一个 cJSON *json 参数。

处理方式是在分发表中将 device.set 设为 NULL，在入口函数中做一次显式判断：

1
if (strcasecmp(item, "device") == 0) {
2
    if (set_device(key, values_item, json))
3
        return;  // json 已在 set_device 内部释放（重启场景）
4
}

set_device 返回 bool 来告知调用方是否已接管 json 的生命周期——这是一个最小特例化的策略：不为了追求完美统一而引入复杂的抽象，而是在必要时用最小的代码量处理例外。

8. 扩展性分析#

新增一个 item 模块（如 `sensor`）#

只需 3 步：

编写 query_sensor() 和 set_sensor() 两个函数

在分发表加一行：

1
{ "sensor", query_sensor, (query_handler_t)set_sensor },

完成。入口函数 零改动。

新增一个 key（如给 camera 加 `brightness`）#

只需在 query_camera / set_camera 中各加一个 else if 分支。其他模块和入口函数完全不受影响。

新增一个枚举映射（如 `FRAMESIZE_QVGA`）#

在 fs_table[] 加一行即可，to_str 和 from_str 自动适配。

9. 设计要点总结#

设计原则	具体体现
表驱动替代分支	映射表消除 switch-case，分发表消除 if-else 嵌套
单一职责	入口函数只做路由，业务逻辑下沉到各 handler
统一接口	所有 handler 遵循 `(key, values_item)` 签名
统一出口	`ws_reply()` 保证响应格式一致
最小特例化	仅 `device.set` 做特殊处理，不过度抽象
编译期安全	映射表和分发表均为 `const`，存 `.rodata` 段
零外部依赖	仅依赖 cJSON + ESP-IDF 标准 API