📚 课程目录第2章设备影子数据模型设计

2. 设备影子数据模型设计

设备影子（Device Shadow）本质上是一份保存在云端的 JSON 文档，用来描述某个设备“当前被认为处于什么状态”以及“期望它变成什么状态”。它解决的核心问题是：设备可能离线、网络不稳定、上报频率低，而应用侧又需要随时读写设备状态。影子把设备状态从“必须实时连着的设备”中解耦出来，让云端先保存一份可读写的状态副本，等设备上线后再同步。

理解影子，关键是理解它不是一份普通的状态缓存，而是一份带有方向语义和版本控制的状态文档。同一份文档里，reported 表示设备“已经报告的事实”，desired 表示应用“希望设备达到的目标”，delta 则是两者之间尚未收敛的差异。版本号、时间戳和元数据则负责回答“这份状态是什么时候的、谁改的、是否过期、能否安全覆盖”等问题。

一、JSON 文档的整体结构

以 AWS IoT 设备影子为参照（其他平台如阿里云、Azure IoT Hub 的孪生/影子模型思路相近，字段命名略有差异），一份典型的影子文档由三大部分组成：state、metadata、version。其中 state 内部再分为 reported 与 desired，delta 通常由云端根据两者差异自动计算，不需要设备或应用手动写入。

{
  "state": {
    "reported": {
      "power": "on",
      "brightness": 60,
      "color": { "r": 255, "g": 180, "b": 0 }
    },
    "desired": {
      "brightness": 80,
      "color": { "r": 0, "g": 160, "b": 255 }
    }
  },
  "metadata": {
    "reported": {
      "power":      { "timestamp": 1735689600 },
      "brightness": { "timestamp": 1735689600 },
      "color":      { "timestamp": 1735689600 }
    },
    "desired": {
      "brightness": { "timestamp": 1735693200 },
      "color":      { "timestamp": 1735693200 }
    }
  },
  "version": 27,
  "timestamp": 1735693200
}

这份文档表达的含义是：设备上次报告亮度为 60、颜色为暖橙；应用希望亮度变为 80、颜色变为冷蓝。由于 desired 与 reported 在 brightness 和 color 上不一致，云端会生成 delta，设备订阅 delta 主题后即可获知“需要把亮度调到 80、颜色改成冷蓝”。

二、reported、desired 与 delta 的语义边界

三者不是三个并列的存储区，而是围绕“事实—目标—差异”构成的一组状态关系。reported 只能由设备写入，代表设备对自身状态的权威声明；desired 只能由应用/规则/运维写入，代表外部对设备的期望；delta 由云端计算，是 desired 中那些“reported 尚未满足”的字段集合。设备执行完成后，应把新状态写回 reported，delta 随之缩小甚至清空。

需要特别注意的是字段级合并语义。影子更新通常是部分更新而非整体替换：如果应用只写 desired.brightness = 80，那么 desired 中已有的 color 不会被删除。若确实要删除某个 desired 字段，需要显式写入 null。这一规则直接影响 delta 的计算结果，也是实际开发中最容易出错的地方。

三、版本号：并发控制的锚点

影子文档中的 version 是一个单调递增的整数，每次影子被成功更新都会加一。它的作用不是给用户看的，而是给并发写入做“乐观锁”。当设备或应用提交更新时，可以带上 version 作为前置条件：只有当前影子版本等于该值时，更新才被接受；否则返回冲突错误，调用方需要重新读取最新影子再决定是否重试。

例如设备在 version=27 时读取了影子，准备回写 reported。若此时应用已经把 desired 改成了新值，影子版本变成 28，那么设备基于 27 的写入就会被拒绝。这避免了“设备用旧认知覆盖新目标”的经典问题。实际工程中，设备回写 reported 通常不需要带版本条件，因为 reported 是设备自身事实；而应用修改 desired 时更建议带版本条件，防止多个控制端互相覆盖。

四、时间戳与元数据：判断新鲜度与来源

影子文档顶层的 timestamp 表示整份文档最后一次更新的时间（Unix 秒）。而 metadata 则按 reported/desired 分别记录每个字段最后一次被写入的时间戳。字段级时间戳非常关键：当设备离线很久后重新上线，它可以通过比较 reported 与 desired 的时间戳判断“这个目标是不是已经过期了”，从而决定是否执行。

在更完整的工程实现中，元数据还可以扩展记录写入来源、客户端 ID、QoS 等。例如在自定义影子服务里，可以设计成：

"metadata": {
  "desired": {
    "brightness": {
      "timestamp": 1735693200,
      "source": "app-web-01",
      "qos": 1
    }
  }
}

这样在排障时就能回答“是谁在什么时候把亮度改成了 80”。需要强调的是，标准 AWS IoT 影子的 metadata 默认只保证 timestamp，额外字段属于平台扩展或自建影子服务的自由度，设计时要与设备端解析逻辑保持一致，避免设备因未知字段解析失败。

五、设计要点与常见陷阱

字段粒度要稳定：reported 与 desired 的字段路径必须一致，否则 delta 无法正确比对。例如 reported 用 color.r，desired 就不能写成 color_r。
避免大对象整体上报：如果设备每次把整个配置树都写进 reported，delta 计算和存储成本都会上升。应按变更字段做部分更新。
null 的语义要明确：写入 null 表示删除该字段，而不是把值设为空。设备端解析 delta 时要能区分“字段不存在”和“字段为 null”。
版本号不要跨设备复用：version 是单份影子文档的局部计数器，不同设备的 version 互不相关，不能用来做全局排序。
时间戳统一用 UTC 秒：避免设备本地时区导致比较错误；设备端做新鲜度判断时，应容忍一定时钟偏差，例如 ±5 分钟。

一个实用的收敛判断方法是：设备执行完 desired 后回写 reported，然后观察 delta 是否为空。若 delta 仍包含某字段，说明该字段没有被正确写回，或者写入的值与 desired 不完全相等（例如类型不同：desired 是数字 80，reported 写成了字符串 "80"）。

综合来看，设备影子数据模型的设计重点不在 JSON 语法本身，而在于把“事实、目标、差异、版本、时间”这五个语义维度表达清楚。reported 与 desired 定义状态的两个方向，delta 定义收敛路径，version 定义并发边界，timestamp 与 metadata 定义新鲜度和来源。把这五者设计好，后续的设备同步、离线控制、批量运维和故障排查才有稳定的数据基础。