266 lines
12 KiB
Markdown
266 lines
12 KiB
Markdown
# API接口文档
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
|
||
- [AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java)
|
||
- [ApiResult.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java)
|
||
- [STATE.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java)
|
||
- [Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java)
|
||
- [BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java)
|
||
- [application.yml（admin）](file://nflg-wms-admin/src/main/resources/application.yml)
|
||
- [application.yml（auth）](file://nflg-wms-auth/src/main/resources/application.yml)
|
||
- [ApiMark.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java)
|
||
- [ApiStorageTest.java](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java)
|
||
- [ApiServiceImpl.java](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java)
|
||
- [pom.xml（根）](file://pom.xml)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件为NFLG WMS系统的完整API接口文档，覆盖仓储管理、物料管理、订单处理等业务域的RESTful接口设计与规范。文档基于仓库中的Spring Boot微服务架构与统一返回体、状态码体系进行整理，并结合注解标记与测试用例对接口进行梳理与归档。同时提供认证与授权机制说明、错误处理策略、版本与兼容性建议、客户端集成与SDK使用指引，以及Postman集合与curl示例的准备思路。
|
||
|
||
## 项目结构
|
||
系统采用多模块聚合工程，核心模块包括：
|
||
- 公共模块：统一返回体、常量、异常与工具
|
||
- 启动器模块：基础控制器基类、通用注解
|
||
- 认证模块：统一认证中心（SSO）
|
||
- 管理模块：业务管理端服务
|
||
- 仓储模块：接口清单持久化与查询
|
||
- 网关与定时任务等其他模块
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "公共层"
|
||
COMMON["nflg-wms-common<br/>统一返回体/常量/异常"]
|
||
STARTER["nflg-wms-starter<br/>基础控制器/注解"]
|
||
end
|
||
subgraph "服务层"
|
||
AUTH["nflg-wms-auth<br/>认证中心(SSO)"]
|
||
ADMIN["nflg-wms-admin<br/>管理服务"]
|
||
REPO["nflg-wms-repository<br/>接口清单持久化"]
|
||
end
|
||
GATEWAY["nflg-wms-gateway<br/>网关(可选)"]
|
||
ROOT["根pom<br/>多模块聚合"]
|
||
ROOT --> COMMON
|
||
ROOT --> STARTER
|
||
ROOT --> AUTH
|
||
ROOT --> ADMIN
|
||
ROOT --> REPO
|
||
ROOT --> GATEWAY
|
||
ADMIN --> COMMON
|
||
ADMIN --> STARTER
|
||
AUTH --> COMMON
|
||
AUTH --> STARTER
|
||
REPO --> COMMON
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml（根）:17-28](file://pom.xml#L17-L28)
|
||
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
|
||
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
|
||
|
||
章节来源
|
||
- [pom.xml（根）:17-28](file://pom.xml#L17-L28)
|
||
- [application.yml（admin）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [application.yml（auth）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
|
||
|
||
## 核心组件
|
||
- 统一返回体与状态码
|
||
- 统一返回体封装了响应码、类型、消息、时间戳、追踪ID与结果数据；支持分页转换与多种错误构造方式。
|
||
- 状态枚举覆盖系统错误、成功、参数错误、权限拒绝、业务异常、请求方式错误、库存不足等场景。
|
||
- 基础控制器
|
||
- 提供二维码内容生成等通用能力，便于各业务控制器复用。
|
||
- 注解与接口清单
|
||
- 使用自定义注解标记接口模块与名称，并通过测试用例扫描注册到接口清单表中，形成可维护的接口目录。
|
||
|
||
章节来源
|
||
- [ApiResult.java:16-121](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L121)
|
||
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)
|
||
- [BaseController.java:17-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L17-L77)
|
||
- [ApiMark.java:8-17](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java#L8-L17)
|
||
- [ApiStorageTest.java:28-65](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java#L28-L65)
|
||
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)
|
||
|
||
## 架构总览
|
||
系统采用Spring Cloud微服务架构，认证中心提供统一SSO认证，管理服务承载业务接口，公共模块提供统一返回与常量，启动器模块提供基础能力与注解，仓储模块用于接口清单的持久化与查询。
|
||
|
||
```mermaid
|
||
graph TB
|
||
CLIENT["客户端/第三方系统"]
|
||
GATEWAY["网关(可选)"]
|
||
AUTH["认证中心(nflg-wms-auth)<br/>端口8101"]
|
||
ADMIN["管理服务(nflg-wms-admin)<br/>端口8102"]
|
||
COMMON["公共模块(nflg-wms-common)"]
|
||
STARTER["启动器模块(nflg-wms-starter)"]
|
||
REPO["仓储模块(nflg-wms-repository)"]
|
||
CLIENT --> GATEWAY
|
||
GATEWAY --> AUTH
|
||
GATEWAY --> ADMIN
|
||
ADMIN --> COMMON
|
||
ADMIN --> STARTER
|
||
ADMIN --> REPO
|
||
AUTH --> COMMON
|
||
AUTH --> STARTER
|
||
```
|
||
|
||
图表来源
|
||
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
|
||
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
|
||
- [application.yml（admin）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [application.yml（auth）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
|
||
|
||
## 详细组件分析
|
||
|
||
### 认证与授权机制
|
||
- Token与SSO
|
||
- 认证中心通过Sa-Token提供SSO能力，默认Token名称为authorization，超时时间为2592000秒（30天），Ticket超时为300秒。
|
||
- 客户端在访问受保护资源时，应在请求头携带authorization字段。
|
||
- 登录扩展信息
|
||
- 登录时会附加用户名、工号、邮箱、部门ID、角色、用户类型等扩展信息，便于前端与后端进行权限控制与个性化展示。
|
||
- 权限验证
|
||
- 业务接口应结合角色与菜单按钮权限进行校验，具体策略由各业务模块在控制器中实现。
|
||
|
||
章节来源
|
||
- [application.yml（auth）:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)
|
||
- [Constant.java:11-22](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L11-L22)
|
||
|
||
### 错误处理与统一返回体
|
||
- 统一返回体字段
|
||
- code：响应码
|
||
- type：响应类型
|
||
- message：提示信息
|
||
- extras：额外信息（如错误详情）
|
||
- time：服务器时间
|
||
- traceId：链路追踪ID
|
||
- result：业务结果
|
||
- 常见状态码
|
||
- 成功：200
|
||
- 参数错误：101
|
||
- 信息错误：102
|
||
- 操作失败：103
|
||
- 没有权限：104
|
||
- 用户校验失败：105
|
||
- 请重新登录：106
|
||
- 上传失败：107
|
||
- 数据不完整无法提交或审核：108
|
||
- 服务连接异常：109
|
||
- 访问地址不存在：110
|
||
- 请求服务异常：111
|
||
- 账号异地登录：112
|
||
- 页面跳转：113
|
||
- 页面异常：114
|
||
- 业务异常：115
|
||
- 请求方式错误：116
|
||
- 需要用户确认：117
|
||
- 订单不存在：118
|
||
- SAP错误：119
|
||
- 库存不足：120
|
||
|
||
章节来源
|
||
- [ApiResult.java:16-121](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L121)
|
||
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)
|
||
|
||
### 接口命名与模块化
|
||
- 接口命名规范
|
||
- 使用@ApiMark注解标注接口模块名与接口名，并声明是否公开接口。
|
||
- 接口清单管理
|
||
- 通过测试用例扫描所有带@ApiMark的方法，自动注册或更新接口清单，便于统一管理与文档化。
|
||
|
||
章节来源
|
||
- [ApiMark.java:8-17](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java#L8-L17)
|
||
- [ApiStorageTest.java:28-65](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java#L28-L65)
|
||
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)
|
||
|
||
### 二维码打印与内容生成
|
||
- 通用二维码内容生成
|
||
- 基础控制器提供二维码内容生成方法，便于在打印、扫码等环节复用。
|
||
|
||
章节来源
|
||
- [BaseController.java:30-37](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L30-L37)
|
||
|
||
## 依赖分析
|
||
- 模块间依赖
|
||
- 管理服务与认证中心均依赖公共模块与启动器模块，确保统一的返回体、常量与注解能力。
|
||
- 接口清单服务依赖公共模块的VO与实体，用于接口目录的分组与查询。
|
||
- 外部依赖
|
||
- Sa-Token用于SSO与JWT，Actuator用于健康检查与监控，Nacos用于配置与服务发现。
|
||
|
||
```mermaid
|
||
graph LR
|
||
ADMIN["nflg-wms-admin"] --> COMMON["nflg-wms-common"]
|
||
ADMIN --> STARTER["nflg-wms-starter"]
|
||
ADMIN --> REPO["nflg-wms-repository"]
|
||
AUTH["nflg-wms-auth"] --> COMMON
|
||
AUTH --> STARTER
|
||
REPO --> COMMON
|
||
```
|
||
|
||
图表来源
|
||
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
|
||
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
|
||
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)
|
||
|
||
章节来源
|
||
- [pom.xml（根）:54-192](file://pom.xml#L54-L192)
|
||
|
||
## 性能考虑
|
||
- 并发与重试
|
||
- 管理服务启用重试与调度，有助于提升部分业务的可用性与稳定性。
|
||
- 监控与追踪
|
||
- Actuator开启健康检查与Redis数据库健康探测，支持链路追踪与采样概率设置。
|
||
- 文件上传
|
||
- 管理服务配置了较大的文件与请求大小限制，满足大文件导入导出场景。
|
||
|
||
章节来源
|
||
- [AdminApplication.java:16-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L16-L18)
|
||
- [application.yml（admin）:24-27](file://nflg-wms-admin/src/main/resources/application.yml#L24-L27)
|
||
- [application.yml（admin）:31-48](file://nflg-wms-admin/src/main/resources/application.yml#L31-L48)
|
||
|
||
## 故障排查指南
|
||
- 常见错误码定位
|
||
- 参数错误、业务异常、权限不足、请求方式错误、SAP错误、库存不足等，均可通过统一返回体中的code与message快速定位。
|
||
- 追踪ID
|
||
- 返回体包含traceId，可用于日志检索与问题定位。
|
||
- 登录与SSO
|
||
- 若出现“用户校验失败”或“请重新登录”，检查authorization头与Token有效性；确认认证中心配置与回调地址。
|
||
|
||
章节来源
|
||
- [ApiResult.java:16-24](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L24)
|
||
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)
|
||
- [application.yml（auth）:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)
|
||
|
||
## 结论
|
||
本API文档基于仓库现有实现，明确了统一返回体、状态码、认证授权、错误处理与接口清单管理等关键机制。建议后续补充各业务模块的具体接口定义与示例，以完善端到端的API使用体验。
|
||
|
||
## 附录
|
||
|
||
### API版本管理与兼容性
|
||
- 版本策略
|
||
- 建议在URL中引入版本前缀（如/v1），并在服务端通过网关或路由进行版本分流。
|
||
- 向后兼容
|
||
- 新增字段采用可选策略，避免破坏既有调用；变更字段需通过新版本发布并提供迁移指引。
|
||
|
||
### 客户端集成与SDK使用
|
||
- SDK建议
|
||
- 基于统一返回体与状态码，封装HTTP客户端SDK，内置Token刷新、重试与日志追踪能力。
|
||
- 集成步骤
|
||
- 认证中心获取Token → 管理服务调用携带Authorization头 → 处理统一返回体与状态码。
|
||
|
||
### Postman集合与curl示例
|
||
- Postman集合
|
||
- 建议将接口清单（来自接口扫描与注册）导入Postman，按模块分组，设置全局变量（如Token、环境地址）。
|
||
- curl示例
|
||
- 登录获取Token：curl -X POST "{认证中心}/login" -H "Content-Type: application/json" -d '{"username":"...","password":"..."}'
|
||
- 调用受保护接口：curl -X GET "{管理服务}/api/..." -H "Authorization: {token}" |