# ddd

**Repository Path**: wei_ha/ddd

## Basic Information

- **Project Name**: ddd
- **Description**: QiFeng DDD QiFeng DDD 是一个基于 领域驱动设计（DDD） 思想构建的权限管理系统，采用清晰的分层架构和模块化设计。项目不仅实现了完整的 RBAC 权限模型，还创新性地引入了动态权限规则引擎，支持基于 SpEL 表达式 的细粒度数据级权限控制
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QiFeng DDD - 基于领域驱动设计的权限管理系统

<div align="center">

**DDD 架构实践 · 动态数据级权限 · 高性能缓存**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-17+-green.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.10-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Stars](https://img.shields.io/github/stars/yourusername/qiufeng-ddd?style=social)](https://github.com/yourusername/qiufeng-ddd)

[⚡ 快速开始](#-快速开始) • [🔥 核心特性](#-核心特性) • [📖 API文档](#-api-接口)

</div>

---

## 💡 项目简介

  QiFeng DDD QiFeng DDD 是一个基于 **领域驱动设计（DDD）** 思想构建的权限管理系统，采用清晰的分层架构和模块化设计。项目不仅实现了完整的 **RBAC 权限模型**，还创新性地引入了动态权限规则引擎，支持基于 **SpEL 表达式** 的细粒度数据级权限控制。

**核心价值**：
- 🏗️ **DDD 最佳实践**：清晰的聚合根、实体、值对象划分
- 🔐 **三层权限防护**：URL级 + 方法级 + 数据级
- ⚡ **毫秒级响应**：Caffeine + Redis 二级缓存
- 🎯 **配置化权限**：通过 SpEL 表达式实现细粒度控制，无需修改代码
- 🏢 **多租户隔离**：基于 MyBatis-Plus 插件的自动数据隔离，支持 SaaS 模式
- 📚 **在线 API 文档**：集成 Knife4j，自动生成接口文档，支持在线调试

---

## ⚡ 快速开始

### 前置要求

在开始之前，请确保已安装并启动以下服务：

- **MySQL 8.0+**：关系型数据库
- **Redis 6.0+**：缓存数据库

### 方式一：Docker Compose（推荐）

```bash
git clone https://gitee.com/mssng/ddd.git
cd qiufeng-ddd
docker-compose up -d
```

访问 http://localhost:8091/doc.html  
<img src="docs/images/img.png" />
默认账号：`master` / `Qq123456`

**前端项目地址**：https://gitee.com/mssng/dome.git

**API 文档**：http://localhost:8091/doc.html

### 方式二：本地运行

**1. 准备数据库**

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE qiufeng_ddd DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

# 导入表结构
mysql -u root -p qiufeng_ddd < docs/db/schema.sql

# 导入初始数据
mysql -u root -p qiufeng_ddd < docs/db/data.sql
```

**2. 配置 Redis**

确保 Redis 服务已启动：
```bash
# Linux/Mac
redis-server

# Windows (如果安装了 Redis)
redis-server.exe
```

**3. 修改配置文件**

编辑 `qiufeng-ddd-trigger/src/main/resources/application-dev.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/qiufeng_ddd?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password  # 修改为你的 MySQL 密码
  
  data:
    redis:
      host: localhost
      port: 6379
      password:  # 如果 Redis 有密码，在此填写
```

**4. 启动项目**

```bash
mvn spring-boot:run -pl qiufeng-ddd-trigger
```

---

## 🔥 核心特性

### 1️⃣ 动态数据级权限

**传统方式**：
```java
// 每个接口都要写 if-else
if (!order.getUserId().equals(currentUserId)) {
    throw new ForbiddenException();
}
```

**QiFeng DDD**：
```java
// 一行注解搞定，规则配置在数据库
@PreAuthorize("hasPermission('order:view')")
public Order getOrder(@PathVariable String orderId) { ... }
```

配置示例：
```sql
INSERT INTO permission_rule 
VALUES (10, '#order.userId == #currentUserId', 'DATA_SCOPE');
```

### 2️⃣ 高性能二级缓存

```
L1: Caffeine (< 1ms, 命中率 ~95%)
 ↓
L2: Redis (~5ms, 命中率 ~99%)
 ↓
DB (~50ms)
```

- 🚀 99% 请求在 1ms 内响应
- 🔄 权限变更 < 100ms 全网同步
- 📈 支撑 1000+ QPS

### 3️⃣ 三层权限防护

| 层级 | 实现 | 说明 |
|------|------|------|
| URL级 | DynamicAuthorizationFilter | 自动拦截所有请求 |
| 方法级 | @PreAuthorize | SpEL 表达式 |
| 数据级 | PermissionRule | 动态规则引擎 |

### 4️⃣ 在线用户管理

- 👥 实时查看在线用户
- 🚫 强制用户下线
- 🔒 Token 黑名单机制

### 5️⃣ 登录日志审计

- 📝 完整记录登录/登出
- 🌍 IP 地理位置解析
- 🔍 失败追踪

### 6️⃣ 多租户数据隔离

- 🏢 **自动隔离**：MyBatis-Plus 租户插件自动添加 `tenant_id` 过滤条件
- 🔑 **JWT 携带**：Token 中包含租户ID，请求时自动提取
- 🛡️ **框架层保护**：无需手动编写租户过滤逻辑，避免数据泄露
- ⚡ **高性能**：雪花算法生成全局唯一租户ID，支持分布式部署

```java
// 开发者只需关注业务逻辑，租户过滤由框架自动处理
@PreAuthorize("hasPermission('dept:query')")
@GetMapping("/depts")
public List<Dept> getDepts() {
    // SQL 自动添加 WHERE tenant_id = 100
    return deptRepository.findAll();
}
```

---

## 🏗️ 技术栈

| 技术 | 用途 |
|------|------|
| Spring Boot 3.2 | 基础框架 |
| Spring Security 6 | 安全认证 |
| MyBatis-Plus | ORM + **租户插件** |
| Redis + Caffeine | 二级缓存 |
| JWT | Token 认证（**携带租户ID**） |
| MySQL 8.0 | 数据库 |
| Snowflake | **分布式 ID 生成** |
| **Knife4j** | **API 文档（OpenAPI 3.0）** |

---

## 📂 项目结构

```
qiufeng-ddd/
├── qiufeng-ddd-domain          # 领域层 ⭐
│   ├── model/                  # 领域模型（聚合根、实体、值对象）
│   │   ├── auth/              # 认证领域
│   │   ├── user/              # 用户领域
│   │   ├── role/              # 角色领域
│   │   ├── permission/        # 权限领域
│   │   ├── menu/              # 菜单领域
│   │   ├── company/           # 公司/租户领域
│   │   └── dept/              # 部门领域
│   ├── service/               # 领域服务
│   └── event/                 # 领域事件
│
├── qiufeng-ddd-app             # 应用服务层
│   ├── command/               # 命令对象（写操作）
│   ├── query/                 # 查询对象（读操作）
│   ├── dto/                   # 应用层 DTO
│   ├── assembler/             # 对象转换器
│   └── service/               # 应用服务（协调领域对象）
│
├── qiufeng-ddd-infrastructure  # 基础设施层
│   ├── persistence/           # 持久化实现
│   │   ├── repository/        # Repository 实现
│   │   └── po/                # 持久化对象
│   ├── mapper/                # MyBatis Mapper
│   ├── security/              # Spring Security 配置
│   │   ├── filter/            # 安全过滤器
│   │   ├── handler/           # 认证/授权处理器
│   │   └── expression/        # SpEL 表达式扩展
│   ├── config/                # 基础设施配置
│   │   ├── TenantContextFilter.java    # 租户上下文过滤器
│   │   ├── MyBatisPlusConfig.java      # MyBatis-Plus 配置（含租户插件）
│   │   └── JwtTokenUtil.java           # JWT 工具类
│   ├── redis/                 # Redis 缓存实现
│   ├── gateway/               # 外部服务网关
│   └── event/                 # 事件发布实现
│
├── qiufeng-ddd-trigger         # 触发器层（Controller）
│   ├── controller/            # REST API 控制器
│   ├── assembler/             # DTO 转换器
│   ├── config/                # Web 配置
│   ├── exception/             # 全局异常处理
│   ├── job/                   # 定时任务
│   └── listener/              # 事件监听器
│
├── qiufeng-ddd-api             # API 定义层
│   └── dto/
│       ├── request/           # 请求 DTO
│       └── response/          # 响应 DTO
│
└── qiufeng-ddd-types           # 通用类型层
    ├── base/                  # 基础类（分页、响应等）
    ├── config/                # 通用配置
    │   └── TenantContext.java # 租户上下文管理器
    ├── util/                  # 工具类
    │   ├── JwtTokenUtil.java  # JWT 工具（增强版，携带租户ID）
    │   └── AesUtil.java       # AES 加密工具
    ├── exception/             # 通用异常
    ├── enums/                 # 枚举定义
    ├── event/                 # 通用事件
    └── query/                 # 通用查询对象
```

---

## 📖 API 接口

**📚 在线文档**：项目已集成 **Knife4j**，启动后访问 http://localhost:8091/doc.html 即可查看完整的 API 文档，支持在线调试。

**认证管理**：系统用户登录、登出、Token 刷新等认证功能，支持在线用户管理和强制下线。

**用户管理**：系统操作者管理，包括用户创建、修改、删除、查询，以及用户状态控制和密码重置。

**角色管理**：角色权限分配与管理，支持为角色分配菜单和按钮权限，设置数据范围权限划分。

**权限管理**：系统权限配置，包括菜单权限、按钮权限、API 接口权限的增删改查，树形结构展示。

**菜单管理**：系统菜单配置，包括菜单层级、路由、图标、排序等，支持菜单权限标识绑定。

**权限规则**：动态权限规则配置，基于 SpEL 表达式实现数据级权限控制，支持规则启用/禁用。

**登录日志**：用户登录行为审计，记录登录时间、IP 地址、地理位置、浏览器信息等，支持查询统计。

### 快速示例

```bash
# 登录获取 Token
POST /api/auth/login
{
  "username": "master",
  "password": "Qq123456"
}

# 使用 Token 访问受保护接口
GET /api/auth/current-user
Authorization: Bearer {token}

# 获取用户列表
GET /api/users/list?pageNum=1&pageSize=10

# 创建角色并分配权限
POST /api/roles
{
  "roleName": "管理员",
  "roleKey": "master"
}
POST /api/roles/{roleId}/permissions
{
  "permissionIds": [1, 2, 3]
}
```

更多接口详见：[API 完整文档](docs/API接口文档.md)

**相关文档**：
- [多租户自动隔离方案使用说明](docs/多租户自动隔离方案使用说明.md)

---

## 🎯 适用场景

- ✅ **个人项目**：学习 DDD 架构设计、Spring Security 最佳实践
- ✅ **企业级应用**：权限系统开发、SaaS 多租户系统开发
- ✅ **高并发场景**：缓存方案参考、性能优化实践
- ✅ **面试准备**：项目经验积累、技术亮点展示

---

## 🌟 支持项目

如果这个项目对你有帮助，欢迎：

- ⭐ Star 项目
- 🍴 Fork 二次开发
- 🐛 提交 Issue
- 🔧 提交 PR

### ☕ 请作者喝杯咖啡

如果这个项目帮助到了你，可以考虑请作者喝杯咖啡，支持持续更新和维护！

<div align="center">

|                        微信支付                         |                       支付宝                       |
|:---------------------------------------------------:|:-----------------------------------------------:|
| <img src="docs/images/wechat-pay.jpg" width="200"/> | <img src="docs/images/alipay.jpg" width="200"/> |

**感谢每一位支持者！** 🙏

</div>

---

## 📄 开源协议

[Apache License 2.0](LICENSE)

---

<div align="center">

**Made with ❤️ by houyuhuai**

[↑ 返回顶部](#-qiufeng-ddd---企业级权限管理系统)

</div>