📚 课程目录第3章设备影子生命周期管理

3. 设备影子生命周期管理

设备影子（Device Shadow）是云端为每台设备维护的一份 JSON 文档，用来保存设备的“期望状态（desired）”和“上报状态（reported）”。设备离线时，应用仍可写入 desired；设备上线后拉取影子、执行并回报 reported，云端据此判断二者是否一致。理解影子的生命周期，本质上就是理解这份文档从创建到销毁、从期望到一致的完整流转过程。

一、影子的创建：首次交互即隐式生成

在主流物联网平台（如 AWS IoT、阿里云 IoT、华为云 IoTDA）中，影子通常不需要显式“新建”命令。当设备首次连接并发布状态，或应用首次对该设备名调用更新接口时，平台会以设备唯一标识（如 productKey/deviceName 或 Thing Name）为键，自动创建一份初始影子文档。初始结构一般如下：

{
  "state": {
    "desired": {},
    "reported": {}
  },
  "metadata": {},
  "version": 1,
  "timestamp": 1735689600
}

其中 version 是乐观锁版本号，每次成功更新自增；timestamp 为服务端接收时间（Unix 秒）。创建阶段要确认三件事：设备标识是否全局唯一、影子是否随设备注册自动生成、以及该设备是否被策略（Policy）授权访问 shadow 主题。若策略未放行，后续所有更新都会以 Not authorized 失败，而不是“影子不存在”。

二、更新：desired 与 reported 的双向写入

更新是生命周期中使用最频繁的操作，分为应用侧写 desired、设备侧写 reported 两条路径。以 MQTT 为例，主题约定为：

应用下发期望：$shadow/update/accepted  ← 发布到 $shadow/update
设备上报状态：$shadow/update/accepted  ← 发布到 $shadow/update
订阅结果：    $shadow/update/accepted / $shadow/update/rejected / $shadow/update/documents

应用把目标温度写入 desired：

{
  "state": {
    "desired": { "targetTemp": 26 }
  },
  "version": 3
}

设备收到 delta 通知后执行动作，再回报：

{
  "state": {
    "reported": { "targetTemp": 26, "currentTemp": 25.8 }
  },
  "version": 4
}

更新时若携带 version，平台会做乐观锁校验：版本不匹配则返回 409 Conflict 并进入 rejected，避免并发覆盖。若不带 version，则强制覆盖。工程上建议对关键控制指令携带 version，对周期性遥测可不带。

三、查询：GET 拉取与 delta 计算

查询通过 $shadow/get 发布空消息，平台在 $shadow/get/accepted 返回完整文档。查询的价值不只是“看当前值”，更在于平台会自动计算 delta——即 desired 中存在而 reported 中缺失或不一致的部分。例如 desired 为 {"targetTemp":26,"mode":"cool"}，reported 为 {"targetTemp":25.8}，则 delta 为：

{
  "state": {
    "targetTemp": 26,
    "mode": "cool"
  }
}

设备只需订阅 $shadow/update/delta，即可在 desired 变化时被动收到差异，无需轮询。这是影子同步机制的核心：应用写期望，平台算差异，设备收 delta，回报 reported，差异归零。

四、订阅与状态同步机制

同步依赖三个主题的配合：update/delta 推送差异、update/documents 推送每次更新后的完整文档、update/accepted|rejected 反馈结果。设备端典型订阅集合为：

$shadow/update/delta：接收期望与上报的差异，触发本地执行；
$shadow/update/accepted：确认自己的 reported 已被接受；
$shadow/update/rejected：处理版本冲突或格式错误；
$shadow/get/accepted：上线首次拉取全量影子。

同步的收敛条件是 desired == reported。若设备执行失败，应回报实际值而非期望值，让 delta 持续存在，应用即可据此判断“指令未生效”。下面这张图展示了影子从创建、更新、查询到同步收敛的完整状态流转与主题关系。

五、删除：显式清理与自动过期

删除影子有两种方式。其一是显式删除：向 $shadow/delete 发布消息，平台移除整份文档，之后 get 会返回 ResourceNotFoundException。其二是随设备注销自动清理，多数平台在删除设备时级联删除影子。删除前应确认没有应用仍在依赖该影子做状态判断，否则会出现“查询报错”而非“返回空状态”。若只想清空某个字段，应更新为 null 而非删除整份文档：

{
  "state": {
    "desired": { "targetTemp": null }
  }
}

平台会把该字段从 desired 中移除，并重新计算 delta。注意：null 是“删除字段”，不是“把值设为空”，二者语义不同。

六、工程实践中的关键参数与判断依据

下面给出一份可直接参考的影子同步检查表，字段均来自本节实际语境：

检查项	典型值 / 判断	异常表现
影子是否已创建	get 返回 version ≥ 1	ResourceNotFoundException
desired 与 reported 是否一致	delta 为空对象 {}	delta 长期非空，指令未生效
version 是否冲突	更新携带 version 且匹配	409 Conflict → rejected
订阅是否完整	delta / accepted / rejected / documents	只订阅 accepted，漏收 delta
删除是否安全	无应用依赖后再 delete	查询报错而非返回空

建议设备上线流程固定为：连接 → 订阅 delta 与 accepted → get 拉取全量影子 → 对比本地状态 → 执行差异 → 回报 reported。这样即使设备离线期间 desired 多次变化，上线后也能一次性收敛到最新期望值。

不要把 reported 写成“期望值”。若设备执行失败却回报了 desired，delta 会被错误清空，应用将误判指令已生效。正确做法是回报真实测量值，让 delta 保留，暴露问题。

综上，设备影子的生命周期可以概括为：首次交互隐式创建，应用写 desired、设备写 reported 完成更新，get 与 delta 支撑查询与差异计算，订阅主题驱动实时同步，delete 或字段置 null 完成清理。判断同步是否成功的唯一依据是 delta 是否为空，而 version 则是并发安全的关键护栏。