3、RESTful API 设计原则：资源命名规范、无状态通信、统一接口、HATEOAS 概念简介

在工业物联网场景中，设备与网关、平台之间的数据交互高度依赖 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 架构的关键约束。每个请求必须包含服务器处理该请求所需的全部信息，服务器不保存客户端的状态上下文。

3.3 统一接口

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

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 字符串。

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。