属性类型详解：客户端属性、服务端属性、共享属性的作用域、读写权限、使用场景对比
在 ThingsBoard 中，属性（Attributes）是设备元数据的核心载体，用于存储设备的静态配置、运行状态和业务策略。根据数据流向和访问范围，属性分为三种类型：客户端属性、服务端属性和共享属性。理解三者的作用域、读写权限和适用场景，是进行批量更新与遥测优化的基础。
3.1 三种属性的核心定义与作用域
每种属性类型对应不同的数据生命周期和访问边界，下表从作用域、存储位置和可见性三个维度进行对比：
| 属性类型 | 作用域 | 存储位置 | 可见性 |
|---|---|---|---|
| 客户端属性 | 设备本地 | 设备端内存 / 本地存储 | 仅设备自身可见 |
| 服务端属性 | 平台全局 | ThingsBoard 数据库 | 平台管理员 / 租户可见 |
| 共享属性 | 设备与平台之间 | ThingsBoard 数据库 | 设备与平台双向可见 |
关键理解：客户端属性是设备的“私有记忆”，服务端属性是平台的“管理台账”，共享属性是设备与平台之间的“协商窗口”。
3.2 读写权限与数据流向
三种属性的读写权限差异决定了谁可以发起更新、谁只能读取。下图展示了完整的属性读写路径：
3.3 使用场景对比
在实际 IoT 项目中，三种属性各有典型用途。以下从设备配置、状态上报、远程控制三个维度进行场景化对比：
| 场景 | 客户端属性 | 服务端属性 | 共享属性 |
|---|---|---|---|
| 设备本地配置 | WiFi 凭据、传感器校准参数 | — | — |
| 平台管理元数据 | — | 设备固件版本、安装位置、资产编号 | — |
| 远程参数调整 | — | — | 温度阈值、采样间隔、控制指令 |
| 设备状态快照 | 当前运行模式、错误码 | 最后在线时间、数据上报统计 | 目标状态、期望值 |
| 批量更新场景 | 不支持（设备本地） | 支持（平台 API 批量写入） | 支持（平台 API 批量下发） |
实践建议：
- 将设备启动后不再变化的参数（如硬件型号）存入客户端属性，减少网络传输。
- 将设备与业务绑定的元数据（如所属项目、客户 ID）存入服务端属性，便于平台侧检索。
- 将需要远程动态调整的参数（如报警阈值、上报周期）存入共享属性，实现双向同步。
3.4 属性更新机制对比
三种属性在更新触发方式、同步延迟和冲突处理上存在显著差异：
| 对比维度 | 客户端属性 | 服务端属性 | 共享属性 |
|---|---|---|---|
| 更新触发 | 设备主动调用 clientAttributes API |
平台 REST API / 规则链 | 设备或平台均可发起 |
| 同步延迟 | 即时（设备本地） | 即时（平台侧） | 取决于 MQTT 订阅/推送机制 |
| 冲突处理 | 无冲突（单点写入） | 最后写入覆盖 | 最后写入覆盖，需业务层保证幂等 |
| 离线缓存 | 设备本地存储 | 平台数据库持久化 | 平台数据库持久化，设备离线时暂存 |
| 批量更新效率 | 不适用 | 高（单次 API 调用更新多设备） | 高（支持批量下发至设备组） |
3.5 属性类型选择决策流程
在实际项目中，可以通过以下决策树快速确定属性类型：
常见误区：
- 将客户端属性用于平台需要读取的场景——平台无法直接读取客户端属性，需设备主动上报。
- 将共享属性用于存储设备固件版本等静态信息——共享属性的双向同步机制会带来不必要的网络开销。
- 忽略服务端属性的批量更新能力——对于需要统一管理的设备元数据，服务端属性配合 REST API 可实现高效批量操作。
3.6 属性操作 API 速查
在 ThingsBoard 中，不同属性类型对应不同的 API 接口。以下是常用操作对照：
| 操作 | 客户端属性 | 服务端属性 | 共享属性 |
|---|---|---|---|
| 获取 | getClientAttributes() |
getServerAttributes() |
getSharedAttributes() |
| 更新 | saveClientAttributes() |
saveServerAttributes() |
saveSharedAttributes() |
| 删除 | deleteClientAttributes() |
deleteServerAttributes() |
deleteSharedAttributes() |
| 订阅变化 | 不支持 | 不支持 | subscribeToSharedAttributes() |
在设备端固件中，典型的属性操作代码示例如下：
// 客户端属性：设备本地存储
clientAttributes.put("wifi_ssid", "HomeNetwork");
clientAttributes.put("calibration_factor", 1.05);
saveClientAttributes(clientAttributes);
// 共享属性：设备发布供平台读取
sharedAttributes.put("temperature_threshold", 30.0);
sharedAttributes.put("report_interval", 60);
saveSharedAttributes(sharedAttributes);
// 订阅共享属性变化（平台下发新配置时触发）
subscribeToSharedAttributes((key, value) -> {
if ("report_interval".equals(key)) {
updateReportInterval((int) value);
}
});
优化建议：在批量更新场景中，优先使用服务端属性和共享属性的 REST API 进行批量操作，避免逐设备调用 MQTT 接口。单次 REST 调用可更新数千台设备的属性，效率提升显著。