docs: 扩展接口分域与维护原则文档
- 补充接口分域架构（四大核心域） - 补充接口 URL 规范和禁止事项 - 补充 Swagger 注解规范和变更流程 - 补充版本管理策略和跨域处理原则 - 补充 Swagger UI 地址和 OpenAPI 导出
This commit is contained in:
226
开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md
Normal file
226
开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 01-接口分域与维护原则
|
||||
|
||||
本文档定义 AIOT 系统 API 接口的组织原则、文档维护责任边界，以及接口变更的协作流程。
|
||||
|
||||
**核心原则**：接口文档优先按**业务域**维护，而非按页面或客户端维护。因为页面会变、客户端会增，但领域边界相对稳定。
|
||||
|
||||
---
|
||||
|
||||
## 一、接口分域架构
|
||||
|
||||
### 1.1 四大核心域
|
||||
|
||||
| 域标识 | 对应微服务 | 职责范围 | 负责人 |
|
||||
|--------|-----------|---------|--------|
|
||||
| `system` | `module-system` | 用户、角色、菜单、部门、租户、字典 | 后端架构组 |
|
||||
| `infra` | `module-infra` | 文件管理、定时任务、代码生成、消息推送 | 后端架构组 |
|
||||
| `ops` | `module-ops` | 工单、巡检、保洁、安保、排班、考勤 | Ops 业务组 |
|
||||
| `iot` | `module-iot` | 设备、物模型、规则引擎、告警、MQTT 桥接 | IoT 业务组 |
|
||||
|
||||
### 1.2 接口 URL 规范
|
||||
|
||||
所有接口必须遵循 RESTful 风格，并按域组织路径：
|
||||
|
||||
```
|
||||
GET /api/system/users # 用户列表
|
||||
POST /api/system/users # 创建用户
|
||||
GET /api/system/users/{id} # 用户详情
|
||||
PUT /api/system/users/{id} # 更新用户
|
||||
DELETE /api/system/users/{id} # 删除用户
|
||||
|
||||
GET /api/ops/tickets # 工单列表
|
||||
POST /api/ops/tickets/{id}/dispatch # 派单（业务操作）
|
||||
POST /api/ops/tickets/{id}/confirm # 确认到岗（业务操作）
|
||||
|
||||
GET /api/iot/devices # 设备列表
|
||||
POST /api/iot/devices/{id}/reboot # 重启设备（业务操作）
|
||||
```
|
||||
|
||||
**禁止事项**：
|
||||
- ❌ `/api/getUserList` - 非 RESTful
|
||||
- ❌ `/api/ticket/updateStatus` - 动词在 URL 中，应使用 `/api/tickets/{id}/status`
|
||||
- ❌ `/api/opsAndIot/xxx` - 跨域接口应拆分或通过事件驱动
|
||||
|
||||
---
|
||||
|
||||
## 二、接口文档维护责任
|
||||
|
||||
### 2.1 Swagger 注解是唯一的真理源
|
||||
|
||||
**所有接口必须在 Controller 方法上完整标注 Swagger 注解**：
|
||||
|
||||
```java
|
||||
@RestController
|
||||
@RequestMapping("/ops/tickets")
|
||||
@Tag(name = "工单管理", description = "工单 CRUD 及状态流转")
|
||||
public class TicketController {
|
||||
|
||||
@PostMapping("/dispatch")
|
||||
@Operation(summary = "派单", description = "将工单派发给指定保洁员")
|
||||
@PreAuthorize("@ss.hasPermi('ops:ticket:dispatch')")
|
||||
public CommonResult<Long> dispatchTicket(@RequestBody @Valid TicketDispatchReqVO reqVO) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**必填注解**：
|
||||
- `@Tag` - 接口分组（对应域）
|
||||
- `@Operation(summary = ..., description = ...)` - 接口用途
|
||||
- `@Parameter` / `@Schema` - 参数说明
|
||||
- `@ApiResponse` - 返回码说明（特别是业务错误码）
|
||||
|
||||
### 2.2 接口变更流程
|
||||
|
||||
```
|
||||
开发者修改接口
|
||||
↓
|
||||
更新 Swagger 注解
|
||||
↓
|
||||
提交 MR → 自动触发 Swagger 文档生成
|
||||
↓
|
||||
前端/移动端负责人 Review 文档
|
||||
↓
|
||||
确认无破坏性变更后合并
|
||||
```
|
||||
|
||||
**破坏性变更定义**（需提前通知所有调用方）：
|
||||
- 删除或重命名已有字段
|
||||
- 修改字段类型（如 `String` → `Integer`）
|
||||
- 增加必填参数
|
||||
- 修改接口路径或 HTTP 方法
|
||||
|
||||
**非破坏性变更**（可直接发布）：
|
||||
- 新增可选参数
|
||||
- 新增接口
|
||||
- 增加返回字段
|
||||
|
||||
---
|
||||
|
||||
## 三、为什么不按页面维护接口文档
|
||||
|
||||
### 3.1 错误示例
|
||||
|
||||
```
|
||||
❌ 按页面组织：
|
||||
- 保洁管理页面接口
|
||||
- 获取保洁员列表
|
||||
- 创建保洁员
|
||||
- 编辑保洁员
|
||||
- 工单列表页面接口
|
||||
- 获取工单列表
|
||||
- 工单详情
|
||||
```
|
||||
|
||||
**问题**：
|
||||
1. 同一个 `/api/ops/cleaners` 接口可能被保洁管理页面、工单派发页面、排班页面同时使用
|
||||
2. 新增一个移动端页面时，接口文档需要重复维护
|
||||
3. 页面重构或合并时，接口文档需要大量调整
|
||||
|
||||
### 3.2 正确示例
|
||||
|
||||
```
|
||||
✅ 按业务域组织：
|
||||
- ops 域
|
||||
- 保洁员管理
|
||||
- GET /api/ops/cleaners - 保洁员列表
|
||||
- POST /api/ops/cleaners - 创建保洁员
|
||||
- PUT /api/ops/cleaners/{id} - 更新保洁员
|
||||
- 工单管理
|
||||
- GET /api/ops/tickets - 工单列表
|
||||
- POST /api/ops/tickets/{id}/dispatch - 派单
|
||||
```
|
||||
|
||||
**优势**：
|
||||
1. 接口与页面解耦，一个接口服务多个客户端
|
||||
2. 领域边界清晰，便于微服务拆分
|
||||
3. 新增客户端（如小程序）时，直接引用已有域文档
|
||||
|
||||
---
|
||||
|
||||
## 四、接口版本管理
|
||||
|
||||
### 4.1 版本号位置
|
||||
|
||||
当需要发布不兼容的接口变更时，使用 URL 路径版本号：
|
||||
|
||||
```
|
||||
GET /api/v1/ops/tickets # 旧版本
|
||||
GET /api/v2/ops/tickets # 新版本（字段结构变化）
|
||||
```
|
||||
|
||||
**禁止使用**：
|
||||
- ❌ Query 参数版本：`/api/ops/tickets?version=2`
|
||||
- ❌ Header 版本：`X-API-Version: 2`（不利于缓存和调试）
|
||||
|
||||
### 4.2 版本共存策略
|
||||
|
||||
- 新版本发布后，旧版本至少保留 **3 个月** 过渡期
|
||||
- 在网关层监控旧版本接口的调用量，提前通知调用方迁移
|
||||
- 过渡期结束后，在网关层返回 `410 Gone` 并引导升级
|
||||
|
||||
---
|
||||
|
||||
## 五、跨域接口处理
|
||||
|
||||
### 5.1 禁止跨域直接调用
|
||||
|
||||
```java
|
||||
// ❌ 错误：ops 服务直接调用 iot 服务的 Feign Client
|
||||
@Autowired
|
||||
private IotDeviceClient deviceClient;
|
||||
|
||||
public void dispatchTicket() {
|
||||
// 直接调用 IoT 服务
|
||||
deviceClient.getDeviceStatus(deviceId);
|
||||
}
|
||||
```
|
||||
|
||||
**问题**：
|
||||
- 微服务之间产生强耦合
|
||||
- 无法独立部署和扩展
|
||||
- 故障传播（IoT 服务宕机拖垮 Ops 服务）
|
||||
|
||||
### 5.2 正确做法：事件驱动
|
||||
|
||||
```java
|
||||
// ✅ 正确：通过消息队列解耦
|
||||
// Ops 服务发布事件
|
||||
applicationEventPublisher.publishEvent(new TicketDispatchedEvent(ticketId, deviceId));
|
||||
|
||||
// IoT 服务监听事件并处理
|
||||
@EventListener
|
||||
public void onTicketDispatched(TicketDispatchedEvent event) {
|
||||
// 处理设备相关逻辑
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、接口文档访问
|
||||
|
||||
### 6.1 Swagger UI 地址
|
||||
|
||||
| 环境 | 地址 |
|
||||
|------|------|
|
||||
| 开发环境 | `http://localhost:48080/swagger-ui.html` |
|
||||
| 测试环境 | `http://test-api.example.com/swagger-ui.html` |
|
||||
| 生产环境 | **不开放**（通过内部文档平台查看） |
|
||||
|
||||
### 6.2 导出 OpenAPI 规范
|
||||
|
||||
```bash
|
||||
# 导出 YAML 格式
|
||||
curl http://localhost:48080/v3/api-docs -o openapi.yaml
|
||||
|
||||
# 导出 JSON 格式
|
||||
curl http://localhost:48080/v3/api-docs -o openapi.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、相关文档
|
||||
|
||||
- [00-支撑平台总览.md](../00-支撑平台总览.md)
|
||||
- [01-统一网关入口规范.md](../01-统一网关入口规范.md)
|
||||
- [08-数据库/01-数据域划分与表关系思路.md](../08-数据库/01-数据域划分与表关系思路.md)
|
||||
Reference in New Issue
Block a user