后端架构
项目结构
本项目采用Maven多模块架构，主要分为以下几个部分：
- zs-admin: 主应用模块，负责整合所有业务模块并提供统一入口
- zs-common: 基础公共模块，包含通用功能组件
- zs-modules: 业务模块集合，包含各个独立的业务功能
- zs-quartz: 定时任务模块
- zs-generator: 代码生成器模块
mermaid
graph TD
zs-admin[zs-admin 主应用] --> zs-common[zs-common 基础模块]
zs-admin --> zs-modules[zs-modules 业务模块]
zs-admin --> zs-quartz[zs-quartz 定时任务]
zs-admin --> zs-generator[zs-generator 代码生成]
zs-common --> aop[zs-common-aop 切面模块]
zs-common --> core[zs-common-core 核心模块]
zs-common --> mybatis[zs-common-mybatis MyBatis扩展]
zs-common --> redis[zs-common-redis Redis集成]
zs-common --> security[zs-common-security 安全框架]
zs-modules --> file[zs-file 文件服务]
zs-modules --> mail[zs-mail 邮件服务]
zs-modules --> sms[zs-sms 短信服务]
zs-modules --> system[zs-system 系统管理]
zs-modules --> websocket[zs-websocket WebSocket服务]目录结构
├── zs-project-java/ # 后端根目录
│ ├── zs-admin/ # 主应用模块
│ ├── zs-common/ # 公共模块
│ │ ├── zs-common-aop/ # 切面编程模块
│ │ ├── zs-common-core/ # 核心工具类模块
│ │ ├── zs-common-mybatis/ # MyBatis配置模块
│ │ ├── zs-common-redis/ # Redis工具模块
│ │ └── zs-common-security/ # 安全配置模块
│ ├── zs-generator/ # 代码生成器模块
│ ├── zs-quartz/ # 定时任务模块
│ ├── zs-modules/ # 业务模块集合
│ │ ├── zs-file/ # 文件管理模块
│ │ ├── zs-mail/ # 邮件管理模块
│ │ ├── zs-sms/ # 短信管理模块
│ │ ├── zs-system/ # 系统管理模块
│ │ └── zs-websocket/ # WebSocket模块
│ └── pom.xml # 父工程pom.xml模块化架构
项目采用Spring Boot为基础的模块化架构设计，通过Maven的dependencyManagement机制统一管理各模块版本。zs-admin作为主应用模块，通过依赖引入的方式整合zs-common基础模块和zs-modules业务模块。
主应用通过@SpringBootApplication注解的scanBasePackages属性指定组件扫描范围，确保能够发现所有模块中的Spring组件。
mermaid
graph TD
A[客户端请求] --> B[zs-admin 主应用]
B --> C[zs-common 基础模块]
B --> D[zs-modules 业务模块]
C --> E[安全控制]
C --> F[数据访问]
C --> G[缓存管理]
D --> H[文件服务]
D --> I[邮件服务]
D --> J[短信服务]
D --> K[系统管理]
D --> L[WebSocket服务]MVC分层设计
项目严格遵循MVC分层架构，各层职责明确：
控制层 (Controller)
负责接收HTTP请求，进行参数校验和转换，调用服务层处理业务逻辑，并返回响应结果。所有控制器类位于各模块的controller包下。
服务层 (Service)
实现核心业务逻辑，协调数据访问层完成数据操作。服务层分为接口定义和实现类，遵循面向接口编程原则。
数据访问层 (Mapper)
基于MyBatis-Plus实现数据持久化操作，提供丰富的CRUD方法。Mapper接口与XML映射文件配合使用，支持复杂查询。
实体层 (Entity)
定义数据模型，与数据库表结构对应。实体类通常包含@Table、@Column等JPA注解，用于ORM映射。
mermaid
graph TD
Controller[Controller层] --> Service[Service层]
Service --> Mapper[Mapper层]
Mapper --> Database[(数据库)]
Database --> Mapper
Mapper --> Service
Service --> Controller多租户支持
多租户支持
项目通过MyBatis-Plus的多租户插件实现多租户支持。在application.yml中配置多租户相关参数：
yaml
tenant:
enable: true
column: tenant_id
ignoreTablePrefix: # 忽略表前缀
- jimu_
- qrtz_
- gen_
ignoreTables: # 忽略表
- sys_tenant
- sys_tenant_package
- sys_configMybatisPlusConfig配置类中通过TenantLineInnerInterceptor实现租户隔离，MultiTenantHandler负责处理租户ID的获取和SQL条件注入。
安全框架集成
项目集成了Spring Security安全框架，实现JWT认证和权限控制。
JWT认证
通过JwtAuthenticationTokenFilter过滤器实现JWT令牌的验证。在application.yml中配置JWT相关参数：
yaml
jwt:
secret: QxXJ18vaaiH0781h6rzMurcyJNzcGtsWYfzc/OyqKBI= # 密钥
expiration: 86400 # 过期时间，单位秒权限控制
使用@EnableMethodSecurity注解启用方法级别的权限认证。通过CustomAccessDeniedHandler和CustomAuthenticationEntryPoint处理权限异常。
白名单配置在security.white.url中，定义了无需认证即可访问的URL路径。
mermaid
classDiagram
class WebSecurityConfig {
+filterChain(HttpSecurity http)
+authenticationManager(AuthenticationConfiguration config)
+corsConfigurationSource()
}
class JwtAuthenticationTokenFilter {
+doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
+getJwtFromRequest(HttpServletRequest request)
+validateToken(String token)
}
class CustomAuthenticationEntryPoint {
+commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException)
}
class CustomAccessDeniedHandler {
+handle(HttpServletRequest request, HttpServletResponse response, AccessDeniedException accessDeniedException)
}
class UserNameAuthenticationProvider {
+authenticate(Authentication authentication)
+supports(Class~?~ authentication)
}
WebSecurityConfig --> JwtAuthenticationTokenFilter : "使用"
WebSecurityConfig --> CustomAuthenticationEntryPoint : "使用"
WebSecurityConfig --> CustomAccessDeniedHandler : "使用"
WebSecurityConfig --> UserNameAuthenticationProvider : "使用"核心配置类说明
WebConfig
WebMvcConfigurer实现类，负责Web相关配置：
- 配置文件上传路径的资源处理器
- 添加租户拦截器TenantInterceptor
- 自定义消息转换器，处理JSON序列化
MybatisPlusConfig
MyBatis-Plus配置类，集成多种插件：
- 多租户插件：实现数据隔离
- 乐观锁插件：防止并发修改
- SQL防护插件：防止全表更新/删除
- 数据权限插件：实现细粒度权限控制
- 分页插件：提供分页功能
WebSecurityConfig
Spring Security配置类，负责安全相关配置：
- 配置HTTP安全策略
- 设置认证和授权规则
- 注册自定义过滤器和处理器
- 配置CORS跨域支持
MyJacksonConfig
Jackson序列化配置类，统一JSON处理规则：
- Long类型序列化为字符串，避免前端精度丢失
- BigDecimal类型保留两位小数
- 空字符串和布尔值的特殊处理
- 日期格式统一为"yyyy-MM-dd HH:mm:ss"
ThreadPoolConfig
线程池配置类，提供异步任务执行能力：
- 核心线程数：CPU核心数
- 最大线程数：CPU核心数×2
- 队列容量：100
- 线程名称前缀：zs-thread-
- 拒绝策略：由调用线程处理
mermaid
graph TD
WebConfig[WebConfig] --> ResourceHandler[资源处理器]
WebConfig --> Interceptor[拦截器]
WebConfig --> MessageConverter[消息转换器]
MybatisPlusConfig[MybatisPlusConfig] --> TenantPlugin[多租户插件]
MybatisPlusConfig --> OptimisticLock[乐观锁插件]
MybatisPlusConfig --> BlockAttack[SQL防护插件]
MybatisPlusConfig --> DataPermission[数据权限插件]
MybatisPlusConfig --> Pagination[分页插件]
WebSecurityConfig[WebSecurityConfig] --> HttpSecurity[HTTP安全]
WebSecurityConfig --> Authentication[认证]
WebSecurityConfig --> Authorization[授权]
WebSecurityConfig --> Cors[CORS配置]
MyJacksonConfig[MyJacksonConfig] --> JsonSerialization[JSON序列化]
MyJacksonConfig --> LongToString[Long转字符串]
MyJacksonConfig --> BigDecimalFormat[BigDecimal格式化]
ThreadPoolConfig[ThreadPoolConfig] --> ThreadPool[线程池]
ThreadPoolConfig --> CorePool[核心线程]
ThreadPoolConfig --> MaxPool[最大线程]
ThreadPoolConfig --> Queue[任务队列]典型请求处理流程
以用户登录请求为例，展示典型请求的处理流程：
mermaid
sequenceDiagram
participant Client as "客户端"
participant SecurityFilter as "安全过滤器链"
participant JwtFilter as "JWT过滤器"
participant LoginController as "LoginController"
participant LoginService as "LoginService"
participant UserMapper as "UserMapper"
participant Database as "数据库"
Client->>SecurityFilter : POST /auth/login
SecurityFilter->>SecurityFilter : CORS预检处理
SecurityFilter->>LoginController : 跳过JWT验证(白名单)
LoginController->>LoginService : authenticate(credentials)
LoginService->>UserMapper : findByUsername(username)
UserMapper->>Database : 查询用户数据
Database-->>UserMapper : 用户信息
UserMapper-->>LoginService : User对象
LoginService->>LoginService : 验证密码
LoginService->>LoginService : 生成JWT令牌
LoginService-->>LoginController : 认证结果
LoginController-->>Client : {token, userInfo}- 客户端发送登录请求到/auth/login端点
- 请求经过Spring Security过滤器链
- 由于/auth/login在白名单中，跳过JWT验证
- 请求到达LoginController的登录方法
- 调用LoginService进行认证处理
- 通过UserMapper查询数据库获取用户信息
- 验证用户密码正确性
- 生成JWT令牌并返回给客户端