Guava Docs

Appearance

目录规范 ​

TIP

规定后端项目的目录结构与文件组织方式，适用于基于 Spring Boot 3 + MyBatis-Plus 的微服务业务模块。

设计原则 ​

原则说明
按职责分层Controller、Service、Repository 职责清晰，避免跨层调用
按业务聚合相关功能的 Controller、Service、Mapper 放在同一业务包下
接口与实现分离Service 定义接口，impl/ 包下提供实现
统一数据模型PO、DTO 公共的统一放在 Entity 模块，其余各业务服务自行定义
配置集中配置类、常量、枚举统一归位到 config/、constant/ 包

目录结构 ​

以下为推荐的业务微服务模块（如 guava-admin-starter）包结构：

text
com.guava.admin/
├── BootApplication.java          # 启动类
├── config/                      # 配置类
│   ├── RedisListenerConfig.java # Redis 监听配置
│   └── AsyncTaskExecutorConfig.java # 异步任务配置
├── constant/                    # 常量定义
│   ├── RedisAdminConstants.java # Redis 常量
│   ├── DicConstants.java        # 字典常量
│   └── TableDicConstant.java    # 表字典常量
├── controller/                  # REST 接口层（按业务分子包）
│   ├── sysuser/                 # 用户模块
│   │   └── SysUserController.java
│   ├── sysdept/                 # 部门模块
│   │   └── SysDeptController.java
│   └── sysmenu/                 # 模块菜单
│       └── SysMenuController.java
├── service/                     # 业务逻辑层
│   ├── sysuser/                 # 用户服务接口
│   │   ├── SysUserService.java
│   │   └── impl/
│   │       └── SysUserServiceImpl.java
│   └── sysdept/
│       ├── SysDeptService.java
│       └── impl/
│           └── SysDeptServiceImpl.java
├── repository/                  # 数据访问层
│   ├── SysUserMapper.java       # Mapper 接口
│   ├── SysDeptMapper.java
│   └── provider/                # 动态 SQL Provider
│       ├── SysUserSqlProvider.java
│       └── SysDeptSqlProvider.java
├── model/                       # 服务私有模型（非跨服务共享）
│   └── po/                      # 服务内 PO（如无跨服务共享必要）
├── feign/                       # 远程调用接口
│   └── redisService/
│       └── RedisUserFeignService.java
├── redis/                       # Redis 客户端封装
│   └── RedisAdminClient.java
├── event/                       # 事件发布/监听
│   └── MenuChangedEventListener.java
└── util/                        # 服务私有工具类
    ├── CommonUtils.java
    └── MenuUtils.java

包职责说明 ​

controller/ — 接口层 ​

  • 仅负责接收请求、参数校验、调用 Service
  • 禁止在 Controller 中写业务逻辑
  • 按业务域分子包，如 sysuser/、sysdept/

service/ — 业务逻辑层 ​

  • service/XxxService.java 定义接口
  • service/Xxx/impl/XxxServiceImpl.java 提供实现
  • 业务编排、事务管理、调用 Repository / Feign

repository/ — 数据访问层 ​

  • Mapper 接口继承 DBMapper<T>（Guava 平台封装）
  • 复杂动态 SQL 放在 provider/ 包下，使用 @SelectProvider 注解

feign/ — 远程调用层 ​

  • 定义调用其他服务的 Feign 接口
  • 按目标服务分子包

文件命名 ​

类型命名规则示例
ControllerXxxController.javaSysUserController.java
Service 接口XxxService.javaSysUserService.java
Service 实现XxxServiceImpl.javaSysUserServiceImpl.java
MapperXxxMapper.javaSysUserMapper.java
SQL ProviderXxxSqlProvider.javaSysUserSqlProvider.java
Feign 接口XxxFeignService.javaRedisUserFeignService.java
配置类XxxConfig.javaRedisListenerConfig.java
常量类XxxConstants.javaRedisAdminConstants.java
POXxxPO.javaSysUserPO.java
DTOXxxDTO.javaSysUserDTO.java

分层调用规范 ​

Controller
    │ 调用
    ▼
Service（接口）
    │ 实现
    ▼
ServiceImpl
    │ 调用
    ├── Repository（Mapper）
    ├── Feign（远程服务）
    └── RedisClient（缓存）
  • 禁止 Controller 直接调用 Mapper
  • 禁止 Service 实现类之间互相调用（提取到公共 Service 中）
  • 禁止 在 Mapper 中写业务逻辑

反例与正例 ​

❌ 反例：按文件类型扁平堆叠 ​

text
com.guava.admin/
├── controller/        # 所有 Controller 混在一起
├── service/           # 所有 Service 混在一起
└── mapper/            # 所有 Mapper 混在一起

✅ 正例：按业务模块组织 ​

text
com.guava.admin/
├── controller/
│   ├── sysuser/
│   ├── sysdept/
│   └── sysmenu/
├── service/
│   ├── sysuser/
│   │   ├── SysUserService.java
│   │   └── impl/
│   ├── sysdept/
│   └── sysmenu/
└── repository/
    ├── SysUserMapper.java
    └── SysDeptMapper.java

相关规范 ​