3. RESTful API 设计原则：资源命名、无状态性、统一接口、HATEOAS 概念

在边缘计算场景中，HTTP API 是设备接入与数据采集的核心通信契约。REST（Representational State Transfer）架构风格为构建可伸缩、可维护的 Web 服务提供了设计准则。本章聚焦 RESTful API 的四大核心原则，帮助你在边缘网关与设备之间建立清晰、标准化的接口规范。

3.1 资源命名：用名词定义万物

REST 将一切视为“资源”（Resource），每个资源通过唯一的 URI 标识。资源命名应使用名词复数形式，避免动词，并采用层级结构表达从属关系。

3.2 无状态性：每个请求独立自足

无状态性要求服务器不保存客户端上下文。每个请求必须包含处理该请求所需的全部信息（认证令牌、参数、数据等）。

• 优势：水平扩展容易，任意服务器节点可处理任意请求；故障恢复无需会话迁移。
• 边缘场景挑战：设备可能频繁断连，无状态设计避免因会话丢失导致数据采集中断。
• 实现方式：使用 JWT（JSON Web Token）在请求头携带认证信息，而非依赖服务器 Session。

3.3 统一接口：标准化的操作契约

统一接口通过有限的 HTTP 方法表达对资源的操作，使 API 行为可预测。边缘设备接入中最常用的方法如下：

3.4 HATEOAS：让 API 自导航

HATEOAS（Hypermedia As The Engine Of Application State）是 REST 的成熟度第 3 级。服务器在响应中嵌入链接，客户端通过链接发现后续操作，无需硬编码 URI。

// 边缘设备列表响应示例（含 HATEOAS 链接）
{
  "devices": [
    {
      "id": "sensor-001",
      "type": "temperature",
      "value": 23.5,
      "unit": "°C",
      "_links": {
        "self": { "href": "/devices/sensor-001" },
        "readings": { "href": "/devices/sensor-001/readings" },
        "config": { "href": "/devices/sensor-001/config" },
        "calibrate": { "href": "/devices/sensor-001/calibrate" }
      }
    }
  ],
  "_links": {
    "self": { "href": "/devices?page=1" },
    "next": { "href": "/devices?page=2" },
    "register": { "href": "/devices" }
  }
}

3.5 四大原则关系总览

下图展示了 RESTful API 四大原则在边缘设备接入中的协作关系：资源命名定义数据模型，无状态性保障请求独立性，统一接口提供标准操作，HATEOAS 实现动态导航。

3.6 边缘场景中的 REST 成熟度模型

Leonard Richardson 提出的 REST 成熟度模型（RMM）将 API 分为 4 个等级。边缘设备接入通常从 Level 2 起步，逐步演进到 Level 3。