项目结构

Molan Cloud 采用 Maven 多模块结构，清晰的模块划分便于开发和维护。

整体结构

backend/
├── core/                     # 双模驱动核心库（单模块，按包划分能力）
├── apis/                     # API 接口定义（Feign 接口）
├── base-service/             # 基础服务（用户/角色/菜单/部门/文件/消息/任务）
├── knowledge-service/        # 知识库服务（RAG 检索增强生成）
├── xiuxian-service/          # AI 修仙服务（AI 对话、技能系统）
├── gateway-service/          # 微服务网关
└── standalone-service/       # 单体模式启动入口

设计理念

服务拆分不再按功能垂直划分，而是按业务域聚合。base 整合了系统管理、文件、消息、任务等基础能力，knowledge 和 xiuxian 专注于 AI 相关业务。单体模式通过 standalone 启动，微服务模式通过 gateway + 各服务独立部署。

后端模块详解

1. API 模块 (apis)

职责： 定义服务间调用的 Feign 接口和 DTO。

特点：

✅ 接口定义与实现分离
✅ 支持单体和微服务双模
✅ 统一的 API 规范

目录结构：

apis/
└── src/main/java/com/molandev/api/
    ├── sys/                        # 系统相关 API
    │   └── user/
    │       └── SysUserApi.java     # 用户服务接口
    ├── msg/                        # 消息相关 API
    │   └── MsgSendApi.java         # 消息发送接口
    └── dto/                        # 数据传输对象
        └── UserDto.java

示例代码：

java

// Feign 接口定义
@FeignClient(
    name = "${molandev.service-name.base-service:base-service}", 
    contextId = "sysUserApi", 
    path = "/feign/user"
)
public interface SysUserApi {

    @GetMapping("/admin")
    UserDto getAdmin(@RequestParam("id") String id);
}

接口即服务

通过 backend/core 的 RPC 能力，Feign 在单体下走本地调用，微服务下走远程 HTTP，业务代码无需感知。

2. 应用服务模块

2.1 基础服务 (base)

职责： 基础业务服务，整合了系统管理、文件、消息、任务等功能。

包含功能：

用户管理、角色管理、菜单管理、部门管理
文件上传下载、回收站机制
消息发送、站内信、WebSocket 推送
定时任务调度

目录结构：

base/
├── src/main/java/com/molandev/base/
│   ├── sys/                      # 系统管理
│   │   ├── controller/
│   │   │   ├── SysUserController.java
│   │   │   ├── SysRoleController.java
│   │   │   └── SysMenuController.java
│   │   ├── service/
│   │   └── mapper/
│   ├── file/                     # 文件管理
│   │   ├── controller/
│   │   └── service/
│   ├── msg/                      # 消息管理
│   │   ├── controller/
│   │   └── service/
│   ├── task/                     # 定时任务
│   │   ├── controller/
│   │   └── service/
│   └── BaseApp.java              # 启动类（微服务模式）
└── src/main/resources/
    └── application.yml

启动类：

java

@SpringBootApplication
public class BaseApp {
    public static void main(String[] args) {
        SpringApplication.run(BaseApp.class, args);
    }
}

服务整合

base 整合了原 sys-service、file-service、msg-service、task-service 的所有功能，减少服务间通信开销，简化部署和运维。

2.2 知识库服务 (knowledge)

职责： RAG 检索增强生成，文档摄入、向量化、检索。

目录结构：

knowledge/
├── src/main/java/com/molandev/knowledge/
│   ├── ingest/                    # 文档摄入
│   │   ├── controller/
│   │   └── service/
│   ├── retrieval/                 # 检索系统
│   │   ├── controller/
│   │   └── service/
│   ├── rag/                       # RAG 问答
│   │   ├── controller/
│   │   └── service/
│   └── KnowledgeApp.java          # 启动类
└── src/main/resources/
    └── application.yml

2.3 AI 修仙服务 (xiuxian)

职责： AI 对话、技能系统、工具调用。

目录结构：

xiuxian/
├── src/main/java/com/molandev/xiuxian/
│   ├── chat/                      # AI 对话
│   │   ├── controller/
│   │   └── service/
│   ├── skill/                     # 技能系统
│   │   ├── controller/
│   │   └── service/
│   ├── tool/                      # 工具调用
│   │   ├── controller/
│   │   └── service/
│   └── XiuxianApp.java            # 启动类
└── src/main/resources/
    └── application.yml

2.4 网关服务 (gateway)

职责： 微服务模式的统一入口、路由转发、认证鉴权。

技术栈：

Spring Cloud Gateway (WebFlux)
Redis Reactive
Knife4j Gateway

目录结构：

gateway/
├── src/main/java/com/molandev/gateway/
│   ├── config/                    # 配置类
│   │   └── GatewayConfig.java
│   ├── filter/                    # 过滤器
│   │   ├── GatewayAuthFilter.java
│   │   └── PermissionCheckGatewayFilter.java
│   └── GatewayApp.java            # 启动类
└── src/main/resources/
    └── application.yml

核心功能：

java

// 认证过滤器
@Component
public class GatewayAuthFilter implements GlobalFilter, Ordered {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, 
                            GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        
        // 白名单检查
        if (isWhiteList(request.getPath().value())) {
            return chain.filter(exchange);
        }
        
        // Token 验证
        String token = getToken(request);
        if (StringUtils.isEmpty(token)) {
            return unauthorized(exchange);
        }
        
        // 验证 Token 并获取用户信息
        try {
            // ... Token 验证逻辑
            return chain.filter(exchange);
        } catch (Exception e) {
            return unauthorized(exchange);
        }
    }
    
    @Override
    public int getOrder() {
        return -100;
    }
}

2.5 单体模式入口 (standalone)

职责： 单体模式的启动入口，合并 base、knowledge、xiuxian 模块。

实现方式：

通过 @ComponentScan 合并扫描多个模块
排除微服务相关依赖（Nacos、Feign、RabbitMQ）
共享数据库连接

启动类：

java

@Slf4j
@SpringBootApplication
@ComponentScan({
    "com.molandev.base",
    "com.molandev.knowledge",
    "com.molandev.xiuxian"
})
public class StandaloneApp {

    public static void main(String[] args) {
        SpringApplication.run(StandaloneApp.class, args);
    }
}

pom.xml 配置：

xml

<dependencies>
    <!-- 引入基础服务，排除微服务依赖 -->
    <dependency>
        <groupId>com.molandev</groupId>
        <artifactId>base-service</artifactId>
        <exclusions>
            <exclusion>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            </exclusion>
            <exclusion>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
            </exclusion>
            <exclusion>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-openfeign</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <!-- 引入知识库服务 -->
    <dependency>
        <groupId>com.molandev</groupId>
        <artifactId>knowledge-service</artifactId>
    </dependency>
    <!-- 引入 AI 修仙服务 -->
    <dependency>
        <groupId>com.molandev</groupId>
        <artifactId>xiuxian-service</artifactId>
    </dependency>
</dependencies>

配置示例：

yaml

# application-mysql.yml
molandev:
  mode: standalone          # 单体模式
  lock:
    type: memory            # 使用内存锁
  datasource:
    sys:                     # 基础数据源
      url: jdbc:mysql://localhost:3306/molandev_base
      username: root
      password: 123456
      packages:
        - com.molandev.base
    knowledge:               # 知识库数据源
      url: jdbc:mysql://localhost:3306/molandev_kl
      username: root
      password: 123456
      packages:
        - com.molandev.knowledge
    xiuxian:                 # 修仙数据源
      url: jdbc:mysql://localhost:3306/molandev_xiuxian
      username: root
      password: 123456
      packages:
        - com.molandev.xiuxian
  security:
    mode: LOCAL             # 本地认证模式

3. 统一响应与约定（已在 core）

原先独立的 common 模块能力已并入 backend/core，例如：

com.molandev.core.web.JsonResult：统一响应
MyBatis / Redis 等约定与自动配置：见 core 内 db、cache、web 等包

业务模块直接依赖 core 即可，无需再引入 molandev-common。

4. Core 依赖

业务模块依赖同仓 backend/core（Maven 坐标 com.molandev:core），能力按包划分：

包	功能
`com.molandev.core.rpc`	接口即服务、单体/远程智能路由
`com.molandev.core.event`	事件总线（内存 / RabbitMQ）
`com.molandev.core.db`	MyBatis-Plus 约定；`db.dynamic` 动态数据源
`com.molandev.core.encrypt`	加解密、签名、脱敏
`com.molandev.core.lock`	分布式锁（Memory / Redisson）
`com.molandev.core.file`	文件存储（local / s3，由 `molandev.file.type` 启用）
`com.molandev.core.web`	统一响应、JSON、XSS、Servlet 过滤器
`com.molandev.core.task`	任务调度（`TaskUtil`）
`com.molandev.core.cache`	缓存（含 Redis）
`com.molandev.core.util`	通用工具（含 tree / SpringUtils / UserAgentUtil）
`com.molandev.core.config`	`MolanMode`（`molandev.mode`）

包命名规范

com.molandev.{module}
├── controller      # 控制器
├── service         # 服务类（直接继承 ServiceImpl）
├── mapper          # 数据访问
├── entity          # 实体类
├── dto             # 数据传输对象
├── enums           # 枚举
├── constant        # 常量
├── config          # 配置类
└── utils           # 工具类

命名示例：

类型	命名规则	示例
实体类	{Name}Entity	`SysUserEntity`
服务类	{Name}Service	`SysUserService`
Mapper	{Name}Mapper	`SysUserMapper`
Controller	{Name}Controller	`SysUserController`

依赖关系

standalone-service / gateway-service
    ↓ 依赖
base-service / knowledge-service / xiuxian-service
    ↓ 依赖
apis (API 层)
    ↓ 依赖
core（双模内核 + 统一约定）

配置文件

application.yml 结构

微服务模式（base）：

yaml

server:
  port: 19091

spring:
  application:
    name: base
  
  # Nacos 配置（微服务模式）
  cloud:
    nacos:
      discovery:
        server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
        namespace: ${NACOS_NAMESPACE:molandev_local}
      config:
        server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
        namespace: ${NACOS_NAMESPACE:molandev_local}

molandev:
  mode: microservice           # 微服务模式
  datasource:
    sys:
      url: jdbc:mysql://localhost:3306/molandev_base
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
      packages:
        - com.molandev.base
  security:
    mode: GATEWAY             # 网关认证模式

单体模式（standalone）：

yaml

server:
  port: 9099

molandev:
  mode: standalone          # 单体模式
  lock:
    type: memory            # 内存锁
  security:
    mode: LOCAL             # 本地认证模式

双模部署

单体模式

yaml

molandev:
  mode: standalone

特点：
- 本地方法调用
- 多数据源事务统一
- 简单部署
- 快速开发

微服务模式

yaml

molandev:
  mode: microservice

特点：
- HTTP 远程调用
- 服务独立部署
- 弹性扩展
- 故障隔离

最佳实践

1. 模块职责单一

每个模块只负责一个领域的功能，避免职责混乱。

2. 依赖管理

API 模块不依赖具体实现
服务模块依赖 API 模块
避免循环依赖

3. 代码分层

严格遵循分层架构：Controller → Service → Mapper

4. 命名规范

类名：大驼峰
方法名：小驼峰
常量：全大写下划线分隔

5. 注释规范

类注释：说明职责
方法注释：说明参数、返回值、异常
复杂逻辑：添加行内注释

总结

Molan Cloud 的项目结构特点：

✅ 模块化设计：清晰的模块划分
✅ 分层架构：Controller-Service-Mapper
✅ 双模支持：单体和微服务
✅ 统一规范：包命名、代码风格
✅ 易于扩展：新增模块简单
✅ 便于维护：职责清晰、解耦合理

双模架构优势

通过 molandev.mode 配置项，项目可以在单体模式和微服务模式之间自由切换，无需修改业务代码。单体模式适合快速开发和中小规模部署，微服务模式适合大规模和高可用场景。

项目结构 ​

整体结构 ​

后端模块详解 ​

1. API 模块 (apis) ​

2. 应用服务模块 ​

2.1 基础服务 (base) ​

2.2 知识库服务 (knowledge) ​

2.3 AI 修仙服务 (xiuxian) ​

2.4 网关服务 (gateway) ​

2.5 单体模式入口 (standalone) ​

3. 统一响应与约定（已在 core） ​

4. Core 依赖 ​

包命名规范 ​

依赖关系 ​

配置文件 ​

application.yml 结构 ​

双模部署 ​

单体模式 ​

微服务模式 ​

最佳实践 ​

1. 模块职责单一 ​

2. 依赖管理 ​

3. 代码分层 ​

4. 命名规范 ​

5. 注释规范 ​

总结 ​

项目结构

整体结构

后端模块详解

1. API 模块 (apis)

2. 应用服务模块

2.1 基础服务 (base)

2.2 知识库服务 (knowledge)

2.3 AI 修仙服务 (xiuxian)

2.4 网关服务 (gateway)

2.5 单体模式入口 (standalone)

3. 统一响应与约定（已在 core）

4. Core 依赖

包命名规范

依赖关系

配置文件

application.yml 结构

双模部署

单体模式

微服务模式

最佳实践

1. 模块职责单一

2. 依赖管理

3. 代码分层

4. 命名规范

5. 注释规范

总结