# delight

**Repository Path**: angeryfeather/delight

## Basic Information

- **Project Name**: delight
- **Description**: kotlin+springboot
- **Primary Language**: Kotlin
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-02-01
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Delight — 企业级 RBAC 后台脚手架

Delight 是一套**开箱即用的企业级后台管理系统脚手架**，后端基于 **Kotlin + Spring Boot 3.2** 构建，提供完整的 RBAC（基于角色的访问控制）权限体系、JWT 无状态认证、操作审计日志等核心能力。前端工程（React + TDesign）可配套使用，快速搭建管理后台。

---

## 1. 项目环境要求

| 环境依赖     | 版本要求          | 说明                              |
|-------------|-------------------|----------------------------------|
| **JDK**     | 17+               | 项目使用 Java 17 编译              |
| **Kotlin**  | 2.1.x             | 通过 Gradle 插件自动管理            |
| **Gradle**  | 8.14+             | 使用 Gradle Wrapper，无需手动安装   |
| **PostgreSQL** | 14+           | 主数据库，生产/开发环境使用          |
| **Redis**   | 6.0+（可选）       | 仅在使用分布式缓存时需要             |

> **提示**：项目内置 Gradle Wrapper（`gradlew`），首次运行会自动下载指定版本的 Gradle，**无需手动安装 Gradle**。

---

## 2. 项目架构

### 2.1 模块划分

Delight 后端采用 **Gradle 多模块** 工程结构，按领域职责拆分为 1 个主应用模块 + 5 个核心基础模块：

```
backend/
├── buildSrc/                         # Gradle 约定插件（Convention Plugins）
│   └── src/main/kotlin/
│       ├── delight.kotlin-common-conventions.gradle.kts    # 公共约定（Kotlin + Spring Boot）
│       ├── delight.kotlin-library-conventions.gradle.kts   # 库模块约定
│       ├── delight.kotlin-web-conventions.gradle.kts       # Web 模块约定
│       └── delight.kotlin-database-conventions.gradle.kts  # 数据库模块约定
│
├── core/                             # 核心基础模块（不包含业务逻辑）
│   ├── delight-common/               # 公共模块：统一返回体、分页、异常定义
│   ├── delight-cache/                # 缓存模块：Caffeine 本地缓存 / Redis 分布式缓存
│   ├── delight-jdbc/                 # 数据模块：雪花 ID 自动生成、JDBC 回调
│   ├── delight-security/             # 安全模块：Spring Security + JWT 认证鉴权
│   └── delight-web/                  # Web 基座：Controller/Service 基类、全局异常处理
│
└── system/                           # 主应用模块（Spring Boot 入口）
    └── src/main/kotlin/com/delight/system/
        ├── SystemApplication.kt      # 应用启动类
        ├── application/              # 应用服务层
        ├── domain/
        │   ├── entity/system/        # 领域实体（User, Role, Permission 等 9 张表）
        │   ├── repository/system/    # 数据仓库接口（Spring Data JDBC）
        │   └── service/              # 领域服务（RBACService）
        ├── infrastructure/
        │   ├── aop/                  # AOP 切面（操作日志自动记录）
        │   ├── cache/                # 缓存辅助工具
        │   ├── config/               # 配置（CORS、文件上传、Flyway、WebMvc）
        │   └── persistence/security/ # 安全持久化实现
        └── interfaces/web/system/    # 对外接口层（REST Controller + DTO）
```

### 2.2 分层架构

项目遵循 **DDD 分层架构**，各层职责清晰：

```
┌─────────────────────────────────────────────┐
│           interfaces/web/                    │  ← 接口层：Controller + DTO
│   (接收 HTTP 请求、参数校验、权限注解)           │
├─────────────────────────────────────────────┤
│           application/                       │  ← 应用服务层：编排领域服务
│   (认证服务 AuthenticationService)             │
├─────────────────────────────────────────────┤
│           domain/                            │  ← 领域层：核心业务逻辑
│   ├── entity/    领域实体                     │
│   ├── repository/  数据仓库接口               │
│   └── service/   领域服务 (RBACService)       │
├─────────────────────────────────────────────┤
│           infrastructure/                    │  ← 基础设施层
│   ├── aop/      操作日志切面                  │
│   ├── cache/    缓存实现                      │
│   ├── config/   配置（Flyway、CORS、文件上传）  │
│   └── persistence/  安全持久化                │
└─────────────────────────────────────────────┘
```

### 2.3 技术栈概览

| 层次       | 技术选型                                                 |
|------------|--------------------------------------------------------|
| **语言**   | Kotlin 2.1                                              |
| **框架**   | Spring Boot 3.2.0                                       |
| **持久层** | Spring Data JDBC（非 JPA，更轻量可控）                    |
| **数据库** | PostgreSQL（生产/开发） / H2（测试）                      |
| **迁移**   | Flyway 10.x                                             |
| **安全**   | Spring Security 6.x + JJWT 0.11.x（无状态 JWT）          |
| **缓存**   | Caffeine（本地） / Redis（分布式），通过配置切换            |
| **工具库** | Hutool 5.8（验证码、雪花 ID、通用工具）                    |
| **日志**   | Logback + Spring Profiles（按环境输出）                   |
| **构建**   | Gradle 8.14 + Version Catalog + 约定插件                  |

### 2.4 数据库模型（ER 概要）

```
sys_user ──< sys_user_role >── sys_role ──< sys_role_permission >── sys_permission
    │                                                                   │
    └── sys_department                                       parent_id (自引用树)
                                                                        │
                                                              resource_type: MENU / BUTTON / API
sys_dict_type ──< sys_dict_data
sys_operation_log (审计日志)
```

核心 RBAC 五表：**用户 → 用户角色关联 → 角色 → 角色权限关联 → 权限**。权限支持三级资源类型（菜单 / 按钮 / API），通过 `parent_id` 自引用形成树形结构。

### 2.5 API 端点一览

所有接口统一前缀 `/{context-path}/system/`，除登录接口外均受 `@PreAuthorize` 权限注解保护。

| 控制器                    | 核心接口                                                       |
|---------------------------|---------------------------------------------------------------|
| **LoginController**       | 登录、验证码获取                                                |
| **UserController**        | 用户 CRUD、密码修改、按用户名查询                                 |
| **RoleController**        | 角色 CRUD、角色权限绑定/查询                                     |
| **PermissionController**  | 权限 CRUD、权限树查询                                           |
| **DepartmentController**  | 部门 CRUD、部门树、根节点查询                                    |
| **DictTypeController**    | 字典类型 CRUD                                                  |
| **DictDataController**    | 字典数据 CRUD、按类型查询                                       |
| **OperationLogController**| 操作日志查询、删除                                              |
| **DashboardController**   | 首页统计（用户数、角色数等）                                     |
| **RolePermissionController** | 角色-权限关联 CRUD                                           |
| **UserRoleController**    | 用户-角色关联 CRUD                                              |

---

## 3. 架构优点

### 3.1 约定优于配置 — Gradle 约定插件

通过 `buildSrc` 中的 4 个约定插件，将通用的构建配置（Kotlin 编译参数、Spring Boot 依赖、测试框架等）抽取为可复用的 Gradle 脚本。新增模块只需一行 `plugins { id("delight.kotlin-xxx-conventions") }` 即可继承全套配置，**消除重复、降低维护成本**。

### 3.2 多模块按需组合

`core/` 下的每个模块职责单一、边界清晰：

- **不需要缓存的模块**可以不依赖 `delight-cache`
- **不需要安全认证的模块**可以不依赖 `delight-security`
- **不需要数据库的模块**可以不依赖 `delight-jdbc`

模块间的依赖关系是**单向、无环**的，避免了"大泥球"式的混乱依赖。

### 3.3 DDD 分层 — 关注点分离

接口层（`interfaces`）、应用层（`application`）、领域层（`domain`）、基础设施层（`infrastructure`）四层分明：

- 业务逻辑集中在 `domain/`，不依赖任何框架细节
- 基础设施实现（缓存、日志、安全）与业务代码隔离
- 修改某层不影响其他层，降低变更风险

### 3.4 双模缓存 — 灵活适配部署场景

通过配置项 `cache.type` 一行切换：

| 模式       | 适用场景                       |
|------------|-------------------------------|
| **Caffeine**（默认） | 单节点部署，零外部依赖，毫秒级响应 |
| **Redis**           | 多节点集群部署，缓存数据跨实例共享 |

`CacheService` 接口统一抽象，业务代码无需感知底层实现。

### 3.5 Spring Data JDBC — 更轻量的持久层

相比 JPA/Hibernate，Spring Data JDBC：

- **无懒加载陷阱**：实体即普通对象，不存在 Session 延迟加载问题
- **无脏写风险**：每次 save 都是全量保存，不依赖"托管态"跟踪
- **SQL 可控**：复杂查询通过 `@Query` 直接写 SQL，不会被自动生成的 SQL 拖累性能
- **概念简单**：学习成本远低于 JPA，团队上手更快

### 3.6 雪花 ID — 分布式友好

通过 Hutool 的 Snowflake 算法 + `BeforeConvertCallback` 自动为所有实体生成全局唯一 ID：

- 无需数据库自增序列，避免分库分表时的 ID 冲突
- 对业务代码完全透明，开发者无需手动设置 ID

### 3.7 Flyway 数据库迁移 — 版本化管理

所有 DDL 和初始数据由 Flyway 脚本统一管理：

- 开发和生产的迁移脚本分离（`db/migration/dev/` 和 `db/migration/prod/`）
- 多环境激活策略灵活：通过 `spring.flyway.locations` 按 profile 指定
- 新建环境一键初始化：启动应用即可自动完成建表 + 灌入种子数据

### 3.8 操作日志 — AOP 零侵入审计

通过自定义 `@Log` 注解 + `OperationLogAspect` 切面，自动记录：

- 操作人、IP 地址
- 请求参数、方法名
- 执行耗时
- 操作结果（成功/失败）

业务代码只需在 Controller 方法上加 `@Log` 注解即可，零侵入、无感知。

### 3.9 统一响应格式

所有 API 返回体统一为 `ReturnData<T>` 结构：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": { ... },
  "page": { "pageNum": 1, "pageSize": 10, "total": 100 }
}
```

前端只需对接一套数据结构，降低沟通成本和解析错误。

### 3.10 无状态认证 — 天然支持水平扩展

基于 JWT 的无状态认证：

- **Session 零依赖**：无需服务端存储会话，天然支持多实例负载均衡
- **安全性**：RSA 非对称加密签名（`app.key` / `app.pub`），Token 无法伪造
- **细粒度鉴权**：`@PreAuthorize("hasAuthority('...')")` 精确到按钮/API 级别

---

## 4. 配套前端

> 前端工程位于 `frontend/` 目录，基于 **React + TDesign** 构建，提供完整的后台管理界面，与后端 RBAC 权限体系无缝对接。前端仅作为配套参考实现，可根据需求替换为 Vue、Angular 等任意前端框架。

---

## 5. 快速开始

### 5.1 克隆项目

```bash
git clone https://gitee.com/angeryfeather/delight.git
cd delight/backend
```

### 5.2 准备数据库

确保 PostgreSQL 已启动，创建数据库：

```sql
CREATE DATABASE delight;
```

### 5.3 修改配置

编辑 `system/src/main/resources/application-dev.yaml`，将数据库连接信息修改为自己的：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/delight
    username: your_username
    password: your_password
```

### 5.4 启动应用

```bash
# Windows
gradlew.bat :system:bootRun

# Linux / macOS
./gradlew :system:bootRun
```

应用启动后，Flyway 会自动执行数据库迁移并灌入初始数据。访问 `http://localhost:8080/delight-system` 即可。

### 5.5 默认账号

| 用户名  | 密码       | 角色          |
|---------|-----------|---------------|
| admin   | admin@123 | super_admin   |

---

## 6. 项目结构速查

| 配置项               | 位置                                                               |
|----------------------|--------------------------------------------------------------------|
| Gradle 版本目录      | [backend/gradle/libs.versions.toml](backend/gradle/libs.versions.toml)     |
| 多模块设置           | [backend/settings.gradle.kts](backend/settings.gradle.kts)                 |
| 约定插件             | [backend/buildSrc/src/main/kotlin/](backend/buildSrc/src/main/kotlin/)      |
| 应用配置             | [backend/system/src/main/resources/application.yaml](backend/system/src/main/resources/application.yaml) |
| 开发环境配置         | [backend/system/src/main/resources/application-dev.yaml](backend/system/src/main/resources/application-dev.yaml) |
| JWT 配置             | [backend/core/delight-security/src/main/resources/application.yml](backend/core/delight-security/src/main/resources/application.yml) |
| 数据库迁移脚本       | [backend/system/src/main/resources/db/migration/dev/](backend/system/src/main/resources/db/migration/dev/) |
| 日志配置             | [backend/system/src/main/resources/logback-spring.xml](backend/system/src/main/resources/logback-spring.xml) |
| 启动类               | [backend/system/src/main/kotlin/com/delight/system/SystemApplication.kt](backend/system/src/main/kotlin/com/delight/system/SystemApplication.kt) |

---

## 7. 参与贡献

1. Fork 本仓库
2. 新建分支：`git checkout -b feat/your-feature`
3. 提交代码：`git commit -m 'feat: add some feature'`
4. 推送分支：`git push origin feat/your-feature`
5. 新建 Pull Request

---

## License

[MIT License](LICENSE)