358 lines
22 KiB
Markdown
358 lines
22 KiB
Markdown
|
|
# API接口文档
|
|||
|
|
|
|||
|
|
<cite>
|
|||
|
|
**本文引用的文件**
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md)
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java)
|
|||
|
|
- [script/idea/http-client.env.json](file://script/idea/http-client.env.json)
|
|||
|
|
</cite>
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
1. [简介](#简介)
|
|||
|
|
2. [项目结构](#项目结构)
|
|||
|
|
3. [核心组件](#核心组件)
|
|||
|
|
4. [架构总览](#架构总览)
|
|||
|
|
5. [详细组件分析](#详细组件分析)
|
|||
|
|
6. [依赖关系分析](#依赖关系分析)
|
|||
|
|
7. [性能考量](#性能考量)
|
|||
|
|
8. [故障排查指南](#故障排查指南)
|
|||
|
|
9. [结论](#结论)
|
|||
|
|
10. [附录](#附录)
|
|||
|
|
|
|||
|
|
## 简介
|
|||
|
|
本文件为 AIOT 平台云项目的 API 接口文档,覆盖 RESTful API 的规范、认证与授权机制、版本管理与兼容策略、错误码体系、接口调用示例、性能与最佳实践,以及测试与调试方法。文档内容以仓库现有实现与技术文档为依据,确保准确性与可追溯性。
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
- API 以微服务形式提供,统一通过网关进行路由与文档聚合。
|
|||
|
|
- 网关负责:
|
|||
|
|
- 将请求前缀映射到对应后端服务;
|
|||
|
|
- 聚合 Knife4j 文档;
|
|||
|
|
- 重写 Swagger 路径以便文档展示。
|
|||
|
|
- 后端服务通过 OpenFeign 定义 RPC 接口契约,便于跨服务调用。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TB
|
|||
|
|
GW["网关<br/>viewsh-gateway"] --> SYS["系统服务<br/>system-server"]
|
|||
|
|
GW --> INFRA["基础设施服务<br/>infra-server"]
|
|||
|
|
GW --> IOT["物联网服务<br/>iot-server"]
|
|||
|
|
GW --> OPS["运营服务<br/>ops-server"]
|
|||
|
|
GW --> OTHERS["其他服务<br/>..."]
|
|||
|
|
DOC["Knife4j 聚合文档<br/>/doc.html"] --> GW
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L210)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
- 网关路由与文档聚合
|
|||
|
|
- 网关根据请求前缀将流量转发至对应微服务,并对 Swagger 文档进行聚合展示。
|
|||
|
|
- 统一响应结构
|
|||
|
|
- 所有接口返回统一结构,HTTP 状态码与业务 code 分离,便于前端与客户端处理。
|
|||
|
|
- 错误码体系
|
|||
|
|
- 系统模块与 IoT 模块分别维护错误码常量,便于定位业务异常。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L5-L42)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java#L12-L171)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java#L12-L82)
|
|||
|
|
|
|||
|
|
## 架构总览
|
|||
|
|
- 网关路由规则
|
|||
|
|
- 管理后台与移动端接口前缀清晰划分,便于权限与路由控制。
|
|||
|
|
- 文档聚合
|
|||
|
|
- 通过 Knife4j 聚合各微服务的 OpenAPI 文档,统一入口访问。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant C as "客户端"
|
|||
|
|
participant G as "网关"
|
|||
|
|
participant S as "后端服务"
|
|||
|
|
C->>G : "HTTP 请求含前缀"
|
|||
|
|
G->>G : "匹配路由规则"
|
|||
|
|
G->>S : "转发请求重写路径"
|
|||
|
|
S-->>G : "统一响应结构"
|
|||
|
|
G-->>C : "返回响应"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L59)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
|
|||
|
|
## 详细组件分析
|
|||
|
|
|
|||
|
|
### 认证与授权机制
|
|||
|
|
- 访问令牌传递方式
|
|||
|
|
- 支持在请求头中携带令牌(默认 Header 名称),以及通过查询参数传递(用于 WebSocket 等场景)。
|
|||
|
|
- 安全配置
|
|||
|
|
- 基于 Spring Security 的 Web 安全适配器,支持免登录白名单、CSRF、表单登录与 HTTP Basic 等。
|
|||
|
|
- 令牌使用
|
|||
|
|
- 管理后台接口通常需要携带 Bearer Token;具体接口请参考各服务的 OpenAPI 文档。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
Start(["开始"]) --> CheckHeader["检查请求头是否存在令牌"]
|
|||
|
|
CheckHeader --> HasHeader{"存在?"}
|
|||
|
|
HasHeader --> |是| UseHeader["使用请求头令牌"]
|
|||
|
|
HasHeader --> |否| CheckParam["检查查询参数是否存在令牌"]
|
|||
|
|
CheckParam --> HasParam{"存在?"}
|
|||
|
|
HasParam --> |是| UseParam["使用查询参数令牌"]
|
|||
|
|
HasParam --> |否| Deny["拒绝访问未认证"]
|
|||
|
|
UseHeader --> End(["结束"])
|
|||
|
|
UseParam --> End
|
|||
|
|
Deny --> End
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java#L17-L28)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java#L1-L23)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L75-L106)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java#L17-L28)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java#L1-L23)
|
|||
|
|
|
|||
|
|
### 统一响应结构与错误码
|
|||
|
|
- 统一响应结构
|
|||
|
|
- code:业务状态码(0 表示成功)
|
|||
|
|
- msg:错误提示信息
|
|||
|
|
- data:业务数据
|
|||
|
|
- 常用 HTTP 状态码与业务错误码
|
|||
|
|
- 成功、参数校验失败、未登录/Token 过期、无权限、限流、系统内部错误、系统模块与 IoT 模块业务错误等
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
erDiagram
|
|||
|
|
RESPONSE {
|
|||
|
|
int code
|
|||
|
|
string msg
|
|||
|
|
json data
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L17-L42)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L17-L42)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java#L12-L171)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java#L12-L82)
|
|||
|
|
|
|||
|
|
### 网关路由与文档聚合
|
|||
|
|
- 路由规则
|
|||
|
|
- 管理后台前缀:/admin-api/{module}/**
|
|||
|
|
- 移动端前缀:/app-api/**(部分复用系统服务)
|
|||
|
|
- 物联网设备上报等特殊路径由网关单独处理
|
|||
|
|
- 文档聚合
|
|||
|
|
- 通过 Knife4j 聚合各服务的 OpenAPI 文档,统一入口访问
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
A["请求 /admin-api/system/**"] --> B["网关匹配 system 路由"]
|
|||
|
|
B --> C["转发到 system-server"]
|
|||
|
|
D["请求 /admin-api/iot/**"] --> E["网关匹配 iot 路由"]
|
|||
|
|
E --> F["转发到 iot-server"]
|
|||
|
|
G["请求 /doc.html"] --> H["Knife4j 聚合各服务文档"]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
|
|||
|
|
### 系统模块接口示例(RPC)
|
|||
|
|
- 管理员用户查询
|
|||
|
|
- 通过用户 ID 查询用户
|
|||
|
|
- 获取用户列表(按 ID、部门、岗位)
|
|||
|
|
- 校验用户有效性
|
|||
|
|
- 权限相关
|
|||
|
|
- 获取拥有多个角色的用户编号集合
|
|||
|
|
- 短信验证码
|
|||
|
|
- 发送验证码
|
|||
|
|
- 使用验证码
|
|||
|
|
- 校验验证码有效性
|
|||
|
|
- 社交用户
|
|||
|
|
- 绑定社交用户
|
|||
|
|
- 解绑社交用户
|
|||
|
|
- 基于用户 ID 或授权码获取社交用户
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant Client as "调用方"
|
|||
|
|
participant Gateway as "网关"
|
|||
|
|
participant System as "system-server"
|
|||
|
|
Client->>Gateway : "GET /admin-api/system/user/v3/api-docs"
|
|||
|
|
Gateway->>System : "转发请求"
|
|||
|
|
System-->>Gateway : "OpenAPI 文档"
|
|||
|
|
Gateway-->>Client : "聚合后的文档"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L221-L271)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L32-L82)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L22-L26)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java#L24-L34)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java#L24-L54)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L32-L82)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L22-L26)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java#L24-L34)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/social/SocialUserApi.java#L24-L54)
|
|||
|
|
|
|||
|
|
### 物联网模块接口示例(RPC)
|
|||
|
|
- 设备属性查询
|
|||
|
|
- 批量查询设备属性历史
|
|||
|
|
- 查询设备属性当前值
|
|||
|
|
- 设备状态查询
|
|||
|
|
- 查询设备状态
|
|||
|
|
- 设备控制
|
|||
|
|
- 控制设备执行服务(如下发指令)
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant Client as "调用方"
|
|||
|
|
participant Gateway as "网关"
|
|||
|
|
participant IOT as "iot-server"
|
|||
|
|
Client->>Gateway : "POST /admin-api/iot/device/control"
|
|||
|
|
Gateway->>IOT : "转发控制请求"
|
|||
|
|
IOT-->>Gateway : "控制结果"
|
|||
|
|
Gateway-->>Client : "统一响应"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java)
|
|||
|
|
|
|||
|
|
### 错误码与异常处理
|
|||
|
|
- 系统模块错误码
|
|||
|
|
- 包括认证、菜单、角色、用户、部门、岗位、字典、通知公告、短信渠道、短信模板、短信发送、短信验证码、租户、租户套餐、社交用户、OAuth2 客户端与授权、邮箱账号、邮件模板、邮件发送、站内信模板与发送等。
|
|||
|
|
- 物联网模块错误码
|
|||
|
|
- 包括产品、物模型、设备、产品分类、设备分组、OTA 固件与任务、数据流转规则与目的、场景联动、告警配置与记录等。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ErrorCodeConstants.java#L12-L171)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ErrorCodeConstants.java#L12-L82)
|
|||
|
|
|
|||
|
|
## 依赖关系分析
|
|||
|
|
- 网关依赖
|
|||
|
|
- 通过路由规则将不同前缀的请求转发到对应服务;
|
|||
|
|
- 通过 Knife4j 配置聚合各服务的 OpenAPI 文档。
|
|||
|
|
- 服务间依赖
|
|||
|
|
- 后端服务通过 OpenFeign 定义 RPC 接口契约,便于跨服务调用与文档生成。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph LR
|
|||
|
|
G["网关配置"] --> R["路由规则"]
|
|||
|
|
G --> K["Knife4j 聚合"]
|
|||
|
|
SYS["system-server"] --> FEIGN_SYS["Feign 接口定义"]
|
|||
|
|
IOT["iot-server"] --> FEIGN_IOT["Feign 接口定义"]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L25-L28)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L271)
|
|||
|
|
- [viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L25-L28)
|
|||
|
|
- [viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
|
|||
|
|
|
|||
|
|
## 性能考量
|
|||
|
|
- 网关缓冲区与序列化配置
|
|||
|
|
- 调整内存缓冲区大小,优化大对象传输;
|
|||
|
|
- Jackson 序列化配置,减少时间戳单位开销。
|
|||
|
|
- 文档聚合与缓存
|
|||
|
|
- 通过 Knife4j 聚合文档,减少客户端多次请求;
|
|||
|
|
- 合理设置服务实例灰度负载均衡,提升可用性。
|
|||
|
|
- 限流与熔断
|
|||
|
|
- 结合网关与服务侧限流策略,保障系统稳定性。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L8-L18)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L38-L38)
|
|||
|
|
|
|||
|
|
## 故障排查指南
|
|||
|
|
- 未登录或 Token 过期
|
|||
|
|
- 检查请求头 Authorization 是否正确携带 Bearer Token;
|
|||
|
|
- 若使用 WebSocket,确认 token 参数是否正确传递。
|
|||
|
|
- 无权限访问
|
|||
|
|
- 确认用户角色与权限范围;
|
|||
|
|
- 检查免登录白名单配置。
|
|||
|
|
- 请求过于频繁
|
|||
|
|
- 检查限流策略与客户端重试逻辑;
|
|||
|
|
- 适当降低请求频率或增加退避策略。
|
|||
|
|
- 系统内部错误
|
|||
|
|
- 查看服务日志与异常堆栈;
|
|||
|
|
- 确认数据库连接与第三方依赖可用性。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L35-L41)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/SecurityProperties.java#L17-L28)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/java/com/viewsh/framework/security/config/ViewshWebSecurityConfigurerAdapter.java#L1-L23)
|
|||
|
|
|
|||
|
|
## 结论
|
|||
|
|
本接口文档基于项目现有实现与技术文档整理而成,明确了 RESTful API 规范、认证授权机制、版本与路由策略、统一响应结构与错误码体系,并提供了测试与调试方法。建议在后续迭代中持续完善各服务的 OpenAPI 文档,确保接口定义与实现保持一致。
|
|||
|
|
|
|||
|
|
## 附录
|
|||
|
|
|
|||
|
|
### 版本管理与兼容策略
|
|||
|
|
- 版本控制
|
|||
|
|
- URL 中包含版本号(如 v1、v3),便于平滑演进与向后兼容。
|
|||
|
|
- 兼容策略
|
|||
|
|
- 新增字段采用可选策略,避免破坏既有客户端;
|
|||
|
|
- 旧字段保留并标注废弃,逐步迁移。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L9-L16)
|
|||
|
|
|
|||
|
|
### 接口调用示例
|
|||
|
|
- 设备遥测数据上报(HTTP)
|
|||
|
|
- URL:/iot/device/report
|
|||
|
|
- 方法:POST
|
|||
|
|
- 请求体包含产品标识、设备名称、时间戳与参数对象
|
|||
|
|
- 创建维修工单(管理后台)
|
|||
|
|
- URL:/admin-api/ops/work-order/create
|
|||
|
|
- 方法:POST
|
|||
|
|
- 请求头:Authorization: Bearer {token}
|
|||
|
|
- 请求体包含工单类型、设备 ID、描述与优先级
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L77-L106)
|
|||
|
|
|
|||
|
|
### 测试工具与调试方法
|
|||
|
|
- IDEA HTTP Client 环境变量
|
|||
|
|
- 可通过环境文件配置基础 URL、Token 等参数,便于批量测试。
|
|||
|
|
- 文档聚合入口
|
|||
|
|
- 通过统一入口访问 Knife4j 聚合文档,快速定位接口与参数。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [script/idea/http-client.env.json](file://script/idea/http-client.env.json)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L49-L51)
|