2. HTTP API 基础：RESTful API 设计原则、HTTP 方法与数据格式
在流编排场景中，HTTP API 是数据采集与边缘设备通信的核心协议。理解 RESTful 设计原则、HTTP 方法语义以及状态码与数据格式，是构建可靠、可维护的数据管道的基础。本章将系统梳理这些基础知识，并聚焦于它们在边缘计算与流式数据采集中的实际应用。
2.1 RESTful API 设计原则
REST（Representational State Transfer）是一种架构风格，而非严格标准。在流编排与边缘集成中，遵循 RESTful 原则可以显著提升 API 的可预测性与可调试性。核心原则包括：
- 资源导向：将一切数据或服务抽象为“资源”，每个资源通过唯一的 URI 标识。例如，边缘设备上的传感器数据可表示为
/devices/{deviceId}/sensors/{sensorId}/readings。 - 无状态性：每个请求包含所有必要信息，服务器不保存客户端上下文。这对于边缘节点尤为重要，因为节点可能频繁重启或网络中断。
- 统一接口：通过标准 HTTP 方法（GET/POST/PUT/DELETE）对资源进行操作，减少接口学习成本。
- 可缓存性：响应应明确标记是否可缓存，以优化边缘节点的带宽与延迟。
- 分层系统：客户端无需关心直接与边缘节点还是云端通信，中间层（如网关、代理）对客户端透明。
流编排提示： 在边缘计算场景中，无状态性并非绝对。有时需要在边缘节点维护轻量级会话状态（如分批上传的断点续传），但应尽量通过请求头或参数传递，避免服务器端状态膨胀。
2.2 HTTP 方法语义与使用场景
HTTP 方法定义了客户端对资源期望执行的操作。在流式数据采集与边缘集成中，正确选择方法直接影响数据一致性与系统可靠性。下表对比了四种核心方法：
| 方法 | 语义 | 幂等性 | 请求体 | 典型流编排场景 |
|---|---|---|---|---|
| GET | 获取资源表示 | 是 | 无 | 查询边缘设备状态、拉取配置、轮询传感器最新值 |
| POST | 创建资源或提交处理 | 否 | 有 | 上传传感器数据批次、触发边缘计算任务、注册新设备 |
| PUT | 全量替换资源 | 是 | 有 | 更新边缘节点配置、重置设备状态、同步完整数据快照 |
| DELETE | 删除资源 | 是 | 无 | 移除离线设备、清理过期缓存、取消定时采集任务 |
避坑指南： 在边缘网络不稳定环境下，POST 的非幂等性可能导致重复数据。建议在请求体中携带客户端生成的唯一 ID（Idempotency-Key），由服务端进行去重校验。对于 PUT，务必确保客户端发送的是资源的完整表示，而非部分字段。
2.3 HTTP 状态码与数据格式
状态码是服务器对请求处理结果的标准化反馈。在流编排中，正确解析状态码是异常处理与重试策略的基础。以下是边缘计算场景中最常遇到的状态码分类：
- 2xx 成功
200 OK：GET、PUT、DELETE 成功返回。201 Created：POST 成功创建资源，响应应包含 Location 头指向新资源 URI。202 Accepted：请求已接受但尚未处理完成（常用于异步边缘任务）。204 No Content：DELETE 成功或无需返回体的操作。
- 4xx 客户端错误
400 Bad Request：请求格式错误或参数校验失败。401 Unauthorized/403 Forbidden：认证或授权失败。404 Not Found：资源不存在。409 Conflict：资源状态冲突（如版本号不匹配）。429 Too Many Requests：超出速率限制，需等待后重试。
- 5xx 服务器错误
500 Internal Server Error：通用服务器故障。502 Bad Gateway/503 Service Unavailable：边缘网关或上游服务不可用。504 Gateway Timeout：边缘节点响应超时，常见于弱网环境。
数据格式方面，JSON 是流编排与边缘集成的事实标准，因其轻量、易解析且与大多数编程语言天然兼容。一个典型的传感器数据上报请求体示例如下：
{
"deviceId": "edge-gateway-01",
"timestamp": "2025-03-21T10:30:00Z",
"readings": [
{ "sensor": "temperature", "value": 23.5, "unit": "celsius" },
{ "sensor": "humidity", "value": 68.2, "unit": "percent" }
],
"metadata": {
"batchId": "batch-20250321-001",
"retryCount": 0
}
}
最佳实践： 在边缘节点上报数据时，始终包含
timestamp 字段（使用 ISO 8601 格式）和唯一 batchId，以便服务端进行时序对齐与去重。响应体应保持简洁，例如仅返回 {"status": "accepted", "batchId": "batch-20250321-001"}。
2.4 RESTful API 在边缘采集中的典型交互流程
下图展示了一个边缘节点通过 RESTful API 向云端上报数据并获取配置的典型流程，体现了 GET 与 POST 方法的协同使用：
2.5 数据格式与序列化选择
除了 JSON，边缘计算场景中有时也会使用更紧凑的格式以节省带宽：
| 格式 | 可读性 | 序列化速度 | 数据体积 | 适用场景 |
|---|---|---|---|---|
| JSON | 高 | 中等 | 较大 | 通用、调试、低频采集 |
| MessagePack | 低 | 快 | 较小 | 高频传感器、带宽受限链路 |
| Protocol Buffers | 低 | 极快 | 最小 | 强类型、大规模边缘集群 |
流编排建议： 在课程后续的实战中，我们将默认使用 JSON 格式以保持可读性。当涉及高频数据采集（如每秒上报）时，可切换至 MessagePack 或 Protobuf，并在 HTTP 请求头中通过
Content-Type: application/msgpack 或 application/x-protobuf 声明。