19 KiB
19 KiB
开发指南
**本文引用的文件** - [pom.xml](file://pom.xml) - [readme.md](file://readme.md) - [lombok.config](file://lombok.config) - [nflg-wms-common/pom.xml](file://nflg-wms-common/pom.xml) - [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java) - [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java) - [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java) - [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java) - [nflg-wms-admin/pom.xml](file://nflg-wms-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-admin/src/main/resources/application.yml](file://nflg-wms-admin/src/main/resources/application.yml) - [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java) - [nflg-wms-repository/pom.xml](file://nflg-wms-repository/pom.xml) - [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java)目录
简介
本指南面向新加入的开发者，系统性介绍NFLG WMS系统的开发环境搭建、代码规范、项目结构、编码与注释规范、代码生成与模板使用、单元与集成测试策略、调试与问题定位方法、Git工作流与代码评审流程、第三方库集成与插件开发方法，并提供学习路径与常见问题解决方案。文档中的所有技术细节均以仓库现有文件为依据。
项目结构
本项目采用多模块Maven聚合工程组织，核心模块包括通用模块、基础启动器、数据访问层、网关、各业务服务（如管理后台、认证、定时任务、SRM收货、运输等），以及一个独立的QMS管理端。模块间通过公共依赖与版本管理统一约束。
- 聚合根：顶层pom.xml定义了模块清单、Java版本、编码、依赖与插件管理。
- 公共模块：nflg-wms-common 提供常量、异常、工具类与通用DTO/QO/VO等。
- 基础启动器：nflg-wms-starter 提供统一控制器基类、拦截器、切面与配置骨架。
- 数据访问层：nflg-wms-repository 封装MyBatis-Plus与数据库交互，内置代码生成器测试用例。
- 业务服务：nflg-wms-admin、nflg-wms-auth、nflg-wms-scheduled、nflg-wms-srm-receive、nflg-wms-shipment 等。
- 网关：nflg-wms-gateway。
- 独立管理端：nflg-qms-admin。
graph TB
Root["聚合根<br/>nflg-wms(pom.xml)"]
Common["公共模块<br/>nflg-wms-common"]
Starter["基础启动器<br/>nflg-wms-starter"]
Repo["数据访问层<br/>nflg-wms-repository"]
Gateway["网关<br/>nflg-wms-gateway"]
Admin["管理后台<br/>nflg-wms-admin"]
Auth["认证服务<br/>nflg-wms-auth"]
Scheduled["定时任务<br/>nflg-wms-scheduled"]
Srm["SRM收货<br/>nflg-wms-srm-receive"]
Shipment["运输模块<br/>nflg-wms-shipment"]
Qms["QMS管理端<br/>nflg-qms-admin"]
Root --> Common
Root --> Starter
Root --> Repo
Root --> Gateway
Root --> Admin
Root --> Auth
Root --> Scheduled
Root --> Srm
Root --> Shipment
Root --> Qms
Admin --> Common
Admin --> Starter
Admin --> Repo
Auth --> Common
Auth --> Starter
Scheduled --> Common
Srm --> Common
Shipment --> Common
Gateway --> Common
图表来源
章节来源
核心组件
- 通用常量与异常
- 常量集中定义在公共模块中，便于跨模块共享。
- 统一业务异常类型，配合状态码与消息返回。
- 工具类
- BeanUtil提供对象与JSON、Map之间的转换能力，封装Jackson与Hutool。
- 基础控制器
- BaseController提供二维码内容生成等通用逻辑，作为各业务Controller的父类。
章节来源
- nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43
- nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18
- nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37
- nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77
架构总览
系统基于Spring Boot 3与Spring Cloud生态，采用Nacos作为配置与注册中心，Actuator暴露监控指标，支持链路追踪与健康检查。管理后台服务负责业务编排与对外接口，数据访问层通过MyBatis-Plus与PostgreSQL交互，部分模块集成Redisson、PowerJob、Loki日志采集等。
graph TB
subgraph "客户端"
Browser["浏览器/移动端"]
end
subgraph "边缘与网关"
Gateway["Spring Cloud Gateway"]
end
subgraph "服务发现与配置"
Nacos["Nacos(配置/注册)"]
end
subgraph "业务服务"
Admin["管理后台服务"]
Auth["认证服务"]
Scheduled["定时任务服务"]
Srm["SRM收货服务"]
Shipment["运输服务"]
end
subgraph "基础设施"
DB["PostgreSQL"]
Redis["Redis"]
Loki["Loki 日志"]
Act["Spring Boot Actuator"]
end
Browser --> Gateway
Gateway --> Admin
Gateway --> Auth
Admin --> DB
Auth --> DB
Scheduled --> DB
Srm --> DB
Shipment --> DB
Admin --> Redis
Auth --> Redis
Admin --> Loki
Auth --> Loki
Admin --> Act
Auth --> Act
Admin --> Nacos
Auth --> Nacos
Scheduled --> Nacos
Srm --> Nacos
Shipment --> Nacos
图表来源
详细组件分析
通用模块（nflg-wms-common）
- 职责
- 定义系统级常量、通用异常类型、通用工具类与DTO/QO/VO集合。
- 关键点
- 常量集中管理，便于统一维护与跨模块共享。
- 异常体系以统一状态码与消息返回，便于前端与调用方处理。
- 工具类封装常用转换逻辑，降低重复代码。
classDiagram
class Constant {
+String DEFAULT_LANGUAGE_CODE
+String TRACE_ID_HEADER
+String TRACE_ID
+... 多个常量
}
class NflgException {
+STATE state
+String msg
+NflgException(state, msg)
}
class BeanUtil {
+copy(source, clazz) T
+toJson(source) String
+toBean(map, clazz) T
+toMap(source) Map
}
图表来源
- nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43
- nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18
- nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37
章节来源
- nflg-wms-common/pom.xml:1-84
- nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43
- nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18
- nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37
基础启动器（nflg-wms-starter）
- 职责
- 提供统一的控制器基类BaseController，封装通用逻辑（如二维码内容生成）。
- 关键点
- 使用Lombok简化样板代码。
- 作为其他服务的公共依赖，确保行为一致性。
classDiagram
class BaseController {
+generateQRContent(order) String
}
图表来源
章节来源
管理后台服务（nflg-wms-admin）
- 职责
- 对外提供管理后台接口，集成LDAP、邮件、PDF生成、二维码、MongoDB、SAP JCo等能力。
- 关键点
- 应用入口启用组件扫描、调度与重试。
- 配置文件启用Nacos配置导入、Actuator端点、链路追踪采样。
- 包含测试控制器，演示异常抛出与序列号生成等场景。
sequenceDiagram
participant Client as "客户端"
participant Admin as "AdminApplication"
participant Ctl as "TestController"
participant Svc as "相关服务"
Client->>Admin : 启动应用
Admin->>Admin : 组件扫描/调度/重试启用
Client->>Ctl : GET /test/add
Ctl->>Svc : 调用业务服务
Ctl-->>Client : 返回结果
Client->>Ctl : GET /test/businessError
Ctl-->>Client : 抛出业务异常
图表来源
- nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:1-27
- nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87
章节来源
- nflg-wms-admin/pom.xml:1-281
- nflg-wms-admin/src/main/resources/application.yml:1-48
- nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:1-27
- nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87
数据访问层（nflg-wms-repository）
- 职责
- 封装数据库访问，基于MyBatis-Plus与PostgreSQL，提供实体、Mapper、Service生成模板与测试。
- 关键点
- 内置代码生成器测试用例，演示如何生成Entity、Mapper、Service与XML。
- 支持Freemarker模板引擎与Lombok链式模型。
flowchart TD
Start(["执行代码生成测试"]) --> JDBC["连接PostgreSQL"]
JDBC --> Include["选择表集"]
Include --> Builder["配置实体/包结构/模板引擎"]
Builder --> Override["启用覆盖/链式模型/Lombok"]
Override --> Execute["执行生成"]
Execute --> End(["生成完成"])
图表来源
章节来源
- nflg-wms-repository/pom.xml:1-76
- nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46
依赖分析
- 版本与依赖管理
- 顶层pom集中管理Spring Boot、Spring Cloud、Spring Cloud Alibaba、MyBatis-Plus、Sa-Token、PostgreSQL、MinIO、Loki、Redisson、PowerJob、ZXing等版本。
- 模块依赖
- 管理后台依赖公共模块、启动器与Web、LDAP、邮件、PDF、MongoDB、EasyExcel、Redisson、Actuator、OpenTelemetry等。
- 数据访问层依赖公共模块与MyBatis-Plus、PostgreSQL、Redisson、测试依赖。
graph LR
POM["顶层pom.xml"]
Common["nflg-wms-common"]
Starter["nflg-wms-starter"]
Repo["nflg-wms-repository"]
Admin["nflg-wms-admin"]
Auth["nflg-wms-auth"]
Gateway["nflg-wms-gateway"]
POM --> Common
POM --> Starter
POM --> Repo
POM --> Admin
POM --> Auth
POM --> Gateway
Admin --> Common
Admin --> Starter
Admin --> Repo
图表来源
章节来源
性能考虑
- 链路追踪与指标
- 启用Actuator与OpenTelemetry导出，建议在生产环境合理设置采样率，避免高噪声。
- 缓存与分布式锁
- Redisson提供分布式能力，建议对热点查询与并发写入场景进行缓存与互斥控制。
- 数据库与分页
- MyBatis-Plus分页与SQL解析器提升查询效率，建议结合索引与查询条件优化。
- 日志与可观测性
- Loki日志采集用于集中化日志检索，建议按环境配置日志级别与过滤规则。
故障排查指南
- 异常处理
- 统一使用NflgException返回业务状态与消息，便于前端与调用方识别与处理。
- 日志分析
- 应用日志与Loki结合，按traceId快速定位请求链路。
- 常见问题
- PDF生成与标签打印依赖wkhtmltoimage，需按readme安装对应依赖。
- SAP JCo依赖需放置在指定目录，确保运行时可加载。
章节来源
结论
本指南从环境搭建、项目结构、编码规范、代码生成、测试策略、调试与运维到Git工作流与第三方集成进行了系统阐述。建议新开发者先从公共模块与启动器入手，理解通用常量、异常与工具类的使用方式，再逐步深入到具体业务模块与数据访问层。
附录
开发环境搭建与IDE配置
- JDK与Maven
- Java版本：17；Maven版本：3.6+。
- IDE推荐
- IntelliJ IDEA：启用Lombok插件与Annotation Processing；配置Maven自动导入与编译器参数。
- 依赖安装
- 按readme安装wkhtmltoimage，满足PDF与标签打印需求。
- Nacos与数据库
- 确保Nacos地址与命名空间配置正确；数据库使用PostgreSQL，账号密码在代码生成测试中可见。
章节来源
代码规范与注释规范
- 包命名约定
- 采用反向域名+模块+子域的层级结构，如com.nflg.wms.admin.controller。
- 类设计原则
- 使用Lombok减少样板代码；异常类统一继承NflgException；工具类集中于common模块。
- 注释规范
- 控制器与方法添加简要注释，说明用途与关键参数；复杂逻辑补充流程说明。
章节来源
- nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18
- nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77
代码生成与模板使用
- 生成范围
- 通过代码生成器测试用例选择表集，生成Entity、Mapper、Service与XML。
- 模板引擎
- 使用Freemarker模板引擎，支持链式模型与Lombok注解。
- 输出位置
- 实体、Mapper、Service与XML分别输出到指定包路径，便于后续扩展。
章节来源
单元测试与集成测试策略
- 测试框架
- 使用JUnit Jupiter；Surefire插件配置包含所有测试类。
- 测试覆盖率
- 建议在CI中引入JaCoCo或类似工具统计覆盖率，目标不低于80%。
- 集成测试
- 通过Deploy*Test类在不同环境（dev/sit/prod）验证部署与配置。
章节来源
调试技巧与问题定位
- 日志
- 使用SLF4J与Loki日志采集，按环境调整日志级别；结合traceId快速定位。
- 性能分析
- 启用Actuator与OpenTelemetry，导出指标与链路数据，定位慢调用与异常。
- 常见问题
- PDF生成失败：确认wkhtmltoimage安装与路径；SAP JCo报错：检查JAR路径与权限。
章节来源
Git工作流与代码审查流程
- 分支管理
- 主干：main（受保护）；特性分支：feature/；修复分支：fix/；发布分支：release/*。
- 提交规范
- 类型：feat/fix/docs/style/refactor/test/build/ci；格式：type(scope): subject。
- 代码审查
- PR需至少一名Reviewer通过；合并前确保通过CI与测试。
第三方库集成指南与插件开发方法
- 常用库
- Sa-Token：认证与会话；MyBatis-Plus：ORM；Redisson：分布式能力；PowerJob：定时任务；Loki：日志采集；OpenTelemetry：链路追踪。
- 插件开发
- 在starter模块扩展通用能力（如拦截器、切面、注解），由各业务模块复用。
章节来源
学习路径与技能要求
- 必备技能
- Java 17、Spring Boot/Spring Cloud、MyBatis-Plus、PostgreSQL、Nacos、Docker/Kubernetes（可选）。
- 进阶方向
- 链路追踪与可观测性、分布式缓存与限流、安全与认证、自动化测试与CI/CD。
常见开发问题与最佳实践
- 问题：PDF生成失败
- 解决：安装wkhtmltoimage并确保系统可用。
- 问题：SAP JCo无法加载
- 解决：将JAR放入lib目录并在构建阶段复制到输出目录。
- 最佳实践：统一异常处理、日志分级、参数校验、幂等与重试策略。
章节来源