401 lines
16 KiB
Markdown
401 lines
16 KiB
Markdown
# 系统架构
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [pom.xml](file://pom.xml)
|
||
- [readme.md](file://readme.md)
|
||
- [nflg-wms-admin/pom.xml](file://nflg-wms-admin/pom.xml)
|
||
- [nflg-wms-auth/pom.xml](file://nflg-wms-auth/pom.xml)
|
||
- [nflg-wms-gateway/pom.xml](file://nflg-wms-gateway/pom.xml)
|
||
- [nflg-wms-repository/pom.xml](file://nflg-wms-repository/pom.xml)
|
||
- [nflg-wms-scheduled/pom.xml](file://nflg-wms-scheduled/pom.xml)
|
||
- [nflg-wms-srm-receive/pom.xml](file://nflg-wms-srm-receive/pom.xml)
|
||
- [nflg-wms-shipment/pom.xml](file://nflg-wms-shipment/pom.xml)
|
||
- [nflg-qms-admin/pom.xml](file://nflg-qms-admin/pom.xml)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
|
||
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java)
|
||
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java)
|
||
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本架构文档面向架构师与高级开发者，系统化阐述NFLG WMS（仓库管理系统）在Spring Cloud生态下的微服务架构设计。该系统采用多模块聚合工程，围绕“网关层-业务服务层-基础设施层”进行服务拆分与职责划分，结合Nacos注册与配置中心、Sa-Token统一认证、MyBatis-Plus数据访问、Redisson缓存与分布式能力、OpenTelemetry链路追踪、PowerJob计划任务等技术栈，实现高可用、可扩展、可观测的仓储业务支撑平台。
|
||
|
||
## 项目结构
|
||
系统以Maven聚合工程组织，父POM统一管理版本与依赖，子模块按功能域拆分，形成清晰的模块边界与复用层：
|
||
|
||
- 核心公共层
|
||
- nflg-wms-common：通用常量、异常、DTO/QO/VO、工具类
|
||
- nflg-wms-starter：全局切面、拦截器、统一响应包装、基础配置
|
||
- 基础设施层
|
||
- nflg-wms-repository：数据库访问抽象与MyBatis-Plus集成
|
||
- nflg-wms-gateway：Spring Cloud Gateway网关与鉴权路由
|
||
- 业务服务层
|
||
- nflg-wms-admin：WMS管理后台（含打印、报表、SAP对接）
|
||
- nflg-wms-auth：统一认证中心（SSO）
|
||
- nflg-wms-srm-receive：SRM订单接收服务
|
||
- nflg-wms-shipment：发货相关业务
|
||
- nflg-qms-admin：QMS质量管理后台
|
||
- nflg-wms-scheduled：计划任务执行器（PowerJob Worker）
|
||
- 其他
|
||
- readme.md：环境依赖说明（如wkhtmltoimage）
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "聚合工程"
|
||
ROOT["父POM<br/>统一版本与依赖管理"]
|
||
end
|
||
subgraph "公共与基础设施"
|
||
COMMON["nflg-wms-common"]
|
||
STARTER["nflg-wms-starter"]
|
||
REPO["nflg-wms-repository"]
|
||
GATEWAY["nflg-wms-gateway"]
|
||
end
|
||
subgraph "业务服务"
|
||
ADMIN["nflg-wms-admin"]
|
||
AUTH["nflg-wms-auth"]
|
||
SRM["nflg-wms-srm-receive"]
|
||
SHIPMENT["nflg-wms-shipment"]
|
||
QMS["nflg-qms-admin"]
|
||
SCHEDULED["nflg-wms-scheduled"]
|
||
end
|
||
ROOT --> COMMON
|
||
ROOT --> STARTER
|
||
ROOT --> REPO
|
||
ROOT --> GATEWAY
|
||
ROOT --> ADMIN
|
||
ROOT --> AUTH
|
||
ROOT --> SRM
|
||
ROOT --> SHIPMENT
|
||
ROOT --> QMS
|
||
ROOT --> SCHEDULED
|
||
ADMIN --> COMMON
|
||
ADMIN --> STARTER
|
||
ADMIN --> REPO
|
||
AUTH --> COMMON
|
||
AUTH --> STARTER
|
||
GATEWAY --> COMMON
|
||
GATEWAY --> REPO
|
||
SRM --> STARTER
|
||
SHIPMENT --> COMMON
|
||
SHIPMENT --> STARTER
|
||
QMS --> COMMON
|
||
QMS --> STARTER
|
||
SCHEDULED --> COMMON
|
||
SCHEDULED --> STARTER
|
||
```
|
||
|
||
**图表来源**
|
||
- [pom.xml:17-28](file://pom.xml#L17-L28)
|
||
- [nflg-wms-admin/pom.xml:14-22](file://nflg-wms-admin/pom.xml#L14-L22)
|
||
- [nflg-wms-auth/pom.xml:15-23](file://nflg-wms-auth/pom.xml#L15-L23)
|
||
- [nflg-wms-gateway/pom.xml:15-27](file://nflg-wms-gateway/pom.xml#L15-L27)
|
||
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)
|
||
- [nflg-wms-srm-receive/pom.xml:15-19](file://nflg-wms-srm-receive/pom.xml#L15-L19)
|
||
- [nflg-wms-shipment/pom.xml:14-22](file://nflg-wms-shipment/pom.xml#L14-L22)
|
||
- [nflg-qms-admin/pom.xml:17-25](file://nflg-qms-admin/pom.xml#L17-L25)
|
||
- [nflg-wms-scheduled/pom.xml:14-22](file://nflg-wms-scheduled/pom.xml#L14-L22)
|
||
|
||
**章节来源**
|
||
- [pom.xml:17-28](file://pom.xml#L17-L28)
|
||
- [readme.md:1-10](file://readme.md#L1-L10)
|
||
|
||
## 核心组件
|
||
- 父POM与版本治理
|
||
- Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0
|
||
- MyBatis-Plus 3.5.12、Sa-Token 1.42.0、Redisson 3.52.0、PowerJob 5.1.1、OpenTelemetry等
|
||
- 应用入口与发现
|
||
- 各服务通过@EnableDiscoveryClient启用服务注册与发现
|
||
- 网关、管理后台、认证中心分别暴露HTTP端口，计划任务服务以非Web方式运行
|
||
|
||
**章节来源**
|
||
- [pom.xml:29-53](file://pom.xml#L29-L53)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
|
||
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
|
||
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:9-13](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L9-L13)
|
||
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java:10-17](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java#L10-L17)
|
||
|
||
## 架构总览
|
||
系统采用“网关+服务网格”的微服务体系，客户端请求经由网关统一接入，网关负责路由、鉴权与限流；业务服务通过Nacos完成注册与配置下发；认证中心提供SSO统一认证；数据访问层通过Repository模块与MyBatis-Plus对接PostgreSQL；计划任务通过PowerJob Worker异步执行；日志与链路追踪通过Loki与OpenTelemetry集成。
|
||
|
||
```mermaid
|
||
graph TB
|
||
CLIENT["客户端/前端"]
|
||
GW["Spring Cloud Gateway<br/>路由/鉴权/限流"]
|
||
REG["Nacos 注册与配置中心"]
|
||
AUTH["认证中心(nflg-wms-auth)<br/>SSO"]
|
||
ADMIN["管理后台(nflg-wms-admin)"]
|
||
SRM["SRM接收(nflg-wms-srm-receive)"]
|
||
SHIP["发货(nflg-wms-shipment)"]
|
||
QMS["QMS管理(nflg-qms-admin)"]
|
||
SCHED["计划任务(nflg-wms-scheduled)"]
|
||
DB["PostgreSQL 数据库"]
|
||
REDIS["Redis 缓存/分布式锁"]
|
||
LOG["Loki 日志"]
|
||
TRACE["OpenTelemetry 链路追踪"]
|
||
CLIENT --> GW
|
||
GW --> REG
|
||
GW --> AUTH
|
||
GW --> ADMIN
|
||
GW --> SRM
|
||
GW --> SHIP
|
||
GW --> QMS
|
||
GW --> SCHED
|
||
ADMIN --> DB
|
||
ADMIN --> REDIS
|
||
SRM --> DB
|
||
SRM --> REDIS
|
||
SHIP --> DB
|
||
SHIP --> REDIS
|
||
QMS --> DB
|
||
QMS --> REDIS
|
||
SCHED --> DB
|
||
SCHED --> REDIS
|
||
ADMIN -.日志/链路.-> LOG
|
||
ADMIN -.日志/链路.-> TRACE
|
||
AUTH -.日志/链路.-> LOG
|
||
AUTH -.日志/链路.-> TRACE
|
||
GW -.日志/链路.-> LOG
|
||
GW -.日志/链路.-> TRACE
|
||
```
|
||
|
||
**图表来源**
|
||
- [nflg-wms-gateway/pom.xml:29-49](file://nflg-wms-gateway/pom.xml#L29-L49)
|
||
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
|
||
- [nflg-wms-srm-receive/pom.xml:15-19](file://nflg-wms-srm-receive/pom.xml#L15-L19)
|
||
- [nflg-wms-shipment/pom.xml:14-22](file://nflg-wms-shipment/pom.xml#L14-L22)
|
||
- [nflg-qms-admin/pom.xml:17-25](file://nflg-qms-admin/pom.xml#L17-L25)
|
||
- [nflg-wms-scheduled/pom.xml:14-22](file://nflg-wms-scheduled/pom.xml#L14-L22)
|
||
- [nflg-wms-repository/pom.xml:23-26](file://nflg-wms-repository/pom.xml#L23-L26)
|
||
|
||
## 详细组件分析
|
||
|
||
### 网关服务（nflg-wms-gateway）
|
||
- 职责
|
||
- 作为统一入口，聚合路由规则，对接Nacos注册中心与配置中心
|
||
- 集成Sa-Token鉴权能力，支持SSO与令牌校验
|
||
- 提供负载均衡与限流策略
|
||
- 技术要点
|
||
- spring-cloud-starter-gateway、spring-cloud-starter-loadbalancer
|
||
- Sa-Token Reactor Starter、Redis Jackson
|
||
- Actuator、Loki Logback、Redisson Starter
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class GateWayApplication {
|
||
+main(args)
|
||
}
|
||
class GatewayRoutes {
|
||
+routeToAdmin()
|
||
+routeToAuth()
|
||
+routeToSrm()
|
||
+routeToShipment()
|
||
+routeToQms()
|
||
+routeToScheduled()
|
||
}
|
||
GateWayApplication --> GatewayRoutes : "加载路由规则"
|
||
```
|
||
|
||
**图表来源**
|
||
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:10-13](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L10-L13)
|
||
- [nflg-wms-gateway/pom.xml:29-49](file://nflg-wms-gateway/pom.xml#L29-L49)
|
||
|
||
**章节来源**
|
||
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)
|
||
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:9-18](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L9-L18)
|
||
|
||
### 认证服务（nflg-wms-auth）
|
||
- 职责
|
||
- 提供SSO认证中心，统一发放与校验令牌
|
||
- 对接LDAP/用户体系，支持角色权限模型
|
||
- 技术要点
|
||
- Sa-Token Server/JWT/Jackson
|
||
- Redisson、Actuator、Loki、JSch测试依赖
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant GW as "网关"
|
||
participant AUTH as "认证中心"
|
||
participant SVC as "业务服务"
|
||
C->>GW : 请求受保护资源
|
||
GW->>AUTH : 校验令牌/跳转SSO
|
||
AUTH-->>GW : 返回认证结果
|
||
GW->>SVC : 转发带令牌请求
|
||
SVC-->>GW : 返回业务响应
|
||
GW-->>C : 返回最终响应
|
||
```
|
||
|
||
**图表来源**
|
||
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
|
||
- [nflg-wms-gateway/pom.xml:55-61](file://nflg-wms-gateway/pom.xml#L55-L61)
|
||
|
||
**章节来源**
|
||
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)
|
||
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-21](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L21)
|
||
|
||
### 管理后台（nflg-wms-admin）
|
||
- 职责
|
||
- 提供WMS管理界面与接口，覆盖入库、出库、移库、盘点、打印、报表等功能
|
||
- 集成SAP JCo、PDF/二维码/Excel处理能力
|
||
- 技术要点
|
||
- Spring Web、LDAP、Mail、Thymeleaf、iText7、Flying Saucer、EasyExcel、Retry、AOP、Validation、Redisson、Actuator、Loki、OpenTelemetry TSID
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["请求进入"]) --> Validate["参数校验/权限检查"]
|
||
Validate --> Biz["业务处理仓储作业"]
|
||
Biz --> Repo["Repository持久化"]
|
||
Repo --> SAP["SAP JCo同步可选"]
|
||
SAP --> Resp["返回结果"]
|
||
Repo --> Resp
|
||
Validate --> |失败| Err["异常/错误响应"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
|
||
|
||
**章节来源**
|
||
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
|
||
|
||
### SRM接收服务（nflg-wms-srm-receive）
|
||
- 职责
|
||
- 接收SRM订单并落库，触发后续质检/收货流程
|
||
- 技术要点
|
||
- Spring Web、Actuator、Redisson、SAP JCo
|
||
|
||
**章节来源**
|
||
- [nflg-wms-srm-receive/pom.xml:15-62](file://nflg-wms-srm-receive/pom.xml#L15-L62)
|
||
|
||
### 发货服务（nflg-wms-shipment）
|
||
- 职责
|
||
- 处理发货相关的包装、装车、出库、单据打印等流程
|
||
- 技术要点
|
||
- Spring Web、PDF/二维码/Excel、Validation、Redisson、Actuator、OpenTelemetry
|
||
|
||
**章节来源**
|
||
- [nflg-wms-shipment/pom.xml:14-138](file://nflg-wms-shipment/pom.xml#L14-L138)
|
||
|
||
### QMS管理后台（nflg-qms-admin）
|
||
- 职责
|
||
- 质量管理相关后台能力，与WMS管理后台类似，但聚焦质量域
|
||
- 技术要点
|
||
- Spring Web、LDAP、Mail、Thymeleaf、MongoDB、EasyExcel、Retry、AOP、Validation、Redisson、Actuator、Loki、OpenTelemetry
|
||
|
||
**章节来源**
|
||
- [nflg-qms-admin/pom.xml:17-185](file://nflg-qms-admin/pom.xml#L17-L185)
|
||
|
||
### 计划任务服务（nflg-wms-scheduled）
|
||
- 职责
|
||
- 作为PowerJob Worker，执行周期性或调度性任务（如SAP同步）
|
||
- 运行方式
|
||
- 以非Web方式启动，仅加载上下文与任务执行器
|
||
- 技术要点
|
||
- PowerJob Worker、SAP JCo、Redisson、Actuator、LDAP、JUnit、JSch
|
||
|
||
**章节来源**
|
||
- [nflg-wms-scheduled/pom.xml:14-61](file://nflg-wms-scheduled/pom.xml#L14-L61)
|
||
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java:10-17](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java#L10-L17)
|
||
|
||
### 数据访问层（nflg-wms-repository）
|
||
- 职责
|
||
- 封装数据库访问，提供MyBatis-Plus基础能力与重试策略
|
||
- 技术要点
|
||
- PostgreSQL、MyBatis-Plus、JSQLParser、Spring Retry、Redisson
|
||
|
||
**章节来源**
|
||
- [nflg-wms-repository/pom.xml:14-64](file://nflg-wms-repository/pom.xml#L14-L64)
|
||
|
||
## 依赖关系分析
|
||
- 版本治理
|
||
- 父POM集中声明Spring Boot、Spring Cloud、Spring Cloud Alibaba、MyBatis-Plus、Sa-Token、Redisson、PowerJob、OpenTelemetry等版本
|
||
- 模块依赖
|
||
- 业务服务均依赖common与starter，部分依赖repository
|
||
- 网关依赖common与repository，并引入gateway、nacos、sa-token等
|
||
- 计划任务依赖starter与repository，使用PowerJob Worker
|
||
- 外部依赖
|
||
- 数据库：PostgreSQL
|
||
- 缓存/分布式：Redisson
|
||
- 认证：Sa-Token（Server/Client/JWT/Jackson）
|
||
- 日志：Loki Logback Appender
|
||
- 链路追踪：Micrometer Tracing Bridge OTel、OTLP Exporter、SDK Extension Autoconfigure
|
||
- 打印与报表：wkhtmltoimage（环境依赖）
|
||
|
||
```mermaid
|
||
graph LR
|
||
POM["父POM版本管理"]
|
||
BOOT["Spring Boot 3.2.4"]
|
||
CLOUD["Spring Cloud 2023.0.1"]
|
||
ALIBABA["Spring Cloud Alibaba 2023.0.1.0"]
|
||
MP["MyBatis-Plus 3.5.12"]
|
||
ST["Sa-Token 1.42.0"]
|
||
RS["Redisson 3.52.0"]
|
||
PJ["PowerJob 5.1.1"]
|
||
OT["OpenTelemetry"]
|
||
POM --> BOOT
|
||
POM --> CLOUD
|
||
POM --> ALIBABA
|
||
POM --> MP
|
||
POM --> ST
|
||
POM --> RS
|
||
POM --> PJ
|
||
POM --> OT
|
||
```
|
||
|
||
**图表来源**
|
||
- [pom.xml:54-192](file://pom.xml#L54-L192)
|
||
|
||
**章节来源**
|
||
- [pom.xml:54-192](file://pom.xml#L54-L192)
|
||
|
||
## 性能考量
|
||
- 并发与限流
|
||
- 网关侧建议结合限流与熔断策略，避免热点服务过载
|
||
- 缓存与热点
|
||
- 使用Redisson进行热点数据缓存与分布式锁，降低数据库压力
|
||
- 数据库优化
|
||
- MyBatis-Plus分页与JSQLParser动态SQL，配合索引与慢查询监控
|
||
- 链路追踪
|
||
- OpenTelemetry采集指标与链路，定位瓶颈与异常
|
||
- 打印与报表
|
||
- wkhtmltoimage需在服务器侧部署，避免阻塞主线程；可异步化打印任务
|
||
|
||
## 故障排查指南
|
||
- 认证问题
|
||
- 检查认证中心SSO配置与令牌签发；确认网关路由是否正确转发至认证中心
|
||
- 网关路由
|
||
- 核对Nacos路由配置，确保服务名与实例健康状态
|
||
- 数据库连接
|
||
- 检查PostgreSQL连接参数与驱动版本，关注连接池配置
|
||
- 日志与链路
|
||
- Loki日志采集与OpenTelemetry链路导出是否正常
|
||
- 计划任务
|
||
- PowerJob Worker是否在线，任务执行日志与重试策略是否合理
|
||
|
||
**章节来源**
|
||
- [nflg-wms-gateway/pom.xml:76-94](file://nflg-wms-gateway/pom.xml#L76-L94)
|
||
- [nflg-wms-repository/pom.xml:23-26](file://nflg-wms-repository/pom.xml#L23-L26)
|
||
- [nflg-wms-scheduled/pom.xml:30-48](file://nflg-wms-scheduled/pom.xml#L30-L48)
|
||
|
||
## 结论
|
||
本系统通过Spring Cloud与多模块架构实现了清晰的服务边界与职责分离，结合统一认证、网关路由、数据库抽象与分布式能力，构建了可扩展、可观测的WMS平台。建议在生产环境中完善灰度发布、容量评估与灾备演练，持续优化链路与缓存策略，保障高并发与高可用。
|
||
|
||
## 附录
|
||
- 环境依赖
|
||
- 需安装wkhtmltoimage以支持HTML转图片与标签打印
|
||
|
||
**章节来源**
|
||
- [readme.md:1-10](file://readme.md#L1-L10) |