0 Fork 0

Files

T

oneao f4c7413dc6 20260823210241

2026-08-23 21:02:41 +08:00

17 KiB

Raw Blame History

API接口文档

**本文引用的文件** - [AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java) - [DataController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java) - [FileController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java) - [AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java) - [DataService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataService.java) - [DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java) - [FileService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java) - [JwtUtils.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java) - [ApiResponse.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java) - [FileStorageProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java)

简介

本文件为FMS系统的API接口参考文档，覆盖认证、数据与文件三大类RESTful接口。文档包含：

每个接口的HTTP方法、URL路径、请求参数、响应格式与错误码说明
JWT认证流程的调用示例（登录、令牌使用）
元数据驱动的数据接口调用方式（动态查询、分页、批量保存、自动编码生成）
文件上传、下载、预览等操作的完整示例
版本兼容性与向后兼容性说明

项目结构

后端采用Spring Boot分层架构：

控制器层：按业务域划分（认证、数据、文件）
服务层：封装业务逻辑（认证、数据读写、文件存取、批量保存）
工具与配置：统一响应体、JWT工具、文件存储配置等

graph TB
subgraph "控制器"
AC["AuthController"]
DC["DataController"]
FC["FileController"]
end
subgraph "服务"
AS["AuthService"]
DS["DataService"]
DSS["DataSaveService"]
FS["FileService"]
end
subgraph "工具与配置"
JWT["JwtUtils"]
RESP["ApiResponse"]
FSP["FileStorageProperties"]
end
AC --> AS
DC --> DS
DC --> DSS
FC --> FS
AS --> JWT
FS --> FSP
AC -.-> RESP
DC -.-> RESP
FC -.-> RESP

图表来源

章节来源

核心组件

统一响应体 ApiResponse：提供成功/失败封装及标准错误码
JWT工具 JwtUtils：负责令牌签发与解析
文件存储配置 FileStorageProperties：本地/OSS模式配置
各控制器与服务：实现认证、数据、文件相关能力

章节来源

架构总览

下图展示典型请求在系统中的流转路径，以“登录”和“数据分页”为例。

sequenceDiagram
participant C as "客户端"
participant A as "AuthController"
participant S as "AuthService"
participant J as "JwtUtils"
participant R as "ApiResponse"
C->>A : POST /auth/login {orgid, userid, password}
A->>S : login(orgid, userid, password, request)
S-->>A : Optional<Map> (token, orgid, user)
A-->>C : ApiResponse{code=0, data={token,...}}

图表来源

详细组件分析

认证接口

基础信息
- 基础路径：/auth
- 认证方式：登录后返回JWT，后续请求需在请求头携带令牌（由前端或网关注入）
- 统一响应：ApiResponse
登录
- 方法：POST
- 路径：/auth/login
- 请求体字段
  - orgid：机构码（必填）
  - userid：用户ID（必填）
  - password：密码（必填）
- 响应data
  - token：JWT字符串
  - orgid：机构码
  - user：{ id, account, name }
- 错误码
  - 401：认证失败（机构码、账号或密码错误）
  - 1000：业务异常（如参数缺失）
调用示例（登录）
- 请求
  - POST /auth/login
  - Body: { "orgid": "ORG001", "userid": "U001", "password": "xxx" }
- 响应
  - { "code": 0, "message": "操作成功", "data": { "token": "...", "orgid": "ORG001", "user": { "id": 123, "account": "U001", "name": "张三" } } }
令牌刷新
- 当前未提供独立的刷新接口；建议前端在令牌过期时重新调用登录获取新令牌
安全提示
- 登录成功后服务端会记录会话并生成JWT；后续访问受保护资源需携带有效令牌

章节来源

数据接口（元数据驱动）

基础信息
- 基础路径：/data
- 元数据驱动：通过表/视图名与列元数据进行动态查询与保存
- 统一响应：ApiResponse
动态查询
- 方法：POST
- 路径：/data/loaddata
- 请求体字段
  - view_name：视图名（必填）
  - search_condition：搜索条件（可选）
  - order_by：排序（可选）
  - search_columns：搜索列（可选）
- 响应data：List<Map<String,Object>>
SQL直查
- 方法：POST
- 路径：/data/loaddatabysql
- 请求体字段
  - sql：SQL语句（必填）
- 响应data：List<Map<String,Object>>
分页查询
- 方法：POST
- 路径：/data/page
- 请求体字段
  - view_name：视图名（必填）
  - search_columns：搜索列（可选）
  - search_condition：搜索条件（可选）
  - order_by：排序（必填）
  - page_no：页码（默认1）
  - page_size：每页条数（默认20）
- 响应data
  - rows：列表
  - row_count：本页条数
  - total：总条数
  - page_no：当前页
  - page_size：每页大小
描述元数据
- 方法：POST
- 路径：/data/describe
- 请求体字段
  - table：表名（必填）
- 响应data：列元数据列表
批量保存（事务）
- 方法：POST
- 路径：/data/saveobjt
- 请求体：数组，每项为一个表的保存指令
  - table：目标表名（必填）
  - key_field：主键字段名（必填）
  - deletes：删除行数组（可选）
  - updates：更新行数组（可选）
  - inserts：新增行数组（可选）
- 行为
  - 同一请求内对多个表的操作在同一事务中执行
  - 任一失败将回滚整个请求
- 响应data：null（成功）
批量保存流程图

flowchart TD
Start(["进入 saveobjt"]) --> Validate["校验请求体非空"]
Validate --> BeginTx["开启事务"]
BeginTx --> LoadMeta["加载表元数据(缓存)"]
LoadMeta --> ExecDelete{"是否存在deletes?"}
ExecDelete --> |是| DoDelete["执行删除"]
ExecDelete --> |否| ExecUpdate{"是否存在updates?"}
DoDelete --> ExecUpdate
ExecUpdate --> |是| DoUpdate["执行更新"]
ExecUpdate --> |否| ExecInsert{"是否存在inserts?"}
DoUpdate --> ExecInsert
ExecInsert --> |是| DoInsert["执行新增"]
ExecInsert --> |否| Commit["提交事务"]
DoInsert --> Commit
Commit --> End(["返回成功"])

图表来源

DataSaveService.java:34-58
DataSaveService.java:381-423
自动生成编号
- 方法：POST
- 路径：/data/nextcode
- 请求体字段
  - moduleId：模块ID（必填）
  - count：生成数量（可选，默认1，范围1-1000）
- 响应data：单个字符串或字符串数组
雪花ID生成
- 方法：POST
- 路径：/data/nextid
- 请求体字段
  - count：生成数量（可选，默认1）
- 响应data：单个Long或Long数组

章节来源

文件接口

基础信息
- 基础路径：/file
- 存储模式：本地或OSS（通过配置切换）
- 统一响应：ApiResponse
获取存储配置
- 方法：POST
- 路径：/file/config
- 响应data
  - storageType：local 或 aliyun-oss
本地上传（FormData）
- 方法：POST
- 路径：/file/upload
- 表单字段
  - files：文件数组（必填）
  - father：父级ID（必填）
  - moduleId：模块ID（必填）
  - cateId：分类ID（可选）
- 响应data：文件元数据数组
  - subid：文件唯一标识
  - mx_filename：原始文件名
  - mx_filesize：文件大小
  - mx_fileext：扩展名
  - mx_mapfilename：映射路径（用于访问）
  - father：父级ID
  - mx_moduleid：模块ID
  - mx_cate_id：分类ID
OSS上传凭证
- 方法：POST
- 路径：/file/upload-credential
- 用途：前端直传OSS前获取凭证
- 响应data：OSS上传所需凭证对象
保存文件记录（OSS回调）
- 方法：POST
- 路径：/file/save-record
- 请求体：文件元数据（含subid、father、mx_moduleid、mx_filename、mx_filesize、mx_fileext、mx_mapfilename、mx_cate_id等）
- 响应data：保存结果
删除文件
- 方法：POST
- 路径：/file/delete
- 请求体
  - subid：文件ID（必填）
- 行为：根据存储模式删除物理文件与数据库记录
本地文件访问/预览
- 方法：GET
- 路径：/file/static/{fileName:.+}
- 说明：fileName包含子目录结构（如 {orgId}/{yyyy}/{MM}/{dd}/{file}）
- 响应：文件流，浏览器可直接预览或下载
文件上传序列图（本地模式）

sequenceDiagram
participant C as "客户端"
participant FC as "FileController"
participant FS as "FileService"
participant DB as "数据库"
C->>FC : POST /file/upload (files, father, moduleId, cateId)
FC->>FS : localUpload(files, ...)
FS->>DB : 插入bf_files记录
FS-->>FC : List<元数据>
FC-->>C : ApiResponse{data : [...]}

图表来源

章节来源

依赖关系分析

控制器依赖服务：认证、数据、文件各自解耦
服务依赖工具与配置：
- AuthService依赖JwtUtils进行令牌签发
- FileService依赖FileStorageProperties决定存储策略
- DataSaveService通过DbUtils进行元数据驱动的持久化
统一响应体贯穿所有接口

graph LR
AC["AuthController"] --> AS["AuthService"]
DC["DataController"] --> DS["DataService"]
DC --> DSS["DataSaveService"]
FC["FileController"] --> FS["FileService"]
AS --> JWT["JwtUtils"]
FS --> FSP["FileStorageProperties"]
AC -.-> RESP["ApiResponse"]
DC -.-> RESP
FC -.-> RESP

图表来源

性能考虑

分页查询：page接口支持分页，避免一次性拉取大量数据
元数据缓存：批量保存时对表元数据进行缓存，减少重复查询
事务控制：saveobjt在同一事务中处理多表操作，保证一致性
文件I/O：本地上传顺序写入磁盘后落库，避免大对象阻塞；OSS模式支持直传减轻服务器压力
连接管理：数据库连接通过DataSourceUtils获取与释放，防止连接泄漏

[本节为通用指导，不直接分析具体文件]

故障排查指南

常见错误码
- 0：成功
- 1000：业务异常（如参数校验失败）
- 2001：保存错误（批量保存失败）
- 401：认证失败（登录失败或令牌无效）
- 40101：会话被替换（并发登录场景）
- 500：系统错误
定位建议
- 检查请求体字段是否齐全且类型正确
- 查看统一响应体的message字段获取具体错误信息
- 对于批量保存失败，关注SaveObjectException中的表名、操作与索引信息
- 文件删除失败时确认存储模式与路径前缀配置是否正确

章节来源

结论

本API文档覆盖了FMS系统的认证、数据与文件三大核心能力，提供了完整的接口规范、调用示例与错误码说明。通过元数据驱动的数据接口与事务化的批量保存，系统具备良好的扩展性与一致性保障。文件接口同时支持本地与OSS两种存储模式，满足多样化部署需求。

[本节为总结性内容，不直接分析具体文件]

附录

统一响应体规范

结构
- code：状态码
- message：消息
- data：业务数据
常用状态码
- 0：成功
- 1000：业务异常
- 2001：保存错误
- 401：认证失败
- 40101：会话被替换
- 500：系统错误

章节来源

ApiResponse.java:1-32

版本兼容性与向后兼容

向后兼容原则
- 新增可选参数不影响已有调用
- 响应体新增字段不影响解析
- 错误码保持向下兼容，新增错误码不修改既有含义
建议
- 前端对未知字段做忽略处理
- 对关键必填参数做好校验与降级策略

[本节为通用指导，不直接分析具体文件]

17 KiB Raw Blame History Unescape Escape

API接口文档

目录

简介

项目结构

核心组件

架构总览

详细组件分析

认证接口

数据接口（元数据驱动）

文件接口

依赖关系分析

性能考虑

故障排查指南

结论

附录

统一响应体规范

版本兼容性与向后兼容

17 KiB

Raw Blame History