📚 课程目录第4章数据标准化与接口设计

4. 数据标准化与接口设计：传感器元数据模型定义、JSON/XML数据交换格式、RESTful API接口规范、MQTT消息队列集成

数据标准化这件事，说白了就是给传感器发回来的数据定个规矩。没有规矩，你想想看，温度传感器报个"25.3"，压力传感器报个"101.325"，可谁分得清哪个是温度哪个是压力？我在项目里见过太多因为数据格式不统一导致的集成灾难了。

4.1 传感器元数据模型定义

元数据，就是描述数据的数据。对于工业传感器，我们需要定义一套通用的元数据模型，让每个传感器都能说清楚自己是谁、在哪儿、测什么、怎么测的。

我个人习惯把元数据模型分成三层：

设备层：传感器ID、型号、厂商、固件版本、序列号
测量层：物理量类型（温度/压力/振动等）、单位、量程、精度、采样频率
通信层：协议类型、数据格式、上报周期、心跳间隔

核心原则：元数据一旦注册，尽量不变。变动的只有测量值。这样设计，数据存储和查询效率都会高很多。

举个例子，一个温度传感器的元数据模型大概长这样：

{
  "deviceId": "TEMP-001-A3B4",
  "model": "PT100-4W",
  "manufacturer": "Siemens",
  "firmware": "v2.1.3",
  "measurement": {
    "type": "temperature",
    "unit": "celsius",
    "rangeMin": -50,
    "rangeMax": 150,
    "accuracy": 0.1
  },
  "communication": {
    "protocol": "MQTT",
    "topic": "factory/line1/oven/temperature",
    "interval": 5000
  }
}

嗯，这里要注意：deviceId 必须是全局唯一的。我曾经在一个项目里吃过亏，两个不同产线的传感器用了相同的ID，结果数据全混了，排查了整整两天。

4.2 JSON/XML 数据交换格式

工业场景里，JSON 和 XML 都在用。JSON 轻量、解析快，适合边缘计算和云端通信；XML 严谨、带 Schema 校验，适合需要严格数据契约的场景，比如和 ERP/MES 系统对接。

我一般这样选型：

对比维度	JSON	XML
数据体积	小（约 XML 的 60%）	大（标签冗余多）
解析性能	快（原生 JavaScript 支持）	慢（需要 DOM/SAX 解析器）
Schema 校验	JSON Schema（较新）	XSD（成熟稳定）
工业协议兼容	OPC UA 支持 JSON	PLC 历史数据常用 XML
可读性	简洁，适合人眼扫读	标签嵌套，结构清晰但冗长

我个人建议：新项目优先用 JSON，除非客户明确要求 XML 或者需要和遗留系统对接。我在一个汽车零部件工厂的项目里，就因为坚持用 JSON，把传感器上报延迟从 200ms 降到了 50ms。

来看一个实际的数据交换示例。传感器上报温度数据：

// JSON 格式
{
  "deviceId": "TEMP-001-A3B4",
  "timestamp": "2025-03-21T14:30:00Z",
  "value": 85.3,
  "quality": "good",
  "battery": 78
}

// XML 格式
<?xml version="1.0" encoding="UTF-8"?>
<SensorData>
  <DeviceId>TEMP-001-A3B4</DeviceId>
  <Timestamp>2025-03-21T14:30:00Z</Timestamp>
  <Value>85.3</Value>
  <Quality>good</Quality>
  <Battery>78</Battery>
</SensorData>

小技巧：如果系统需要同时支持 JSON 和 XML，可以在 RESTful API 的请求头里加 Accept: application/json 或 Accept: application/xml，服务端根据头信息自动切换序列化方式。这样一套接口，两种格式都支持。

4.3 RESTful API 接口规范

RESTful API 是传感器注册和数据交互的"门面"。设计得好，后续集成省一半力气。我总结了一套工业传感器专用的 API 规范，核心就四个字：资源驱动。

每个传感器都是一个资源，用 URL 来标识：

POST /api/v1/sensors — 注册新传感器
GET /api/v1/sensors/{deviceId} — 查询传感器元数据
PUT /api/v1/sensors/{deviceId} — 更新传感器配置
DELETE /api/v1/sensors/{deviceId} — 注销传感器
POST /api/v1/sensors/{deviceId}/data — 上报测量数据
GET /api/v1/sensors/{deviceId}/data?from=...&to=... — 查询历史数据

接口响应格式要统一。我习惯这样设计：

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": { ... }  // 具体数据
}

// 错误响应
{
  "code": 400,
  "message": "invalid deviceId",
  "error": "deviceId format must be XXX-XXX-XXXX"
}

避坑指南：我曾经设计过一套 API，不同接口的错误码格式不统一，有的返回 errorCode，有的返回 err_code，还有的返回 code。结果前端对接时写了一大堆 if-else。后来我强制所有接口用同一套响应模板，再也没出过这种问题。

另外，分页查询一定要做。工业场景下，一个工厂可能有上万台传感器，不分页的话，一次查询就能把数据库打崩。我常用的分页参数：

GET /api/v1/sensors?page=1&size=50&sort=createdAt&order=desc

返回格式：

{
  "code": 200,
  "data": {
    "items": [ ... ],
    "total": 1024,
    "page": 1,
    "size": 50,
    "hasMore": true
  }
}

4.4 MQTT 消息队列集成

MQTT 在工业物联网里几乎是标配。为什么？因为它轻量、支持发布/订阅模式、还能保证消息送达。传感器数据上报用 MQTT，比 HTTP 轮询靠谱多了。

我一般这样设计 MQTT 主题结构：

factory/{工厂ID}/{产线ID}/{设备类型}/{设备ID}/{数据类型}

举个例子：

factory/F001/L001/temperature/TEMP-001-A3B4/value — 温度值
factory/F001/L001/temperature/TEMP-001-A3B4/status — 设备状态
factory/F001/L001/temperature/TEMP-001-A3B4/alarm — 报警信息

这样做的好处是，订阅方可以用通配符灵活订阅。比如想监控整个产线 L001 的所有温度传感器，只需要订阅 factory/F001/L001/temperature/+/value 就行。

MQTT 的 QoS（服务质量）等级也要选对：

QoS 等级	含义	适用场景
0	最多一次（可能丢消息）	环境温度、湿度等非关键数据
1	至少一次（可能重复）	设备状态、心跳包
2	恰好一次（最可靠）	报警、安全相关数据

我的经验：大部分传感器数据用 QoS 1 就够了。QoS 2 虽然可靠，但性能开销大，容易造成消息堆积。只有在处理安全报警这类"绝对不能丢也不能重复"的数据时，才用 QoS 2。

最后，来看一张整体架构图，把上面这些串起来：

这张图把整个数据流串起来了。传感器上报数据走 MQTT，元数据管理走 RESTful API，两者各司其职。你想想看，如果所有数据都走 HTTP，那服务器压力得多大？MQTT 的长连接和发布/订阅模式，天生就是为这种高频、小数据量的场景设计的。

总结一下：元数据模型是骨架，JSON/XML 是血肉，RESTful API 是门面，MQTT 是血管。四者配合好了，工业传感器注册和数据交互才能跑得稳、跑得快。