# mall

**Repository Path**: nidu/mall

## Basic Information

- **Project Name**: mall
- **Description**: 电商平台
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-04-22
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mall

mall 是一个基于 **Spring Cloud Alibaba** 的 DDD 微服务商城后端项目，采用 Alibaba COLA 4.3.2 分层架构、JDK 1.8、Spring Boot 2.7.18 构建。

本项目适合用作：

- Spring Cloud Alibaba 微服务脚手架参考。
- DDD/COLA 分层在微服务场景下的实践示例。
- AI 协作开发时的架构约束样板。
- 商城通用后台能力的二次开发基础。
- 配套前端代码：https://gitee.com/nidu/vue-admin-demo

## 文档导航

| 文档 | 说明 |
| --- | --- |
| [REQUIREMENT.md](REQUIREMENT.md) | 需求范围、业务能力、非功能需求和验收标准 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 模块职责、分层依赖、运行链路和横切设计 |
| [SKILL.md](SKILL.md) | 开发流程、编码步骤、排查清单和扩展规范 |
| [AGENTS.md](AGENTS.md) | 编码代理必须遵守的长期仓库规则 |
| [CLAUDE.md](CLAUDE.md) | Claude 兼容入口，内容与 `AGENTS.md` 保持一致 |
| [CHANGELOG.md](CHANGELOG.md) | 项目重要变更记录 |

## 技术栈

| 类别 | 技术 |
| --- | --- |
| 语言与框架 | JDK 1.8、Spring Boot 2.7.18、Spring Framework 5.3.x、Spring Security 5.8.x |
| 微服务 | Spring Cloud 2021.0.9、Spring Cloud Alibaba 2021.0.6.0 |
| 服务注册/发现 | Nacos 2.x |
| 配置中心 | Nacos Config |
| API 网关 | Spring Cloud Gateway |
| 服务调用 | Spring Cloud OpenFeign |
| 熔断限流 | Alibaba Sentinel |
| 架构组件 | Alibaba COLA 4.3.2 |
| 数据访问 | MySQL、Druid、MyBatis Plus |
| 缓存 | Spring Cache、Caffeine、Redis、Lettuce |
| 对象转换 | MapStruct、Lombok |
| 文档与工具 | Springdoc OpenAPI、Knife4j、Hutool、FastJSON2、EasyExcel |
| 文件存储 | 本地、MinIO、阿里云 OSS、腾讯云 COS |
| 第三方登录 | JustAuth |

## 业务域

| 服务 | 端口 | 业务能力 |
| --- | --- | --- |
| mall-system | 9004 | 用户、角色、菜单、部门、岗位、公司、租户、租户套餐、参数配置、字典、在线用户、权限、认证授权、OAuth2、社交登录、基础设施（文件、短信、邮件、站内信、日志）|
| mall-member | 9001 | 会员用户、会员等级、会员分组、会员标签、会员地址、会员积分、签到、经验值 |
| mall-product | 9002 | 商品 SPU/SKU、商品分类、品牌、属性、商品评论、收藏、浏览历史 |
| mall-trade | 9005 | 购物车、订单、售后、物流、佣金分销 |
| mall-promotion | 9003 | 满减活动、积分商城、拼团、文章、客服消息、横幅 |
| mall-gateway | 9000 | API 网关：统一路由、RPC 路径拦截、跨域 |

## 模块结构

每个业务服务采用相同的 COLA 分层结构，以 `mall-system` 为例：

```text
mall
├── mall-common                        # 公共模块
│   ├── mall-common-domain             # 通用领域基础类型
│   └── mall-common-infrastructure     # 通用 Web/安全/缓存/MyBatis 基础设施
│
├── mall-gateway                       # API 网关（Spring Cloud Gateway）
│
├── mall-system                        # 认证与系统管理服务
│   ├── mall-system-client             # API 契约、Cmd/Qry/CO、RPC Feign 接口
│   ├── mall-system-adapter            # HTTP Controller（admin-api / app-api / rpc-api）
│   ├── mall-system-app                # 应用编排：CmdExe、QryExe、事务、事件
│   ├── mall-system-domain             # 领域核心：Entity、DomainService、Gateway 接口
│   ├── mall-system-infrastructure     # 技术实现：GatewayImpl、Mapper、DO、Convertor
│   └── mall-system-start              # 启动类、配置、SQL 脚本、i18n
│
├── mall-member                        # 会员服务（同上 COLA 分层）
├── mall-product                       # 商品服务
├── mall-trade                         # 交易服务
└── mall-promotion                     # 营销服务
```

分层依赖遵循：

```text
adapter -> app -> domain <- infrastructure
client  -> 被 adapter / app / infrastructure 引用
common  -> 被所有模块引用
start   -> 组装所有模块并启动应用
```

## 接口前缀

| 前缀 | 用途 | Controller 包 |
| --- | --- | --- |
| `/admin-api/v1` | 管理后台接口 | `com.nidu.mall.web.**`（各服务）|
| `/app-api/v1` | App/Open API 接口 | `com.nidu.mall.app.**`（各服务）|
| `/rpc-api/v1` | 微服务内部 RPC 接口 | `com.nidu.mall.rpc.**`（各服务）|

> `/rpc-api/v1/**` 不在网关路由表中，前端无法访问；其他服务通过 Feign + Nacos 直连调用。

## 快速启动

### 环境要求

| 组件 | 版本 |
| --- | --- |
| JDK | 1.8 |
| Maven | 3.6+ |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| Nacos | 2.x（必须先启动） |

### 1. 启动 Nacos

```bash
# 单机模式启动
nacos/bin/startup.cmd -m standalone
# 访问：http://localhost:8848/nacos  默认账号 nacos/nacos
```

### 2. 初始化数据库

```sql
CREATE DATABASE mall DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

依次执行各服务的 SQL 脚本（位于各服务的 `*-start/src/main/resources/db/` 目录）：

```text
mall-system-start/src/main/resources/db/initial.sql
mall-system-start/src/main/resources/db/mall_system.sql
mall-member-start/src/main/resources/db/mall_member.sql
```

### 3. 检查配置

主配置文件位于各服务的 `*-start/src/main/resources/application.yml`。

关键默认配置（以 mall-system 为例）：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mall
    username: root
    password: 123456
  redis:
    host: localhost
    port: 6379
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
```

### 4. 编译与启动

按依赖顺序启动（mall-common 先安装，再启动各业务服务，最后启动网关）：

```bash
# 安装公共模块
mvn -pl mall-common -am install -DskipTests

# 编译指定服务
mvn -pl mall-system/mall-system-start -am compile -DskipTests

# 启动指定服务
mvn -pl mall-system/mall-system-start -am spring-boot:run
```

或打包后运行：

```bash
mvn clean package -DskipTests
java -jar mall-system/mall-system-start/target/mall-system-start-0.0.1.jar
```

### 5. 访问

各服务 API 文档（Knife4j）：

| 服务 | 文档地址 |
| --- | --- |
| mall-gateway | http://localhost:9000 |
| mall-system | http://localhost:9004/doc.html |
| mall-member | http://localhost:9001/doc.html |
| mall-product | http://localhost:9002/doc.html |
| mall-trade | http://localhost:9005/doc.html |
| mall-promotion | http://localhost:9003/doc.html |

## 开发约定摘要

- 必须兼容 JDK 1.8，不使用 Java 9+ 语法或 API。
- Controller 只处理 HTTP 入参、鉴权上下文和响应转换，不写业务逻辑。
- App 层 `*CmdExe` 和 `*QryExe` 负责用例编排，多个写操作的事务边界放在 App 层。
- Domain 层表达核心业务规则，只通过 Gateway 接口访问外部能力。
- Infrastructure 层负责数据库、缓存、文件存储、外部系统和安全框架集成。
- RPC 接口（`@FeignClient`）定义在提供方的 `*-client` 模块；调用方引入该模块即可注入使用。
- RPC 控制器位于 `rpc.*` 包，使用显式路径 `/rpc-api/v1/**`，不走 API 前缀自动注入。
- 业务异常使用 `BizException`，错误码维护在 `ErrorCodeConstants`。
- 对象转换优先使用 MapStruct `*Convertor`。

完整规则见 [AGENTS.md](AGENTS.md)、[SKILL.md](SKILL.md) 和 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 常用命令

```bash
# 编译单个服务及其依赖
mvn -pl mall-system/mall-system-start -am compile -DskipTests

# 启动单个服务
mvn -pl mall-system/mall-system-start -am spring-boot:run

# 全量打包
mvn clean package -DskipTests

# 检查空白问题
git diff --check
```

## 许可

本项目使用 [MIT License](LICENSE)。