VortMall 微服务项目目录结构说明
VortMall 微服务项目目录结构说明
一、项目概览
VortMall 是一个基于 Spring Cloud Alibaba 的电商微服务系统，采用 DDD（领域驱动设计）分层架构。
vortmall-api/
├── db/ # 数据库脚本
├── deployment/ # 部署配置
├── docs/ # 项目文档
├── public/ # 公共资源（i18n）
├── scripts/ # 工具脚本
├── vortmall-auth/ # 认证服务
├── vortmall-biz/ # 业务服务模块（核心）
├── vortmall-common/ # 公共组件库
├── vortmall-feign/ # Feign 客户端
├── vortmall-gateway/ # API 网关
├── vortmall-tools/ # 开发工具
└── pom.xml # 父 POM
二、核心模块详解
2.1 vortmall-biz（业务服务）
业务服务是系统核心，按业务域拆分为 15 个微服务：
vortmall-biz/
├── pom.xml
├── vortmall-biz-aftersales/ # 售后服务（退款、退货、换货）
├── vortmall-biz-content/ # 内容服务（文章、公告、友情链接）
├── vortmall-biz-decoration/ # 装修服务（页面装修、组件配置）
├── vortmall-biz-distribution/ # 分销服务（分销员、佣金）
├── vortmall-biz-file/ # 文件服务（OSS、图片、视频）
├── vortmall-biz-logistics/ # 物流服务（运费模板、物流跟踪）
├── vortmall-biz-marketing/ # 营销服务（优惠券、秒杀、拼团）
├── vortmall-biz-message/ # 消息服务（站内信、短信、邮件）
├── vortmall-biz-order/ # 订单服务（订单、购物车）
├── vortmall-biz-organize/ # 组织服务（门店、供应商、商户）
├── vortmall-biz-payment/ # 支付服务（支付、退款、账单）
├── vortmall-biz-pos/ # POS 服务（收银、门店系统）
├── vortmall-biz-product/ # 商品服务（商品、分类、库存）
├── vortmall-biz-system/ # 系统服务（配置、菜单、权限）
└── vortmall-biz-user/ # 用户服务（会员、管理员、角色）
业务模块内部结构（DDD 分层）
每个业务模块内部按 DDD 分层架构组织，以 product 模块为例：
vortmall-biz-product/
├── pom.xml
└── src/main/
├── java/com/vortmall/product/
│ ├── VortmallBizProductApplication.java # 启动类
│ │
│ ├── brand/ # 品牌聚合
│ │ ├── adapter/ # 适配层（Controller）
│ │ │ ├── AdminBrandController.java # 管理端接口
│ │ │ ├── ApiBrandController.java # 用户端接口
│ │ │ └── FeignBrandController.java # Feign 内部接口
│ │ ├── application/ # 应用层
│ │ │ ├── AdminBrandServiceI.java # 管理端服务接口
│ │ │ ├── AdminBrandServiceImpl.java # 管理端服务实现
│ │ │ ├── ApiBrandServiceI.java # 用户端服务接口
│ │ │ ├── ApiBrandServiceImpl.java # 用户端服务实现
│ │ │ ├── converter/ # 对象转换器
│ │ │ │ └── BrandConverter.java
│ │ │ ├── dto/ # 数据传输对象
│ │ │ │ ├── admin/
│ │ │ │ │ ├── AdminBrandCreateDTO.java
│ │ │ │ │ └── AdminBrandUpdateDTO.java
│ │ │ │ └── api/
│ │ │ │ └── ApiBrandQueryDTO.java
│ │ │ └── vo/ # 视图对象
│ │ │ ├── admin/
│ │ │ │ └── AdminBrandVO.java
│ │ │ └── api/
│ │ │ └── ApiBrandVO.java
│ │ ├── domain/ # 领域层
│ │ │ ├── Brand.java # 领域实体
│ │ │ ├── dto/
│ │ │ │ └── BrandPageDTO.java # 领域查询 DTO
│ │ │ └── gateway/
│ │ │ └── BrandGateway.java # 网关接口（仓储抽象）
│ │ └── infrastructure/ # 基础设施层
│ │ ├── BrandGatewayImpl.java # 网关实现
│ │ ├── data/
│ │ │ └── BrandDO.java # 数据对象（DO）
│ │ └── mapper/
│ │ └── BrandMapper.java # MyBatis Mapper
│ │
│ ├── category/ # 分类聚合
│ ├── product/ # 商品聚合
│ ├── stock/ # 库存聚合
│ ├── search/ # 搜索聚合
│ └── infrastructure/ # 模块级基础设施
│ ├── es/ # Elasticsearch
│ │ ├── document/
│ │ │ └── ProductDocument.java
│ │ └── repository/
│ │ └── ProductDocumentRepository.java
│ └── mq/ # 消息队列
│ ├── CanalMessage.java
│ └── CanalProductConsumer.java
│
└── resources/
├── application.yml # 应用配置
├── bootstrap.yml # 引导配置
└── mapper/ # MyBatis XML（可选）
DDD 分层说明
| 层级 | 包名 | 职责 |
|---|---|---|
| 适配层 | adapter | 处理 HTTP 请求，参数校验，调用应用服务 |
| 应用层 | application | 编排业务流程，事务控制，DTO/VO 转换 |
| 领域层 | domain | 核心业务逻辑，领域实体，网关接口定义 |
| 基础设施层 | infrastructure | 数据库访问，外部服务调用，网关实现 |
2.2 vortmall-common（公共组件）
vortmall-common/
├── pom.xml
├── vortmall-common-cache/ # 缓存组件（Redis + Redisson）
│ └── src/main/java/.../cache/
│ └── config/
│ ├── CacheConfiguration.java
│ └── RedissonConfiguration.java
│
├── vortmall-common-core/ # 核心组件（基础类、工具类）
│ └── src/main/java/.../core/
│ ├── constant/ # 常量定义
│ │ ├── CommonConstant.java
│ │ ├── RegexConstant.java
│ │ └── ...
│ ├── dto/ # 通用 DTO
│ │ ├── BaseBatchEditDTO.java
│ │ ├── BasePageQueryDTO.java
│ │ └── ...
│ ├── exception/ # 异常定义
│ │ ├── BizException.java
│ │ └── GlobalExceptionCode.java
│ ├── utils/ # 工具类
│ │ ├── JsonUtils.java
│ │ └── StringUtils.java
│ └── vo/ # 通用 VO
│ ├── BaseVO.java
│ └── Paged.java
│
├── vortmall-common-datasource/ # 数据源组件（MyBatis-Plus）
│ └── src/main/java/.../datasource/
│ ├── config/
│ │ └── DatasourceConfiguration.java
│ ├── domain/entity/
│ │ └── BaseEntity.java # 基础实体
│ └── handler/
│ └── DataObjectHandler.java # 自动填充处理
│
├── vortmall-common-distribute_id/ # 分布式 ID 生成器
│ └── src/main/java/.../distributeId/
│ ├── config/
│ │ └── DistributeIdGenerator.java
│ └── enums/
│ └── ServiceCode.java
│
├── vortmall-common-emqx/ # EMQX MQTT 组件
├── vortmall-common-es/ # Elasticsearch 组件
├── vortmall-common-excel/ # Excel 导入导出
├── vortmall-common-job/ # XXL-JOB 定时任务
├── vortmall-common-lock/ # 分布式锁（Redisson）
├── vortmall-common-log/ # 日志组件（操作日志）
├── vortmall-common-mq/ # RocketMQ 消息队列
├── vortmall-common-nacos/ # Nacos 配置
├── vortmall-common-outbox/ # Outbox 模式（事务消息）
├── vortmall-common-sa-token/ # Sa-Token 认证
├── vortmall-common-seata/ # Seata 分布式事务
│
└── vortmall-common-web/ # Web 组件
└── src/main/java/.../web/
├── annotation/ # 自定义注解
├── auth/ # 认证授权
│ ├── annotation/
│ │ └── RequirePermission.java
│ ├── aspect/
│ │ └── PermissionAspect.java
│ ├── context/
│ │ ├── CurrentUser.java
│ │ └── UserContext.java
│ └── interceptor/
│ └── UserContextInterceptor.java
├── configuration/ # 配置类
│ ├── CorsConfig.java
│ ├── JacksonAutoConfiguration.java
│ ├── OpenApiConfig.java
│ └── WebConfiguration.java
├── handler/ # 全局处理器
│ ├── GlobalResponseAdvice.java
│ └── GlobalWebExceptionHandler.java
├── serializer/ # JSON 序列化
│ ├── LongToStringSerializer.java
│ └── StringToLongDeserializer.java
└── translate/ # 翻译功能
├── annotation/
│ └── JsonTranslate.java
└── TranslateSerializer.java
2.3 vortmall-feign（Feign 客户端）
微服务间调用的 Feign 客户端定义：
vortmall-feign/
├── pom.xml
├── vortmall-feign-common/ # Feign 公共配置
│ └── src/main/java/.../feign/common/
│ ├── FeignRequestInterceptor.java # 请求拦截器
│ └── FeignConfiguration.java
│
├── vortmall-feign-aftersales/ # 售后服务 Feign
├── vortmall-feign-decoration/ # 装修服务 Feign
├── vortmall-feign-distribution/ # 分销服务 Feign
├── vortmall-feign-file/ # 文件服务 Feign
├── vortmall-feign-logistics/ # 物流服务 Feign
├── vortmall-feign-marketing/ # 营销服务 Feign
├── vortmall-feign-message/ # 消息服务 Feign
├── vortmall-feign-order/ # 订单服务 Feign
├── vortmall-feign-organize/ # 组织服务 Feign
├── vortmall-feign-payment/ # 支付服务 Feign
├── vortmall-feign-product/ # 商品服务 Feign
├── vortmall-feign-system/ # 系统服务 Feign
└── vortmall-feign-user/ # 用户服务 Feign
└── src/main/java/.../feign/user/
├── client/ # Feign 接口
│ ├── MemberFeignClient.java
│ └── AdminUserFeignClient.java
├── dto/ # 传输对象
│ ├── MemberDTO.java
│ └── AdminUserDTO.java
├── fallback/ # 降级处理
│ ├── MemberFeignFallback.java
│ └── AdminUserFeignFallback.java
└── vo/ # 返回对象
└── AdminUserVO.java
2.4 vortmall-gateway（API 网关）
vortmall-gateway/
└── src/main/
├── java/com/vortmall/gateway/
│ ├── VortmallGatewayApplication.java # 启动类
│ ├── config/
│ │ └── GatewayConfiguration.java
│ └── filter/
│ └── AuthGlobalFilter.java # 认证过滤器
└── resources/
├── application.yml # 路由配置
└── bootstrap.yml
2.5 vortmall-auth（认证服务）
vortmall-auth/
└── src/main/
├── java/com/vortmall/auth/
│ ├── VortmallAuthApplication.java # 启动类
│ ├── adapter/ # 登录接口
│ │ ├── AdminLoginController.java # 管理端登录
│ │ └── ApiLoginController.java # 用户端登录
│ └── application/ # 登录逻辑
│ ├── AdminLoginServiceImpl.java
│ └── ApiLoginServiceImpl.java
└── resources/
├── application.yml
└── bootstrap.yml
三、其他目录
3.1 db（数据库脚本）
db/
├── vortmall_schema.sql # 完整建表脚本
├── migration/ # 数据迁移脚本
│ ├── convert_id_to_bigint.ps1
│ └── vortmall_full_*.sql
├── add_*.sql # 增量变更脚本
└── reset_data.sql # 数据重置脚本
3.2 deployment（部署配置）
deployment/
└── DockerCompose/
├── docker-compose.yml # Docker Compose 编排
├── start-core.sh # 启动脚本
├── mysql/ # MySQL 配置
│ ├── config/my.cnf
│ └── init/ # 初始化脚本
├── redis/ # Redis 配置
├── nacos/ # Nacos 配置
├── seata-server/ # Seata 配置
├── rocketMQ/ # RocketMQ 配置
├── xxl-job/ # XXL-JOB 配置
├── es/ # Elasticsearch 配置
├── logstash/ # Logstash 配置
├── kibana/ # Kibana 配置
├── sentinel/ # Sentinel 配置
├── canal/ # Canal 配置
└── skywalking/ # SkyWalking 配置
3.3 docs（项目文档）
docs/
├── README.md # 文档索引
├── 00_开发规范速查.md
├── 01_全局开发约束.md
├── 02_技术选型规范.md
├── 03_目录结构规范.md
├── 04_代码开发规范.md
├── 05_API设计规范.md
├── 06_数据库设计规范.md
├── 07_微服务拆分原则.md
├── 08_Git提交规范.md
├── 09_测试规范.md
├── 10_日志规范.md
├── 11_业务开发指南.md
├── 12_微服务迁移进度表.md
├── 13_模块迁移开发操作指南.md
├── 14_SpringCloudAlibaba2025.1.0升级指南.md
├── 微服务部署文档/
│ ├── VortMall快速上手指南.md
│ ├── VortMall微服务技术栈说明.md
│ ├── Docker部署指南.md
│ ├── 阿里云部署指南.md
│ └── 阿里云OSS对象存储指南.md
└── 数据库文档/
├── vortmall-product数据库文档.md
├── vortmall-order数据库文档.md
├── vortmall-user数据库文档.md
└── ...（每个服务一份）
四、命名规范
4.1 包命名
com.vortmall.{service}.{aggregate}.{layer}
示例：
com.vortmall.product.brand.adapter # 商品服务 - 品牌聚合 - 适配层
com.vortmall.order.order.domain # 订单服务 - 订单聚合 - 领域层
4.2 类命名
| 类型 | 命名规则 | 示例 |
|---|---|---|
| Controller | {端}+{聚合名}+Controller | AdminBrandController |
| Service接口 | {端}+{聚合名}+ServiceI | AdminBrandServiceI |
| Service实现 | {端}+{聚合名}+ServiceImpl | AdminBrandServiceImpl |
| 领域实体 | {聚合名} | Brand |
| Gateway接口 | {聚合名}+Gateway | BrandGateway |
| Gateway实现 | {聚合名}+GatewayImpl | BrandGatewayImpl |
| DO | {聚合名}+DO | BrandDO |
| DTO | {端}+{聚合名}+{动作}+DTO | AdminBrandCreateDTO |
| VO | {端}+{聚合名}+VO | AdminBrandVO |
| Mapper | {聚合名}+Mapper | BrandMapper |
| Converter | {聚合名}+Converter | BrandConverter |
端类型说明：
Admin- 管理端（商家后台）Api- 用户端（C 端）Panel- 运营端（平台管理）Pos- POS 端（收银系统）Feign- 内部调用（无端前缀）
五、模块依赖关系
┌─────────────────┐
│ vortmall-gateway│
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ vortmall-auth │ │ vortmall-biz │ │ ...其他服务 │
└───────┬───────┘ └───────┬───────┘ └───────────────┘
│ │
│ ├──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│vortmall-feign │◄──│vortmall-common│◄───────────│ vortmall-biz │
└───────────────┘ └───────────────┘ │ (其他) │
└───────────────┘
依赖方向：
- gateway → 各业务服务（路由转发）
- biz 服务 → feign（跨服务调用）
- biz 服务 → common（公共组件）
- auth → feign-user（用户认证）
六、快速定位指南
| 需求 | 定位路径 |
|---|---|
| 找某个接口 | vortmall-biz-{service}/{aggregate}/adapter/{端}Controller.java |
| 找业务逻辑 | vortmall-biz-{service}/{aggregate}/application/{端}ServiceImpl.java |
| 找数据库操作 | vortmall-biz-{service}/{aggregate}/infrastructure/{Aggregate}GatewayImpl.java |
| 找跨服务调用 | vortmall-feign/vortmall-feign-{service}/client/{聚合}FeignClient.java |
| 找公共工具 | vortmall-common/vortmall-common-core/utils/ |
| 找全局配置 | vortmall-common/vortmall-common-web/configuration/ |
| 找数据库脚本 | db/vortmall_schema.sql |
| 找部署配置 | deployment/DockerCompose/ |
