4. 接口调试基础：RESTful API 设计原则、HTTP 方法、状态码、请求与响应结构

在数字工地管理现场看板图表配置中，前端看板与后端许可工作流引擎之间的所有数据交互均通过 RESTful API 完成。理解 REST 设计原则、HTTP 方法、状态码以及请求/响应结构，是进行接口调试的前提。本章将系统梳理这些基础概念，并结合看板图表配置场景进行说明。

4.1 RESTful API 设计原则

REST（Representational State Transfer）是一种基于资源的架构风格。在看板图表配置接口中，遵循以下核心原则：

• 资源导向：将业务实体抽象为资源，如 /charts（图表）、/data-sources（数据源）、/dashboards（看板）。
• 统一接口：使用标准 HTTP 方法对资源进行操作，避免自定义动作。
• 无状态：每个请求包含所有必要信息，服务器不保存客户端上下文。
• 可寻址：每个资源拥有唯一 URI，如 /charts/{chartId}。
• 表述自描述：通过 Content-Type 和 Accept 头部协商数据格式（JSON/XML）。

4.2 HTTP 方法与看板图表操作映射

下表展示了在看板图表配置中，HTTP 方法与具体业务操作的对应关系：

4.3 HTTP 状态码与调试含义

状态码是服务器对请求处理结果的直接反馈。在看板图表配置接口调试中，以下状态码最为常见：

4.4 请求与响应结构

一个标准的 RESTful 请求包含以下组成部分：

• 请求行：HTTP 方法 + URI + HTTP 版本，如 POST /api/v1/charts HTTP/1.1
• 请求头部：包含认证信息、内容类型、接受格式等元数据
• 请求体：POST/PUT/PATCH 时携带的 JSON 数据

对应的响应结构：

• 状态行：HTTP 版本 + 状态码 + 状态描述，如 HTTP/1.1 201 Created
• 响应头部：包含内容类型、缓存控制、跨域头等
• 响应体：返回的 JSON 数据，通常包含业务数据或错误信息

以下是一个创建图表配置的完整请求与响应示例：

// 请求
POST /api/v1/charts HTTP/1.1
Host: api.digital-construction.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json

{
  "dashboardId": "dash-001",
  "chartType": "bar",
  "title": "今日安全巡检统计",
  "dataSourceId": "ds-007",
  "config": {
    "xAxis": "time",
    "yAxis": "count",
    "color": "#3498db"
  }
}

// 响应
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/charts/chart-042

{
  "id": "chart-042",
  "dashboardId": "dash-001",
  "chartType": "bar",
  "title": "今日安全巡检统计",
  "dataSourceId": "ds-007",
  "config": {
    "xAxis": "time",
    "yAxis": "count",
    "color": "#3498db"
  },
  "createdAt": "2025-03-21T10:30:00Z",
  "updatedAt": "2025-03-21T10:30:00Z"
}

4.5 RESTful API 请求-响应流程（SVG）

下图展示了在看板图表配置场景中，一个完整的 RESTful API 请求-响应交互流程：

4.6 看板图表配置接口调试清单

在实际调试过程中，建议按照以下清单逐项检查：

1. URI 正确性：确认路径与 API 文档一致，注意大小写和版本号。
2. HTTP 方法：确认使用了正确的方法（GET/POST/PUT/PATCH/DELETE）。
3. 请求头部：检查 Authorization、Content-Type、Accept 是否设置正确。
4. 请求体 JSON：使用 JSON 校验工具检查格式，确保字段名与文档一致。
5. 状态码：根据返回的状态码判断问题类型（4xx 客户端问题，5xx 服务器问题）。
6. 响应体：解析返回的 JSON 数据，检查业务字段是否符合预期。
7. 错误信息：当状态码为 4xx 或 5xx 时，仔细阅读响应体中的错误描述。