3. RESTful API 设计原则：资源定义、HTTP方法、状态码与版本控制

在车辆门窗控制功能中，RESTful API 是后端服务与车载中控、手机 App 或云端平台之间的通信契约。本章将围绕四个核心设计原则展开：资源定义、HTTP 方法、状态码选择和版本控制策略。遵循这些原则，可以构建出可维护、可扩展且语义清晰的车辆控制接口。

3.1 资源定义：将车辆门窗抽象为 URI

REST 的核心是将业务实体抽象为“资源”。在车辆门窗场景中，资源层级通常如下：

• 车辆（Vehicle）：顶层资源，代表一辆具体的车。
• 门（Door）：属于车辆的子资源，如左前门、右后门。
• 窗（Window）：属于门的子资源，控制升降。
• 锁（Lock）：属于门的状态资源，控制闭锁/解锁。

资源命名应使用名词复数形式，避免动词。例如使用 /windows 而非 /openWindow。URI 中的变量（如 {vin}）代表具体资源实例。

3.2 HTTP 方法：CRUD 与车辆控制语义映射

标准 HTTP 方法对应不同的操作意图。在车辆门窗控制中，我们将其映射为：

3.3 状态码选择：精确表达车辆控制结果

HTTP 状态码是客户端判断请求结果的直接依据。在车辆控制场景中，状态码的选择需要覆盖成功、客户端错误、服务端错误以及车辆特有的“异步处理”情况。

3.4 版本控制策略：保障接口演进兼容性

车辆软件 OTA 升级频繁，API 版本控制是避免破坏现有客户端的关键。推荐使用 URI 路径版本控制，将版本号显式放在路径中：

# 当前稳定版本
GET /api/v1/vehicles/{vin}/doors

# 未来新版本（引入新字段或行为）
GET /api/v2/vehicles/{vin}/doors

版本控制策略对比：

3.5 综合示例：车窗控制 API 设计

以下是一个完整的车窗控制 API 设计示例，整合了上述原则：

# 1. 查询所有车窗状态（GET）
GET /api/v1/vehicles/WBA1234567890/doors/driver/windows
响应 200 OK
{
  "windows": [
    { "window_id": "front_left", "position": 75, "state": "stationary" },
    { "window_id": "front_right", "position": 0, "state": "closed" }
  ]
}

# 2. 升起左前车窗（POST 创建控制任务）
POST /api/v1/vehicles/WBA1234567890/doors/driver/windows/front_left/actions
请求体
{ "action": "raise", "target_position": 100 }
响应 202 Accepted
{
  "task_id": "task-20250301-001",
  "status": "pending",
  "estimated_completion_ms": 3500
}

# 3. 查询控制任务状态（GET）
GET /api/v1/vehicles/WBA1234567890/tasks/task-20250301-001
响应 200 OK
{
  "task_id": "task-20250301-001",
  "status": "completed",
  "result": { "final_position": 100, "obstacle_detected": false }
}

# 4. 取消控制任务（DELETE）
DELETE /api/v1/vehicles/WBA1234567890/tasks/task-20250301-001
响应 204 No Content

3.6 RESTful 设计原则总览图

下图展示了 RESTful API 设计原则在车辆门窗控制中的整体架构关系：

3.7 状态码选择决策流程

在实际开发中，选择正确的状态码可以遵循以下决策流程：