wms/.qoder/repowiki/zh/content/API接口文档/API接口文档.md

API接口文档

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

目录

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

简介

本文件为NFLG WMS系统的完整API接口文档，覆盖仓储管理、物料管理、订单处理等业务域的RESTful接口设计与规范。文档基于仓库中的Spring Boot微服务架构与统一返回体、状态码体系进行整理，并结合注解标记与测试用例对接口进行梳理与归档。同时提供认证与授权机制说明、错误处理策略、版本与兼容性建议、客户端集成与SDK使用指引，以及Postman集合与curl示例的准备思路。

项目结构

系统采用多模块聚合工程，核心模块包括：

• 公共模块：统一返回体、常量、异常与工具
• 启动器模块：基础控制器基类、通用注解
• 认证模块：统一认证中心（SSO）
• 管理模块：业务管理端服务
• 仓储模块：接口清单持久化与查询
• 网关与定时任务等其他模块

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
• AdminApplication.java:12-18
• AuthApplication.java:10-14

章节来源

• pom.xml（根）:17-28
• application.yml（admin）:1-48
• application.yml（auth）:1-50

核心组件

• 统一返回体与状态码
  • 统一返回体封装了响应码、类型、消息、时间戳、追踪ID与结果数据；支持分页转换与多种错误构造方式。
  • 状态枚举覆盖系统错误、成功、参数错误、权限拒绝、业务异常、请求方式错误、库存不足等场景。
• 基础控制器
  • 提供二维码内容生成等通用能力，便于各业务控制器复用。
• 注解与接口清单
  • 使用自定义注解标记接口模块与名称，并通过测试用例扫描注册到接口清单表中，形成可维护的接口目录。

章节来源

• ApiResult.java:16-121
• STATE.java:6-36
• BaseController.java:17-77
• ApiMark.java:8-17
• ApiStorageTest.java:28-65
• ApiServiceImpl.java:24-38

架构总览

系统采用Spring Cloud微服务架构，认证中心提供统一SSO认证，管理服务承载业务接口，公共模块提供统一返回与常量，启动器模块提供基础能力与注解，仓储模块用于接口清单的持久化与查询。

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
• AuthApplication.java:10-14
• application.yml（admin）:1-48
• application.yml（auth）:1-50

详细组件分析

认证与授权机制

• Token与SSO
  • 认证中心通过Sa-Token提供SSO能力，默认Token名称为authorization，超时时间为2592000秒（30天），Ticket超时为300秒。
  • 客户端在访问受保护资源时，应在请求头携带authorization字段。
• 登录扩展信息
  • 登录时会附加用户名、工号、邮箱、部门ID、角色、用户类型等扩展信息，便于前端与后端进行权限控制与个性化展示。
• 权限验证
  • 业务接口应结合角色与菜单按钮权限进行校验，具体策略由各业务模块在控制器中实现。

章节来源

• application.yml（auth）:20-34
• Constant.java:11-22

错误处理与统一返回体

• 统一返回体字段
  • 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
• STATE.java:6-36

接口命名与模块化

• 接口命名规范
  • 使用@ApiMark注解标注接口模块名与接口名，并声明是否公开接口。
• 接口清单管理
  • 通过测试用例扫描所有带@ApiMark的方法，自动注册或更新接口清单，便于统一管理与文档化。

章节来源

• ApiMark.java:8-17
• ApiStorageTest.java:28-65
• ApiServiceImpl.java:24-38

二维码打印与内容生成

• 通用二维码内容生成
  • 基础控制器提供二维码内容生成方法，便于在打印、扫码等环节复用。

章节来源

• BaseController.java:30-37

依赖分析

• 模块间依赖
  • 管理服务与认证中心均依赖公共模块与启动器模块，确保统一的返回体、常量与注解能力。
  • 接口清单服务依赖公共模块的VO与实体，用于接口目录的分组与查询。
• 外部依赖
  • Sa-Token用于SSO与JWT，Actuator用于健康检查与监控，Nacos用于配置与服务发现。

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
• AuthApplication.java:10-14
• ApiServiceImpl.java:24-38

章节来源

• pom.xml（根）:54-192

性能考虑

• 并发与重试
  • 管理服务启用重试与调度，有助于提升部分业务的可用性与稳定性。
• 监控与追踪
  • Actuator开启健康检查与Redis数据库健康探测，支持链路追踪与采样概率设置。
• 文件上传
  • 管理服务配置了较大的文件与请求大小限制，满足大文件导入导出场景。

章节来源

• AdminApplication.java:16-18
• application.yml（admin）:24-27
• application.yml（admin）:31-48

故障排查指南

• 常见错误码定位
  • 参数错误、业务异常、权限不足、请求方式错误、SAP错误、库存不足等，均可通过统一返回体中的code与message快速定位。
• 追踪ID
  • 返回体包含traceId，可用于日志检索与问题定位。
• 登录与SSO
  • 若出现“用户校验失败”或“请重新登录”，检查authorization头与Token有效性；确认认证中心配置与回调地址。

章节来源

• ApiResult.java:16-24
• STATE.java:6-36
• application.yml（auth）:20-34

结论

本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}"