外观
HTTP and REST API
Phase 03 — Go Web 涵盖：
HTTP·REST API
1. 学习目标
完成本知识点后，你应该能够：
- 理解 HTTP 请求/响应的结构（Method、URL、Header、Body、Status Code）
- 掌握 REST 资源设计原则和 HTTP 动词语义
- 设计适合 Vue 前端调用的 JSON API
- 区分幂等与非幂等操作
- 为数字孪生场景设计设备、场景等 REST 资源
- 理解前后端协作中的 API 契约
2. 为什么需要
作为前端开发者，你已 daily 使用 HTTP——axios 发请求、处理状态码、调试 Network 面板。Phase 03 的目标是从服务端实现这些你熟悉的概念。Go REST API 将成为 Vue + Three.js 数字孪生前端的数据来源。
REST 不是技术，而是一种用 HTTP 表达资源操作的架构风格。好的 API 设计让前端可预测、易调试、易扩展。
3. 核心概念
3.1 HTTP 请求结构
GET /api/devices/AGV-001 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Bearer eyJ...
{ ... body for POST/PUT ... }| 部分 | 说明 |
|---|---|
| Method | GET、POST、PUT、PATCH、DELETE 等 |
| URL | 资源路径 + 查询参数 |
| Header | 元数据（Content-Type、Authorization） |
| Body | 请求体（通常 JSON） |
3.2 HTTP 响应结构
HTTP/1.1 200 OK
Content-Type: application/json
{"id":"AGV-001","online":true}3.3 常见状态码
| 码 | 含义 | 典型场景 |
|---|---|---|
| 200 | OK | GET/PUT 成功 |
| 201 | Created | POST 创建成功 |
| 204 | No Content | DELETE 成功 |
| 400 | Bad Request | 参数错误 |
| 401 | Unauthorized | 未认证 |
| 403 | Forbidden | 无权限 |
| 404 | Not Found | 资源不存在 |
| 500 | Internal Server Error | 服务端 bug |
3.4 REST 原则
- 资源用名词 URL 表示：
/devices、/scenes/{id} - 动作由 HTTP Method 表达，不用 URL 里的动词
- 无状态：每个请求包含完整上下文
- 表述：JSON 是前后端常用格式
3.5 CRUD 映射
| 操作 | Method | URL 示例 |
|---|---|---|
| 列表 | GET | /api/devices |
| 详情 | GET | /api/devices/{id} |
| 创建 | POST | /api/devices |
| 全量更新 | PUT | /api/devices/{id} |
| 部分更新 | PATCH | /api/devices/{id} |
| 删除 | DELETE | /api/devices/{id} |
4. 基础语法
API 设计示例（文档级，实现见后续知识点）：
go
// 设备资源 JSON 结构
type Device struct {
ID string `json:"id"`
Name string `json:"name"`
Type string `json:"type"` // "agv" | "sensor"
Online bool `json:"online"`
X float64 `json:"x,omitempty"`
Y float64 `json:"y,omitempty"`
}
// 统一响应包装
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}数字孪生 API 示例：
| 端点 | Method | 说明 |
|---|---|---|
/api/devices | GET | 设备列表 |
/api/devices/{id} | GET | 单设备状态 |
/api/devices/{id}/position | PATCH | 更新坐标 |
/api/scenes | GET | 3D 场景列表 |
/api/scenes/{id} | GET | 场景配置 JSON |
Vue 前端调用：
typescript
const { data } = await axios.get<Device[]>('/api/devices')5. 代码解析
REST 设计关注资源命名而非代码语法。关键点：
✅ GET /api/devices/AGV-001
❌ GET /api/getDevice?id=AGV-001
❌ POST /api/device/delete查询参数用于过滤、分页、排序，不是资源 ID：
GET /api/devices?type=agv&online=true&page=1&limit=20POST body 创建资源时，ID 通常由服务端生成：
json
POST /api/devices
{ "name": "Warehouse AGV", "type": "agv" }
→ 201 Created
{ "id": "AGV-004", "name": "Warehouse AGV", ... }6. JavaScript / TypeScript 对比
| 概念 | 前端（axios/fetch） | Go 服务端 |
|---|---|---|
| 发请求 | axios.get(url) | http.ListenAndServe 接收 |
| 请求体 | data: { ... } | json.Decoder(r.Body).Decode |
| Header | headers: { ... } | r.Header.Get("Authorization") |
| 状态码 | response.status | w.WriteHeader(404) |
| 错误处理 | interceptors | 统一 error handler middleware |
关键差异：
- 前端消费 API，Go 定义并实现 API
- 服务端决定状态码和错误格式——应文档化给前端
- CORS 是服务端配置的（下一知识点详述）
7. 常见错误
错误 1：URL 里用动词
POST /api/createDevice // ❌
POST /api/devices // ✅错误 2：滥用 POST
所有操作用 POST 会失去 HTTP 语义和缓存能力。
错误 3：200 包裹错误
json
HTTP 200
{"success": false, "error": "not found"} // ❌ 应返回 404错误 4：不一致的响应格式
列表有时返回数组，有时返回 { items: [] }，增加前端适配成本。
错误 5：缺少 API 版本
/api/v1/devices 便于未来不破坏兼容地升级。
8. 实际应用
数字孪生 — 设备 API
GET /api/v1/devices → 全部设备（Three.js 初始化场景）
GET /api/v1/devices/{id} → 单设备详情
PATCH /api/v1/devices/{id}/state → 更新位置/状态（模拟或 webhook 写入）
GET /api/v1/scenes/{id}/config → 场景模型配置实时位置推送用 WebSocket（Phase 06），REST 负责初始加载和配置管理。
与 Vue 协作
- 用 OpenAPI / 文档约定字段名（camelCase）
- 统一
{ code, message, data }响应 - 错误码与前端 toast 映射
9. 深入理解
9.1 幂等性
| Method | 幂等 |
|---|---|
| GET, PUT, DELETE | 是 |
| POST | 否 |
| PATCH | 视实现而定 |
网络重试时，幂等操作更安全。
9.2 HATEOAS
完整 REST 包含链接关系。实际项目中 JSON API 很少严格 HATEOAS，够用即可。
9.3 分页设计
json
{
"data": [...],
"pagination": { "page": 1, "limit": 20, "total": 156 }
}或 Header：X-Total-Count
9.4 REST vs GraphQL
本项目路线用 REST + WebSocket，简单直接，适合数字孪生 CRUD + 实时推送模式。
10. 练习
详细题目见
exercises/phase-03-web/01-http-rest-api.md。
Level 1 — 基础
练习 1.1：为 Device 资源设计 5 个 REST 端点（含 Method 和 URL）。
练习 1.2：列出每个端点的成功/失败状态码。
练习 1.3：编写 Device JSON 请求/响应示例。
Level 2 — 应用
练习 2.1：设计 Scene 资源的 CRUD API。
练习 2.2：设计带分页和过滤的设备列表 API。
练习 2.3：定义统一错误响应 JSON 格式。
Level 3 — 综合
练习 3.1：设计数字孪生完整 API（devices + scenes + alerts）。
练习 3.2：编写 API 文档（Markdown 表格），供 Vue 团队使用。
Level 4 — 项目实践
练习 4.1：在 workspace/phase-03/http-rest-api/ 编写 API 设计文档 API.md 和 Go struct 定义（无需 HTTP 实现）。
11. 学习检查
- GET 和 POST 在 REST 中分别对应什么操作？
- 201 和 200 分别在什么场景返回？
- 为什么 URL 不应包含动词？
- 查询参数和路径参数（
/devices/{id}）如何分工？ - 什么是幂等？为什么 PUT 是幂等的？
- 数字孪生场景中 REST 和 WebSocket 如何分工？
12. 下一步
| 已完成 | 下一知识点 | 关系 |
|---|---|---|
| HTTP, REST API | net/http, Handler, Router | 用 Go 代码实现设计的 API |
| Middleware, Validation, CORS | 完善 API 横切关注点 |
概念已熟悉的话可快速过本文档，重点放在下一节的 Go 服务端实现。