3. RESTful API设计原则

在工业物联网场景中，设备与网关、平台之间的数据交互高度依赖 API 的规范程度。RESTful API 是目前最主流的 Web API 设计风格，其核心原则包括资源命名规范、无状态通信、统一接口以及 HATEOAS。掌握这些原则，能帮助开发者设计出可维护、可扩展且易于集成的工业数据接口。

3.1 资源命名规范

RESTful API 将一切视为“资源”（Resource），每个资源通过唯一的 URI 标识。资源命名应遵循以下规范：

  • 使用名词而非动词：URI 表示资源实体，不应包含操作动词。例如 /devices 而非 /getDevices。
  • 使用复数形式：集合资源使用复数名词，如 /sensors、/gateways。
  • 层级关系通过路径表达：子资源嵌套在主资源路径下，如 /gateways/{gatewayId}/sensors。
  • 使用小写字母和连字符：避免大小写敏感问题，单词间用连字符分隔，如 /temperature-sensors。
  • 避免文件扩展名：不应出现 .json 或 .xml 后缀，通过请求头 Accept 指定返回格式。
工业示例： 某工厂设备管理系统的资源路径设计如下： 
GET    /factories/{factoryId}/production-lines
GET    /production-lines/{lineId}/machines
POST   /machines/{machineId}/telemetry
PUT    /machines/{machineId}/config
DELETE /machines/{machineId}/alarms/{alarmId}

3.2 无状态通信

无状态（Stateless）是 REST 架构的关键约束。每个请求必须包含服务器处理该请求所需的全部信息，服务器不保存客户端的状态上下文。

特性 有状态通信 无状态通信（REST）
会话管理 服务器维护 Session 客户端携带 Token / API Key
请求独立性 依赖前序请求 每个请求自包含
可扩展性 水平扩展需共享 Session 天然支持水平扩展
工业场景适用性 低（网关断连后状态丢失） 高（设备可随时重连）
工业网关实践： 网关上报设备数据时，每次请求都应携带设备 ID、时间戳和认证令牌。即使网关重启或网络中断，平台仍能正确解析数据，无需恢复会话状态。

3.3 统一接口

统一接口（Uniform Interface）通过标准 HTTP 方法对资源进行 CRUD 操作，使 API 行为可预测。工业物联网中常用的映射关系如下：

HTTP 方法 操作类型 工业 API 示例 说明
GET 查询 GET /sensors/{id}/readings?since=2025-01-01 获取传感器历史数据
POST 创建 POST /gateways/{id}/commands 向网关下发控制指令
PUT 全量更新 PUT /machines/{id}/config 更新机器全部配置参数
PATCH 部分更新 PATCH /devices/{id}/firmware 更新固件版本号
DELETE 删除 DELETE /alarms/{id} 清除某条告警记录
注意： 工业设备数据量较大时，GET 请求应支持分页、过滤和排序参数，避免一次性返回过多数据导致网关或平台负载过高。

3.4 HATEOAS 概念简介

HATEOAS（Hypermedia As The Engine Of Application State）是 REST 的进阶约束，要求 API 响应中包含相关资源的链接，客户端通过链接动态发现可执行的操作，无需硬编码 URI。

以下是一个工业网关状态查询的 HATEOAS 响应示例：

{
  "gatewayId": "GW-2025-001",
  "status": "online",
  "lastSeen": "2025-03-21T14:30:00Z",
  "_links": {
    "self": { "href": "/gateways/GW-2025-001" },
    "sensors": { "href": "/gateways/GW-2025-001/sensors" },
    "commands": { "href": "/gateways/GW-2025-001/commands" },
    "firmware": { "href": "/gateways/GW-2025-001/firmware" },
    "alarms": { "href": "/gateways/GW-2025-001/alarms?severity=critical" }
  }
}

客户端解析 _links 字段后，可动态导航到传感器列表、下发命令或查看告警，无需在代码中拼接 URI 字符串。

工业价值： 当网关固件升级后新增了诊断功能，HATEOAS 响应会自动包含 /diagnostics 链接，旧版客户端无需修改代码即可发现新能力，大幅降低系统耦合度。
RESTful API 核心原则关系图 RESTful API 资源命名规范 名词 / 复数 / 层级 无状态通信 请求自包含 统一接口 GET/POST/PUT/DELETE HATEOAS 超媒体驱动 工业物联网 API 设计要点 • 资源路径反映设备层级：工厂 → 产线 → 机器 → 传感器 • 无状态确保网关断连后数据不丢失 • 统一接口降低设备接入开发成本 • HATEOAS 支持固件升级后自动发现新功能

3.5 工业网关配置中的实践建议

在配置工业网关与平台对接时，建议遵循以下 RESTful 设计检查清单：

  • 资源路径：使用 /api/v1/gateways/{gatewayId}/telemetry 格式，版本号放在路径中。
  • 认证信息：通过 Authorization: Bearer <token> 头传递，保持无状态。
  • 响应格式：统一使用 JSON，包含 status、data、error 字段。
  • 分页规范：列表接口支持 ?page=1&size=100 参数，响应中包含 total 和 _links。
  • 错误处理：使用标准 HTTP 状态码（200、201、400、401、404、500），错误体包含 code 和 message。
推荐工具： 使用 OpenAPI（Swagger）规范描述工业 API 接口，可自动生成文档和客户端 SDK，显著提升设备接入效率。
← 上一章 📖 返回目录 下一章 →