435 lines
19 KiB
Markdown
435 lines
19 KiB
Markdown
# 开发指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本指南面向新加入的开发者，系统性介绍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。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml:17-27](file://pom.xml#L17-L27)
|
||
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
|
||
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)
|
||
|
||
章节来源
|
||
- [pom.xml:1-260](file://pom.xml#L1-L260)
|
||
|
||
## 核心组件
|
||
- 通用常量与异常
|
||
- 常量集中定义在公共模块中，便于跨模块共享。
|
||
- 统一业务异常类型，配合状态码与消息返回。
|
||
- 工具类
|
||
- BeanUtil提供对象与JSON、Map之间的转换能力，封装Jackson与Hutool。
|
||
- 基础控制器
|
||
- BaseController提供二维码内容生成等通用逻辑，作为各业务Controller的父类。
|
||
|
||
章节来源
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)
|
||
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)
|
||
|
||
## 架构总览
|
||
系统基于Spring Boot 3与Spring Cloud生态，采用Nacos作为配置与注册中心，Actuator暴露监控指标，支持链路追踪与健康检查。管理后台服务负责业务编排与对外接口，数据访问层通过MyBatis-Plus与PostgreSQL交互，部分模块集成Redisson、PowerJob、Loki日志采集等。
|
||
|
||
```mermaid
|
||
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-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
|
||
- [pom.xml:54-193](file://pom.xml#L54-L193)
|
||
|
||
## 详细组件分析
|
||
|
||
### 通用模块（nflg-wms-common）
|
||
- 职责
|
||
- 定义系统级常量、通用异常类型、通用工具类与DTO/QO/VO集合。
|
||
- 关键点
|
||
- 常量集中管理，便于统一维护与跨模块共享。
|
||
- 异常体系以统一状态码与消息返回，便于前端与调用方处理。
|
||
- 工具类封装常用转换逻辑，降低重复代码。
|
||
|
||
```mermaid
|
||
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](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)
|
||
|
||
章节来源
|
||
- [nflg-wms-common/pom.xml:1-84](file://nflg-wms-common/pom.xml#L1-L84)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)
|
||
|
||
### 基础启动器（nflg-wms-starter）
|
||
- 职责
|
||
- 提供统一的控制器基类BaseController，封装通用逻辑（如二维码内容生成）。
|
||
- 关键点
|
||
- 使用Lombok简化样板代码。
|
||
- 作为其他服务的公共依赖，确保行为一致性。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class BaseController {
|
||
+generateQRContent(order) String
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)
|
||
|
||
章节来源
|
||
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)
|
||
|
||
### 管理后台服务（nflg-wms-admin）
|
||
- 职责
|
||
- 对外提供管理后台接口，集成LDAP、邮件、PDF生成、二维码、MongoDB、SAP JCo等能力。
|
||
- 关键点
|
||
- 应用入口启用组件扫描、调度与重试。
|
||
- 配置文件启用Nacos配置导入、Actuator端点、链路追踪采样。
|
||
- 包含测试控制器，演示异常抛出与序列号生成等场景。
|
||
|
||
```mermaid
|
||
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](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java#L1-L87)
|
||
|
||
章节来源
|
||
- [nflg-wms-admin/pom.xml:1-281](file://nflg-wms-admin/pom.xml#L1-L281)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java#L1-L87)
|
||
|
||
### 数据访问层（nflg-wms-repository）
|
||
- 职责
|
||
- 封装数据库访问，基于MyBatis-Plus与PostgreSQL，提供实体、Mapper、Service生成模板与测试。
|
||
- 关键点
|
||
- 内置代码生成器测试用例，演示如何生成Entity、Mapper、Service与XML。
|
||
- 支持Freemarker模板引擎与Lombok链式模型。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["执行代码生成测试"]) --> JDBC["连接PostgreSQL"]
|
||
JDBC --> Include["选择表集"]
|
||
Include --> Builder["配置实体/包结构/模板引擎"]
|
||
Builder --> Override["启用覆盖/链式模型/Lombok"]
|
||
Override --> Execute["执行生成"]
|
||
Execute --> End(["生成完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)
|
||
|
||
章节来源
|
||
- [nflg-wms-repository/pom.xml:1-76](file://nflg-wms-repository/pom.xml#L1-L76)
|
||
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)
|
||
|
||
## 依赖分析
|
||
- 版本与依赖管理
|
||
- 顶层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、测试依赖。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml:54-193](file://pom.xml#L54-L193)
|
||
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
|
||
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)
|
||
|
||
章节来源
|
||
- [pom.xml:1-260](file://pom.xml#L1-L260)
|
||
- [nflg-wms-admin/pom.xml:1-281](file://nflg-wms-admin/pom.xml#L1-L281)
|
||
- [nflg-wms-repository/pom.xml:1-76](file://nflg-wms-repository/pom.xml#L1-L76)
|
||
|
||
## 性能考虑
|
||
- 链路追踪与指标
|
||
- 启用Actuator与OpenTelemetry导出，建议在生产环境合理设置采样率，避免高噪声。
|
||
- 缓存与分布式锁
|
||
- Redisson提供分布式能力，建议对热点查询与并发写入场景进行缓存与互斥控制。
|
||
- 数据库与分页
|
||
- MyBatis-Plus分页与SQL解析器提升查询效率，建议结合索引与查询条件优化。
|
||
- 日志与可观测性
|
||
- Loki日志采集用于集中化日志检索，建议按环境配置日志级别与过滤规则。
|
||
|
||
## 故障排查指南
|
||
- 异常处理
|
||
- 统一使用NflgException返回业务状态与消息，便于前端与调用方识别与处理。
|
||
- 日志分析
|
||
- 应用日志与Loki结合，按traceId快速定位请求链路。
|
||
- 常见问题
|
||
- PDF生成与标签打印依赖wkhtmltoimage，需按readme安装对应依赖。
|
||
- SAP JCo依赖需放置在指定目录，确保运行时可加载。
|
||
|
||
章节来源
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
|
||
- [readme.md:1-10](file://readme.md#L1-L10)
|
||
|
||
## 结论
|
||
本指南从环境搭建、项目结构、编码规范、代码生成、测试策略、调试与运维到Git工作流与第三方集成进行了系统阐述。建议新开发者先从公共模块与启动器入手，理解通用常量、异常与工具类的使用方式，再逐步深入到具体业务模块与数据访问层。
|
||
|
||
## 附录
|
||
|
||
### 开发环境搭建与IDE配置
|
||
- JDK与Maven
|
||
- Java版本：17；Maven版本：3.6+。
|
||
- IDE推荐
|
||
- IntelliJ IDEA：启用Lombok插件与Annotation Processing；配置Maven自动导入与编译器参数。
|
||
- 依赖安装
|
||
- 按readme安装wkhtmltoimage，满足PDF与标签打印需求。
|
||
- Nacos与数据库
|
||
- 确保Nacos地址与命名空间配置正确；数据库使用PostgreSQL，账号密码在代码生成测试中可见。
|
||
|
||
章节来源
|
||
- [pom.xml:29-35](file://pom.xml#L29-L35)
|
||
- [readme.md:1-10](file://readme.md#L1-L10)
|
||
|
||
### 代码规范与注释规范
|
||
- 包命名约定
|
||
- 采用反向域名+模块+子域的层级结构，如com.nflg.wms.admin.controller。
|
||
- 类设计原则
|
||
- 使用Lombok减少样板代码；异常类统一继承NflgException；工具类集中于common模块。
|
||
- 注释规范
|
||
- 控制器与方法添加简要注释，说明用途与关键参数；复杂逻辑补充流程说明。
|
||
|
||
章节来源
|
||
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
|
||
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)
|
||
|
||
### 代码生成与模板使用
|
||
- 生成范围
|
||
- 通过代码生成器测试用例选择表集，生成Entity、Mapper、Service与XML。
|
||
- 模板引擎
|
||
- 使用Freemarker模板引擎，支持链式模型与Lombok注解。
|
||
- 输出位置
|
||
- 实体、Mapper、Service与XML分别输出到指定包路径，便于后续扩展。
|
||
|
||
章节来源
|
||
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)
|
||
|
||
### 单元测试与集成测试策略
|
||
- 测试框架
|
||
- 使用JUnit Jupiter；Surefire插件配置包含所有测试类。
|
||
- 测试覆盖率
|
||
- 建议在CI中引入JaCoCo或类似工具统计覆盖率，目标不低于80%。
|
||
- 集成测试
|
||
- 通过Deploy*Test类在不同环境（dev/sit/prod）验证部署与配置。
|
||
|
||
章节来源
|
||
- [pom.xml:246-254](file://pom.xml#L246-L254)
|
||
- [nflg-wms-admin/pom.xml:38-41](file://nflg-wms-admin/pom.xml#L38-L41)
|
||
|
||
### 调试技巧与问题定位
|
||
- 日志
|
||
- 使用SLF4J与Loki日志采集，按环境调整日志级别；结合traceId快速定位。
|
||
- 性能分析
|
||
- 启用Actuator与OpenTelemetry，导出指标与链路数据，定位慢调用与异常。
|
||
- 常见问题
|
||
- PDF生成失败：确认wkhtmltoimage安装与路径；SAP JCo报错：检查JAR路径与权限。
|
||
|
||
章节来源
|
||
- [nflg-wms-admin/src/main/resources/application.yml:28-48](file://nflg-wms-admin/src/main/resources/application.yml#L28-L48)
|
||
- [readme.md:1-10](file://readme.md#L1-L10)
|
||
|
||
### 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模块扩展通用能力（如拦截器、切面、注解），由各业务模块复用。
|
||
|
||
章节来源
|
||
- [pom.xml:54-193](file://pom.xml#L54-L193)
|
||
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)
|
||
|
||
### 学习路径与技能要求
|
||
- 必备技能
|
||
- Java 17、Spring Boot/Spring Cloud、MyBatis-Plus、PostgreSQL、Nacos、Docker/Kubernetes（可选）。
|
||
- 进阶方向
|
||
- 链路追踪与可观测性、分布式缓存与限流、安全与认证、自动化测试与CI/CD。
|
||
|
||
### 常见开发问题与最佳实践
|
||
- 问题：PDF生成失败
|
||
- 解决：安装wkhtmltoimage并确保系统可用。
|
||
- 问题：SAP JCo无法加载
|
||
- 解决：将JAR放入lib目录并在构建阶段复制到输出目录。
|
||
- 最佳实践：统一异常处理、日志分级、参数校验、幂等与重试策略。
|
||
|
||
章节来源
|
||
- [readme.md:1-10](file://readme.md#L1-L10)
|
||
- [nflg-wms-admin/pom.xml:115-121](file://nflg-wms-admin/pom.xml#L115-L121) |