4. 特征读写封装设计原则：同步与异步、阻塞与非阻塞、线程安全

GATT 特征读写封装是蓝牙协议栈应用层与硬件交互的核心接口。设计不当会导致数据竞争、主线程卡顿、响应超时等问题。本章从同步/异步、阻塞/非阻塞、线程安全三个维度剖析封装原则，并给出可移植的实现模板。

4.1 核心概念对比

4.2 线程安全设计原则

蓝牙协议栈（如 BlueZ、Zephyr、ESP‑IDF）底层回调可能在 ISR 或专有任务上下文中执行，用户封装层必须保证：

• 共享数据保护：写缓冲区、特征句柄表、挂起请求队列必须加锁（互斥锁或读写锁）。
• 回调上下文迁移：将底层回调转换为应用层安全上下文，避免在 ISR 中直接调用用户函数。
• 重入防护：同一特征在读/写/通知使能并发调用时，使用原子操作或状态机防止序列错乱。
• 资源生命周期管理：确保特征句柄有效期间对应的回调指针不被释放。

4.3 设计决策树与封装策略

下图描述了在封装特征读写 API 时，根据场景选择同步/异步、阻塞/非阻塞的决策路径：

4.4 实现流程：线程安全的异步读写封装

1. 初始化特征句柄表：为每个服务下的特征分配槽位，存储句柄、读写锁、回调函数指针及用户数据。
2. 消息队列投递：应用程序调用 gatt_write_char(handle, data, len, cb) 时，构造写请求消息并放入协议栈工作队列。
3. 底层调度：工作队列线程取出消息，调用 bt_gatt_write()（以 Zephyr 为例）并记录当前请求 ID。
4. 回调着陆：协议栈底层触发 write_cb，在工作队列上下文中调用用户注册的回调。
5. 超时保护：启动定时器，若超过指定时间未收到回调，则自动取消请求并通知错误。

4.5 参考代码片段（Zephyr RTOS 示例）

/* gatt_char_client.h */
struct gatt_write_req {
    uint16_t            handle;
    struct bt_gatt_write_params params;
    void                *user_data;
    gatt_write_cb_t     cb;
    sys_snode_t         node;   /* 链表节点 */
};

/* 工作队列线程 */
void gatt_char_work_handler(struct k_work *work) {
    struct gatt_write_req *req = CONTAINER_OF(work, struct gatt_write_req, params);
    k_mutex_lock(&gatt_lock, K_FOREVER);
    __sync_synchronize();
    int err = bt_gatt_write(&conn, req->handle,
                            req->params.data, req->params.length,
                            req->params.offset,
                            on_write_complete);
    if (err) {
        req->cb(err, req->user_data);
        k_free(req);
    }
    k_mutex_unlock(&gatt_lock);
}

/* 应用层线程安全写入 API */
int gatt_char_write(uint16_t handle,
                    const uint8_t *data, uint16_t len,
                    gatt_write_cb_t cb, void *user_data) {
    struct gatt_write_req *req = k_malloc(sizeof(*req));
    if (!req) return -ENOMEM;
    req->handle = handle;
    req->params.data = data;
    req->params.length = len;
    req->params.offset = 0;
    req->cb = cb;
    req->user_data = user_data;
    // 投递到协议栈工作队列
    return k_work_submit_to_queue(&gatt_work_q, &req->params.work);
}

4.6 调试与常见错误

4.7 性能与稳定性优化

• 内存池代替 k_malloc：预分配固定数量的请求结构体，避免动态分配碎片和延时。
• 批量写合并：对连续小数据写，采用 MTU 协商后合并为一次 bt_gatt_write_without_response。
• 无锁环形队列：在 ISR 到工作队列的投递路径上使用 DWC (Double‑Word Compare) 原子队列，减少上下文切换。
• 优先级分离：特征读写与通知/指示使用不同队列，保证高优实时通知不被阻塞。