📚 课程目录第3章 CSV模板设计原则

3. CSV模板设计原则：字段命名规范、必填字段与可选字段、数据类型与格式要求

CSV模板是批量导入设备的数据契约。一个设计良好的模板能大幅降低解析错误率，并确保设备属性、遥测、凭据等关键信息被正确映射到ThingsBoard实体。本节从字段命名、必选/可选划分、数据类型与格式三个维度，给出可直接落地的设计原则。

3.1 字段命名规范

字段命名必须同时满足CSV解析器、ThingsBoard实体模型和用户可读性三方面的要求。遵循以下规范可避免90%以上的导入失败。

原则	说明	正确示例	错误示例
全小写+下划线	字段名统一使用小写字母，单词间用下划线分隔	`device_name`	`DeviceName`、`device-name`
无空格与特殊字符	禁止空格、中文、@#%等符号，仅允许字母、数字、下划线	`serial_number`	`Serial Number`、`设备编号`
前缀分组	用前缀区分属性、遥测、凭据等不同类别	`attr_firmware_version`	`firmware_version`（无前缀易混淆）
避免保留字	不使用ThingsBoard内部字段名作为自定义字段	`attr_location`	`type`、`name`、`label`
长度限制	字段名不超过64字符，保持简洁	`ts_temperature`	`temperature_sensor_data_point_value`

  命名前缀约定：

  attr_ — 设备属性（server scope）

  ts_ — 遥测键值（time-series）

  cred_ — 设备凭据字段

  shared_ — 共享属性（shared scope）

3.2 必填字段与可选字段

ThingsBoard设备导入至少需要三个必填字段才能完成设备注册。其余字段根据业务需求可选，但建议在模板中保留常用可选字段以提升数据完整性。

字段名	必填/可选	用途	默认值
`device_name`	必填	设备唯一名称，在租户内不可重复	—
`device_type`	必填	设备类型，用于分组和规则链匹配	`default`
`credentials_token`	必填	访问令牌（Access Token），用于设备认证	自动生成（建议手动指定）
`label`	可选	设备显示标签，支持中文和空格	同 `device_name`
`attr_*`	可选	自定义属性键值对，如固件版本、安装位置	空
`ts_*`	可选	初始遥测数据，如温度、湿度初始值	空
`customer_id`	可选	将设备分配给指定客户	未分配
`device_profile_id`	可选	指定设备配置文件，控制传输类型和告警规则	默认配置文件

重要：credentials_token 在租户内必须唯一。如果留空，ThingsBoard会自动生成一个UUID作为令牌，但后续管理会变得困难。建议在CSV中为每个设备预先分配有意义的令牌值。

3.3 数据类型与格式要求

CSV是纯文本格式，但ThingsBoard API对字段值有严格的数据类型期望。错误的格式会导致导入失败或数据解析异常。下表列出常见字段的数据类型与格式规范。

字段	数据类型	格式要求	示例
`device_name`	字符串	1~255字符，不可包含换行符	`sensor_001`
`device_type`	字符串	1~64字符，推荐字母数字组合	`temperature_sensor`
`credentials_token`	字符串	1~64字符，仅允许字母、数字、连字符	`tok-abc-123`
`label`	字符串	0~255字符，支持中文和特殊符号	`车间A-温度传感器`
`attr_*`	字符串/数值/布尔	数值不加引号；布尔值使用 `true`/`false`	`attr_firmware: 2.1.0`
`ts_*`	数值/字符串	数值型遥测使用小数点格式；字符串遥测加双引号	`ts_temperature: 23.5`
`customer_id`	UUID	标准36字符UUID格式	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
`device_profile_id`	UUID	标准36字符UUID格式	`d4c3b2a1-6f5e-0987-dcba-fedcba987654`

格式检查清单：
✅ 所有字符串字段值如果包含逗号、换行符或双引号，必须用双引号包裹整个值。
✅ 数值字段不要加千位分隔符或货币符号。
✅ 时间戳遥测建议使用ISO 8601格式（2025-01-15T08:30:00Z）或Unix毫秒时间戳。
✅ 布尔值统一使用小写 true / false，不要使用 1/0 或 YES/NO。

3.4 CSV模板字段结构总览

下图展示了一个标准CSV模板的字段层级关系，从核心必填字段向外扩展至属性、遥测和可选配置字段。

3.5 常见格式错误与避坑指南

引号嵌套错误：如果字段值本身包含双引号，需使用两个双引号转义。例如："传感器""A""型" 表示值 传感器"A"型。
空值与缺列混淆：可选字段留空时，保留逗号占位（,,），不要删除整列。删除列会导致后续列错位。
BOM头干扰：使用Excel保存CSV时可能添加BOM头（EF BB BF），导致第一行字段名解析异常。建议使用VS Code或纯文本编辑器保存为UTF-8 without BOM。
换行符污染：字段值内不可包含换行符（\n、\r\n），否则CSV解析器会误判为行结束。
数值精度丢失：遥测数值超过15位有效数字时，建议使用字符串类型并标注单位，避免浮点精度问题。

  最佳实践：在正式批量导入前，先用3~5行测试数据通过ThingsBoard REST API的 /api/device/bulk/import 端点进行验证，确认所有字段映射正确后再执行全量导入。