106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
|
# Part 7: 接口文档
|
|||
|
|
|
|||
|
|
> **文档定位**：明确前后端交互的接口标准 (RESTful API)，介绍 API 文档的自动生成与聚合访问方式，以及网关层的路由转发规则。
|
|||
|
|
|
|||
|
|
## 7.1 RESTful API 规范
|
|||
|
|
|
|||
|
|
平台所有 HTTP 接口严格遵循 RESTful 设计风格，HTTP Status Code 与业务 Error Code 分离。
|
|||
|
|
|
|||
|
|
### 7.1.1 URL 设计
|
|||
|
|
* **版本控制**：`/admin-api/system/user/v1/page`
|
|||
|
|
* **动词使用**：
|
|||
|
|
* `GET`：查询资源（幂等）
|
|||
|
|
* `POST`：创建资源（非幂等）
|
|||
|
|
* `PUT`：更新资源（全量）
|
|||
|
|
* `DELETE`：删除资源
|
|||
|
|
|
|||
|
|
### 7.1.2 响应结构
|
|||
|
|
HTTP Status Code 标识网络层状态，Response Body 中的 `code` 标识业务状态。
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0, // 0 表示成功，非 0 表示业务异常
|
|||
|
|
"msg": "success", // 错误提示信息
|
|||
|
|
"data": { // 业务数据
|
|||
|
|
"id": 1001,
|
|||
|
|
"username": "admin"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.1.3 常用错误码
|
|||
|
|
| Code | 类型 | 说明 |
|
|||
|
|
| :--- | :--- | :--- |
|
|||
|
|
| **0** | Success | 请求成功 |
|
|||
|
|
| **400** | Client Error | 参数校验失败 |
|
|||
|
|
| **401** | Unauthorized | 未登录或 Token 过期 |
|
|||
|
|
| **403** | Forbidden | 无权限访问该资源 |
|
|||
|
|
| **429** | Too Many Requests | 请求过于频繁（触发限流） |
|
|||
|
|
| **500** | Server Error | 系统内部未知错误 |
|
|||
|
|
| **100xxx** | Biz Error | [100001] 系统模块异常 |
|
|||
|
|
| **200xxx** | Biz Error | [200001] IoT 模块异常 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.2 接口文档聚合 (Knife4j)
|
|||
|
|
|
|||
|
|
项目采用 **Knife4j** (Swagger 的增强版) 实现接口文档的自动生成与微服务聚合。
|
|||
|
|
|
|||
|
|
### 7.2.1 访问地址
|
|||
|
|
* **统一入口**：`http://{gateway-ip}:48080/doc.html`
|
|||
|
|
* **原理**：Gateway 服务集成 `knife4j-gateway-spring-boot-starter`，自动发现并聚合所有 Nacos 中注册的微服务 Swagger 文档。
|
|||
|
|
|
|||
|
|
### 7.2.2 开发注解规范
|
|||
|
|
后端开发必须使用 Swagger 注解描述接口含义：
|
|||
|
|
* `@Tag(name = "管理后台 - 用户管理")`：标记 Controller。
|
|||
|
|
* `@Operation(summary = "获得用户分页")`：标记接口方法。
|
|||
|
|
* `@Schema(description = "用户编号")`：标记 VO/DTO 字段。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.3 Gateway 路由规则
|
|||
|
|
|
|||
|
|
网关根据请求 Path 前缀将流量转发至对应的微服务。
|
|||
|
|
|
|||
|
|
| 请求前缀 (Prefix) | 目标服务 (Target Service) | 说明 |
|
|||
|
|
| :--- | :--- | :--- |
|
|||
|
|
| `/admin-api/system/**` | `viewsh-module-system-server` | 系统/租户/权限相关 |
|
|||
|
|
| `/admin-api/infra/**` | `viewsh-module-infra-server` | 文件/定时任务相关 |
|
|||
|
|
| `/admin-api/iot/**` | `viewsh-module-iot-server` | 设备管理/规则引擎 |
|
|||
|
|
| `/admin-api/ops/**` | `viewsh-module-ops-server` | 运营工单/报修 |
|
|||
|
|
| `/app-api/**` | `viewsh-module-system-server` | 移动端 App 接口（部分复用） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.4 核心接口示例
|
|||
|
|
|
|||
|
|
### 7.4.1 设备遥测数据上报 (HTTP)
|
|||
|
|
* **URL**: `http://{gateway}:8092/iot/device/report`
|
|||
|
|
* **Method**: `POST`
|
|||
|
|
* **Body**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"productKey": "a1B2c3D4",
|
|||
|
|
"deviceName": "sn-0001",
|
|||
|
|
"ts": 1678888888000,
|
|||
|
|
"params": {
|
|||
|
|
"temperature": 25.6,
|
|||
|
|
"humidity": 60
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.4.2 创建维修工单 (Admin)
|
|||
|
|
* **URL**: `http://{gateway}:48080/admin-api/ops/work-order/create`
|
|||
|
|
* **Method**: `POST`
|
|||
|
|
* **Header**: `Authorization: Bearer {token}`
|
|||
|
|
* **Body**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "REPAIR",
|
|||
|
|
"deviceId": 10001,
|
|||
|
|
"desc": "空调异响，需检查风扇",
|
|||
|
|
"priority": 2
|
|||
|
|
}
|
|||
|
|
```
|