XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1197363ac6ea5d7f1554360bbc89eceecb4fabbb
aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/API接口文档.md

22 KiB
Raw Blame History

API接口文档

**本文引用的文件** - [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)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件为 AIOT 平台云项目的 API 接口文档，覆盖 RESTful API 的规范、认证与授权机制、版本管理与兼容策略、错误码体系、接口调用示例、性能与最佳实践，以及测试与调试方法。文档内容以仓库现有实现与技术文档为依据，确保准确性与可追溯性。

项目结构

  • API 以微服务形式提供，统一通过网关进行路由与文档聚合。
  • 网关负责：
    • 将请求前缀映射到对应后端服务；
    • 聚合 Knife4j 文档；
    • 重写 Swagger 路径以便文档展示。
  • 后端服务通过 OpenFeign 定义 RPC 接口契约，便于跨服务调用。
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

图表来源

章节来源

核心组件

  • 网关路由与文档聚合
    • 网关根据请求前缀将流量转发至对应微服务，并对 Swagger 文档进行聚合展示。
  • 统一响应结构
    • 所有接口返回统一结构，HTTP 状态码与业务 code 分离，便于前端与客户端处理。
  • 错误码体系
    • 系统模块与 IoT 模块分别维护错误码常量，便于定位业务异常。

章节来源

架构总览

  • 网关路由规则
    • 管理后台与移动端接口前缀清晰划分，便于权限与路由控制。
  • 文档聚合
    • 通过 Knife4j 聚合各微服务的 OpenAPI 文档，统一入口访问。
sequenceDiagram
participant C as "客户端"
participant G as "网关"
participant S as "后端服务"
C->>G : "HTTP 请求含前缀"
G->>G : "匹配路由规则"
G->>S : "转发请求重写路径"
S-->>G : "统一响应结构"
G-->>C : "返回响应"

图表来源

章节来源

详细组件分析

认证与授权机制

  • 访问令牌传递方式
    • 支持在请求头中携带令牌（默认 Header 名称），以及通过查询参数传递（用于 WebSocket 等场景）。
  • 安全配置
    • 基于 Spring Security 的 Web 安全适配器，支持免登录白名单、CSRF、表单登录与 HTTP Basic 等。
  • 令牌使用
    • 管理后台接口通常需要携带 Bearer Token；具体接口请参考各服务的 OpenAPI 文档。
flowchart TD
Start(["开始"]) --> CheckHeader["检查请求头是否存在令牌"]
CheckHeader --> HasHeader{"存在？"}
HasHeader --> |是| UseHeader["使用请求头令牌"]
HasHeader --> |否| CheckParam["检查查询参数是否存在令牌"]
CheckParam --> HasParam{"存在？"}
HasParam --> |是| UseParam["使用查询参数令牌"]
HasParam --> |否| Deny["拒绝访问未认证"]
UseHeader --> End(["结束"])
UseParam --> End
Deny --> End

图表来源

章节来源

统一响应结构与错误码

  • 统一响应结构
    • code：业务状态码（0 表示成功）
    • msg：错误提示信息
    • data：业务数据
  • 常用 HTTP 状态码与业务错误码
    • 成功、参数校验失败、未登录/Token 过期、无权限、限流、系统内部错误、系统模块与 IoT 模块业务错误等
erDiagram
RESPONSE {
int code
string msg
json data
}

图表来源

章节来源

网关路由与文档聚合

  • 路由规则
    • 管理后台前缀：/admin-api/{module}/**
    • 移动端前缀：/app-api/**（部分复用系统服务）
    • 物联网设备上报等特殊路径由网关单独处理
  • 文档聚合
    • 通过 Knife4j 聚合各服务的 OpenAPI 文档，统一入口访问
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 聚合各服务文档"]

图表来源

章节来源

系统模块接口示例（RPC）

  • 管理员用户查询
    • 通过用户 ID 查询用户
    • 获取用户列表（按 ID、部门、岗位）
    • 校验用户有效性
  • 权限相关
    • 获取拥有多个角色的用户编号集合
  • 短信验证码
    • 发送验证码
    • 使用验证码
    • 校验验证码有效性
  • 社交用户
    • 绑定社交用户
    • 解绑社交用户
    • 基于用户 ID 或授权码获取社交用户
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 : "聚合后的文档"

图表来源

章节来源

物联网模块接口示例（RPC）

  • 设备属性查询
    • 批量查询设备属性历史
    • 查询设备属性当前值
  • 设备状态查询
    • 查询设备状态
  • 设备控制
    • 控制设备执行服务（如下发指令）
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 : "统一响应"

图表来源

章节来源

错误码与异常处理

  • 系统模块错误码
    • 包括认证、菜单、角色、用户、部门、岗位、字典、通知公告、短信渠道、短信模板、短信发送、短信验证码、租户、租户套餐、社交用户、OAuth2 客户端与授权、邮箱账号、邮件模板、邮件发送、站内信模板与发送等。
  • 物联网模块错误码
    • 包括产品、物模型、设备、产品分类、设备分组、OTA 固件与任务、数据流转规则与目的、场景联动、告警配置与记录等。

章节来源

依赖关系分析

  • 网关依赖
    • 通过路由规则将不同前缀的请求转发到对应服务；
    • 通过 Knife4j 配置聚合各服务的 OpenAPI 文档。
  • 服务间依赖
    • 后端服务通过 OpenFeign 定义 RPC 接口契约，便于跨服务调用与文档生成。
graph LR
G["网关配置"] --> R["路由规则"]
G --> K["Knife4j 聚合"]
SYS["system-server"] --> FEIGN_SYS["Feign 接口定义"]
IOT["iot-server"] --> FEIGN_IOT["Feign 接口定义"]

图表来源

章节来源

性能考量

  • 网关缓冲区与序列化配置
    • 调整内存缓冲区大小，优化大对象传输；
    • Jackson 序列化配置，减少时间戳单位开销。
  • 文档聚合与缓存
    • 通过 Knife4j 聚合文档，减少客户端多次请求；
    • 合理设置服务实例灰度负载均衡，提升可用性。
  • 限流与熔断
    • 结合网关与服务侧限流策略，保障系统稳定性。

章节来源

故障排查指南

  • 未登录或 Token 过期
    • 检查请求头 Authorization 是否正确携带 Bearer Token；
    • 若使用 WebSocket，确认 token 参数是否正确传递。
  • 无权限访问
    • 确认用户角色与权限范围；
    • 检查免登录白名单配置。
  • 请求过于频繁
    • 检查限流策略与客户端重试逻辑；
    • 适当降低请求频率或增加退避策略。
  • 系统内部错误
    • 查看服务日志与异常堆栈；
    • 确认数据库连接与第三方依赖可用性。

章节来源

结论

本接口文档基于项目现有实现与技术文档整理而成，明确了 RESTful API 规范、认证授权机制、版本与路由策略、统一响应结构与错误码体系，并提供了测试与调试方法。建议在后续迭代中持续完善各服务的 OpenAPI 文档，确保接口定义与实现保持一致。

附录

版本管理与兼容策略

  • 版本控制
    • URL 中包含版本号（如 v1、v3），便于平滑演进与向后兼容。
  • 兼容策略
    • 新增字段采用可选策略，避免破坏既有客户端；
    • 旧字段保留并标注废弃，逐步迁移。

章节来源

接口调用示例

  • 设备遥测数据上报（HTTP）
    • URL：/iot/device/report
    • 方法：POST
    • 请求体包含产品标识、设备名称、时间戳与参数对象
  • 创建维修工单（管理后台）
    • URL：/admin-api/ops/work-order/create
    • 方法：POST
    • 请求头：Authorization: Bearer {token}
    • 请求体包含工单类型、设备 ID、描述与优先级

章节来源

测试工具与调试方法

  • IDEA HTTP Client 环境变量
    • 可通过环境文件配置基础 URL、Token 等参数，便于批量测试。
  • 文档聚合入口
    • 通过统一入口访问 Knife4j 聚合文档，快速定位接口与参数。

章节来源