后端目录结构

1. 项目结构概览

zs-project-java项目采用Maven多模块架构，主要分为以下几个核心部分：

根项目：zs-project-java，包含所有子模块的聚合配置
启动模块：zs-admin，负责应用的启动和主配置
基础组件库：zs-common，提供通用功能和工具类
定时任务模块：zs-quartz，处理系统定时任务
代码生成模块：zs-generator，提供代码自动生成功能
业务模块集合：zs-modules，包含各个业务功能模块

2. Maven多模块架构

项目采用分层的Maven多模块架构设计，通过根pom.xml文件统一管理所有子模块的依赖和版本。

模块定义

根模块zs-project-java在pom.xml中定义了以下子模块：

xml

<modules>
    <module>zs-admin</module>
    <module>zs-common</module>
    <module>zs-quartz</module>
    <module>zs-generator</module>
    <module>zs-modules</module>
    <module>zs-modules/zs-file</module>
    <module>zs-modules/zs-mail</module>
    <module>zs-modules/zs-sms</module>
    <module>zs-modules/zs-system</module>
    <module>zs-modules/zs-websocket</module>
</modules>

模块关系图

mermaid

graph TD
A[zs-project-java] --> B[zs-admin]
A --> C[zs-common]
A --> D[zs-quartz]
A --> E[zs-generator]
A --> F[zs-modules]
F --> G[zs-file]
F --> H[zs-mail]
F --> I[zs-sms]
F --> J[zs-system]
F --> K[zs-websocket]

3. 核心基础组件库（zs-common）

zs-common模块是项目的基础组件库，采用子模块化设计，提供各种通用功能。

主要子模块

zs-common-core：核心工具库，提供基础工具类和常量定义，依赖于zs-common-redis模块
zs-common-security：安全认证模块，依赖于zs-common-core、zs-common-aop和zs-common-redis模块

模块依赖关系

mermaid

graph TD
A[zs-common-security] --> B[zs-common-core]
A --> C[zs-common-aop]
A --> D[zs-common-redis]
B --> D

4. 业务模块集合（zs-modules）

zs-modules目录包含所有业务功能模块，每个模块都采用API+Service的分层设计模式。

模块构成

每个业务模块（如zs-system、zs-file等）都包含两个子模块：

API模块：定义接口契约，供其他模块调用
Service模块：实现具体业务逻辑

业务模块结构

mermaid

graph TD
A[zs-system] --> B[zs-system-api]
A --> C[zs-system-service]
D[zs-file] --> E[zs-file-api]
D --> F[zs-file-service]
G[zs-mail] --> H[zs-mail-api]
G --> I[zs-mail-service]
J[zs-sms] --> K[zs-sms-api]
J --> L[zs-sms-service]

5. MVC分层结构

项目采用标准的MVC分层架构，每个Service模块内部都包含controller、service、mapper和entity等层次。

层次职责

Controller层：处理HTTP请求，参数校验，调用Service层
Service层：实现核心业务逻辑，事务管理
Mapper层：数据访问接口，与数据库交互
Entity层：数据实体对象，对应数据库表结构

典型模块结构

以zs-system-service为例，其目录结构如下：

zs-system-service/
├── src/main/java/com/zs/sys/
│   ├── controller/     # 控制器层
│   ├── domain/         # 领域模型
│   │   ├── entity/     # 实体类
│   │   ├── params/     # 参数对象
│   │   └── vo/         # 视图对象
│   ├── service/        # 服务层
│   │   ├── impl/       # 服务实现
│   │   └── ISysService.java  # 服务接口
│   └── mapper/         # 数据映射器

内部调用关系

mermaid

graph TD
A[Controller] --> B[Service]
B --> C[Mapper]
C --> D[(数据库)]
B --> E[Redis]
A --> F[Validator]

6. 配置文件与环境隔离

项目通过Spring Boot的配置文件机制实现不同环境的配置隔离。

配置文件结构

在zs-admin模块的resources目录下，包含以下配置文件：

application.yml：主配置文件，包含通用配置
application-dev.yml：开发环境配置
application-prod.yml：生产环境配置
banner.txt：启动Banner
logback-spring.xml：日志配置

通过Spring Profile机制，可以在不同环境中激活相应的配置文件，实现配置的环境隔离。

7. 根POM依赖管理

根POM文件通过<dependencyManagement>统一管理所有模块的依赖版本，确保版本一致性。

核心特性

版本集中管理：在<dependencyManagement>中声明所有模块使用的依赖及其版本
继承机制：所有子模块继承根POM，自动获得统一的依赖版本配置
避免版本冲突：通过集中管理防止不同模块使用同一依赖的不同版本

根POM还定义了项目级别的属性（如Java版本、MySQL版本）和全局依赖（如Spring Boot Starter系列）。

依赖管理结构

mermaid

graph TD
RootPOM["根POM (zs-project-java)"] --> DependencyManagement["dependencyManagement<br/>统一版本管理"]
RootPOM --> Properties["properties<br/>全局属性定义"]
RootPOM --> Dependencies["dependencies<br/>全局依赖"]
DependencyManagement --> CommonModules["zs-common-* 模块"]
DependencyManagement --> BusinessModules["zs-modules/* 模块"]
DependencyManagement --> CoreModule["zs-admin 模块"]

8. 依赖传递与版本控制

版本继承机制

子模块通过继承根POM获得依赖版本管理：

xml

<parent>
    <groupId>com.zs</groupId>
    <artifactId>zs-project-java</artifactId>
    <version>1.0.0</version>
</parent>

依赖声明方式

子模块在<dependencies>中声明所需依赖，无需指定版本：

xml

<dependency>
    <groupId>com.zs</groupId>
    <artifactId>zs-common-core</artifactId>
</dependency>

版本由根POM的<dependencyManagement>统一控制。

版本覆盖规则

当需要特定版本时，可在子模块中显式指定版本号，覆盖全局管理版本：

xml

<dependency>
    <groupId>com.zs</groupId>
    <artifactId>zs-system-api</artifactId>
    <version>1.0.0</version>
</dependency>

依赖冲突解决

版本冲突：通过dependencyManagement统一版本
传递依赖冲突：使用<exclusions>排除不需要的传递依赖
类路径冲突：检查重复的JAR包

排除示例

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.lettuce</groupId>
            <artifactId>lettuce-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

最佳实践

统一管理：所有版本在根POM中管理
定期审查：定期运行dependency:analyze检查未使用的依赖
最小化依赖：只引入必要的依赖，避免过度依赖
文档化：记录关键依赖的用途和版本选择理由

9. 模块间依赖关系

项目采用清晰的模块依赖层级，实现功能解耦和职责分离。

核心依赖关系

zs-admin 依赖所有业务模块（zs-system-service、zs-file-service等）
业务模块依赖基础公共模块（zs-common-core、zs-common-security等）
公共模块之间存在内部依赖（如zs-common-core依赖zs-common-redis）

API接口依赖模式

业务模块采用"API+实现"的分离模式：

zs-system-api：定义系统模块的接口
zs-system-service：实现系统模块功能，依赖zs-system-api
其他模块通过API接口通信，而非直接依赖实现类

模块依赖关系图

mermaid

graph TD
Admin["zs-admin"] --> FileService["zs-file-service"]
Admin --> MailService["zs-mail-service"]
Admin --> SystemService["zs-system-service"]
Admin --> Quartz["zs-quartz"]
FileService --> CommonCore["zs-common-core"]
FileService --> CommonSecurity["zs-common-security"]
FileService --> SystemAPI["zs-system-api"]
MailService --> CommonCore
MailService --> CommonSecurity
MailService --> SystemAPI
MailService --> MailAPI["zs-mail-api"]
SystemService --> CommonCore
SystemService --> CommonSecurity
SystemService --> SystemAPI
CommonCore --> CommonRedis["zs-common-redis"]

10. 模块间调用关系与依赖注入

zs-admin启动模块

zs-admin作为启动模块，通过依赖注入整合所有业务模块。

xml

<dependencies>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-quartz</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-generator</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-common-security</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-mail-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-system-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-file-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-sms-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.zs</groupId>
        <artifactId>zs-websocket-service</artifactId>
    </dependency>
</dependencies>

启动类配置

ZsAdminApplication.java作为Spring Boot的启动类，通过@SpringBootApplication注解自动扫描和配置所有组件。

mermaid

graph TD
A[ZsAdminApplication] --> B[zs-quartz]
A --> C[zs-generator]
A --> D[zs-common-security]
A --> E[zs-mail-service]
A --> F[zs-system-service]
A --> G[zs-file-service]
A --> H[zs-sms-service]
A --> I[zs-websocket-service]

11. 开发者导航指南

代码导航路径

启动入口：zs-admin/src/main/java/com/zs/ZsAdminApplication.java
核心配置：zs-project-java/pom.xml 和 zs-admin/src/main/resources/application.yml
基础组件：zs-common/ 目录下的各个子模块
业务功能：
- 系统管理：zs-modules/zs-system/
- 文件服务：zs-modules/zs-file/
- 邮件服务：zs-modules/zs-mail/
- 短信服务：zs-modules/zs-sms/
- WebSocket：zs-modules/zs-websocket/
工具模块：zs-quartz/ 和 zs-generator/

开发建议

新增业务模块时，参考zs-modules下的现有模块结构
公共功能应提取到zs-common相应的子模块中
API接口定义放在API模块，实现放在Service模块
使用Spring Profile管理不同环境的配置

后端目录结构 ​

1. 项目结构概览 ​

2. Maven多模块架构 ​

模块定义 ​

模块关系图 ​

3. 核心基础组件库（zs-common） ​

主要子模块 ​

模块依赖关系 ​

4. 业务模块集合（zs-modules） ​

模块构成 ​

业务模块结构 ​

5. MVC分层结构 ​

层次职责 ​

典型模块结构 ​

内部调用关系 ​

6. 配置文件与环境隔离 ​

配置文件结构 ​

7. 根POM依赖管理 ​

核心特性 ​

依赖管理结构 ​

8. 依赖传递与版本控制 ​

版本继承机制 ​

依赖声明方式 ​

版本覆盖规则 ​

依赖冲突解决 ​

排除示例 ​

最佳实践 ​

9. 模块间依赖关系 ​

核心依赖关系 ​

API接口依赖模式 ​

模块依赖关系图 ​

10. 模块间调用关系与依赖注入 ​

zs-admin启动模块 ​

启动类配置 ​

11. 开发者导航指南 ​

代码导航路径 ​

开发建议 ​

后端目录结构

1. 项目结构概览

2. Maven多模块架构

模块定义

模块关系图

3. 核心基础组件库（zs-common）

主要子模块

模块依赖关系

4. 业务模块集合（zs-modules）

模块构成

业务模块结构

5. MVC分层结构

层次职责

典型模块结构

内部调用关系

6. 配置文件与环境隔离

配置文件结构

7. 根POM依赖管理

核心特性

依赖管理结构

8. 依赖传递与版本控制

版本继承机制

依赖声明方式

版本覆盖规则

依赖冲突解决

排除示例

最佳实践

9. 模块间依赖关系

核心依赖关系

API接口依赖模式

模块依赖关系图

10. 模块间调用关系与依赖注入

zs-admin启动模块

启动类配置

11. 开发者导航指南

代码导航路径

开发建议