# yy-server

**Repository Path**: jankinliu/yy-server

## Basic Information

- **Project Name**: yy-server
- **Description**: 基于java21、springboot3.4、gradle，采用最前沿技术。一款追求极致代码编写的单体项目后端框架，简化各种样板代码，能自动化的决不手写、能一行代码解决的决不写10行。内置权限管理、代码生成、文件管理。以及各种简化开发的封装。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://yy.lyyn.top:4/
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Gradle, Java, SpringBoot, 后台管理系统

## README

# YY Server

基于 Spring Boot 的模块化后端单体项目，在线演示：https://yy.lyyn.top:4/ 演示账号:`guest`/`123456`

## 📋 项目简介

YY Server 是一个采用模块化设计的企业级后端服务系统，提供完整的用户管理、权限控制、文件存储、系统监控等功能。项目采用现代化的技术栈，具有高可扩展性和可维护性。

## ✨ 核心特性

- 🏗️ **模块化架构**：基于 Gradle 的多模块项目结构，业务模块解耦
- 🔐 **完善的权限体系**：基于 Sa-Token 的认证授权，支持角色-部门-岗位多维度权限控制
- 📦 **对象存储服务**：集成 MinIO，支持公共/私有文件管理
- 📊 **系统监控**：操作日志、登录日志、在线用户监控
- 🔒 **接口加密**：支持 API 请求/响应加密，保障数据安全
- 🌐 **国际化支持**：内置中英文国际化资源
- 📱 **SSE 推送**：支持服务端事件推送
- 📄 **API 文档**：集成 Knife4j/Swagger，提供完善的接口文档
- 🔄 **社交登录**：支持 Gitea、MaxKey、TopIAM 等第三方登录
- ✉️ **消息通知**：集成邮件、短信发送功能

## 🛠️ 技术栈

### 核心框架

- **Java 21**：JDK 版本
- **Spring Boot3.4+**：核心框架
- **Gradle Kotlin**：构建工具
- **MySQL 8.4.4**：数据库

### 主要依赖

- **MyBatis Plus**：持久层框架
- **Sa-Token**：认证授权框架
- **Redis**：缓存中间件
- **Druid**：数据库连接池
- **MinIO**：对象存储
- **Hutool**：Java 工具类库
- **Knife4j**：API 文档增强工具
- **FastExcel**：Excel 处理
- **Caffeine**：本地缓存

## 📁 项目结构

```
yy-server/
├── application/          # 应用启动模块
│   ├── src/main/java/   # 启动类
│   └── src/main/resources/  # 配置文件、国际化资源
├── business/            # 业务模块
│   └── src/main/java/   # 业务枚举、领域模型
├── common/              # 通用组件集
│   ├── common-core/     # 核心工具类、常量、异常处理
│   ├── common-crypto/   # 加密解密组件
│   ├── common-doc/      # Swagger 文档配置
│   ├── common-excel/    # Excel 导入导出
│   ├── common-json/     # JSON 处理（Jackson）
│   ├── common-log/      # 日志记录
│   ├── common-mail/     # 邮件发送
│   ├── common-mybatis/  # MyBatis 增强配置
│   ├── common-redis/    # Redis 缓存服务
│   ├── common-security/ # 安全认证组件
│   ├── common-sms/      # 短信发送
│   ├── common-social/   # 第三方社交登录
│   ├── common-spring/   # Spring 扩展工具
│   ├── common-sse/      # SSE 推送服务
│   ├── common-util/     # 通用工具类
│   ├── common-validation/ # 参数校验
│   └── common-web/      # Web 层配置、异常处理
├── module/              # 功能模块
│   ├── object-storage/ # 对象存储模块
│   └── system/         # 系统管理模块
└── build.gradle.kts    # 根项目构建配置
```

## 🚀 快速开始

### 环境要求

- JDK 21+
- MySQL 8.0+
- Redis 6.0+
- MinIO（可选，用于文件存储）

### 配置环境变量

注意 [application-env.yml](application/src/main/resources/application-env.yml) 需要配合环境变量文件 [.env](.env) 使用：

环境变量文件 `.env` 示例：
```yaml
# 主机地址
HOST=localhost

# MySQL 配置
MYSQL_PORT=3306
MYSQL_DATABASE=yy_server
MYSQL_USERNAME=root
MYSQL_PASSWORD=your_password

# Redis 配置
REDIS_PASSWORD=your_redis_password

# MinIO 配置
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESSKEY=your_access_key
MINIO_SECRETKEY=your_secret_key

# Sa-Token JWT 密钥
SA_TOKEN_JWT_SECRET_KEY=your_jwt_secret

# API 加密密钥
API_CRYPTO_PUBLIC_KEY=your_public_key
API_CRYPTO_PRIVATE_KEY=your_private_key
```
### 初始化数据库
[mysql-init.sql](script/sql/mysql-init.sql)

### 启动项目

1. **克隆项目**

```bash
git clone https://gitee.com/jankinliu/yy-server.git
cd yy-server
```

2. **构建项目**

```bash
# Windows
./gradlew.bat build

# Linux/Mac
./gradlew build
```

3. **运行项目**

```bash
# Windows
./gradlew.bat bootRun

# Linux/Mac
./gradlew bootRun
```

或直接`IDEA`运行 `Application.java` 主类, 注意：配置文件[application-env.yml](application/src/main/resources/application-env.yml)需要配合环境变量使用,可以参考环境变量文件[.env](.env)


IDEA运行示例：

![run.png](docs/images/run.png)

4. **访问应用**

- 应用地址：http://localhost:8080 默认超级管理员账号：`admin`/`yy1234`
- API 文档：http://localhost:8080/doc.html
- Druid 监控：http://localhost:8080/druid 默认账户：`admin`/`111111`

5. 构建可执行的springboot jar包，以便于部署
```bash
# Windows
./gradlew.bat bootJar

# Linux/Mac
./gradlew bootJar
```

## 📚 模块说明

### System 模块

系统管理核心模块，提供以下功能：

- 用户管理：用户 CRUD、用户状态管理
- 角色管理：角色权限配置
- 菜单管理：动态菜单路由
- 部门管理：组织架构管理
- 岗位管理：岗位配置
- 字典管理：系统字典维护
- 参数配置：系统参数管理
- 通知公告：系统公告发布
- 操作日志：用户操作记录
- 登录日志：登录历史记录
- 在线用户：实时在线用户监控
- 验证码：图形验证码生成
- 代码生成：快速生成 CRUD 代码

### Object Storage 模块

对象存储服务模块，提供：

- 公共文件管理：可公开访问的文件上传下载
- 私有文件管理：需授权访问的文件管理
- 文件分类管理：文件分组和分类
- 定时任务：文件清理、过期处理

### Common 组件

通用能力组件集，各模块可独立引用：

- **common-core**：核心工具类、基础枚举、异常定义
- **common-security**：Sa-Token 集成、权限拦截器
- **common-mybatis**：MyBatis Plus 配置、类型处理器
- **common-redis**：Redis 服务封装
- **common-crypto**：加密解密、接口加密注解
- **common-validation**：参数校验注解
- **common-excel**：Excel 导入导出注解

## 🔧 核心配置

### 数据库配置

项目使用 Druid 连接池，支持动态数据源切换。默认数据源为 `master`，可在 `application-env.yml` 中配置多数据源。

### 缓存配置

- 分布式缓存：Redis
- 本地缓存：Caffeine
- 支持多级缓存策略

### 安全配置

- 基于 Sa-Token 的无状态认证
- JWT Token 方式
- 支持白名单配置
- 接口级别的加密注解

### 日志配置

使用 Logback，配置文件位于 `application/src/main/resources/logback-spring.xml`

## 📖 开发规范
[开发文档.md](docs/%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3.md)

### 数据库规范

- 所有表继承 `BasePo`，包含 `create_time`、`update_time`、`deleted` 等字段
- 日期类型映射为 `LocalDateTime`/`LocalDate`
- 布尔类型使用 `tinyint(1)`
- JSON 字段使用 `json` 类型

详细参考：[数据库设计规范.md](docs/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.md)

### 代码规范

- 统一使用 UTF-8 编码
- Java 版本：21
- 包名规范：`com.yy.{module}`
- 时区统一为：`Asia/Shanghai`

### 接口规范

- RESTful API 设计
- 统一返回结构（通过 `common-core` 定义）
- 异常统一处理
- 支持国际化错误信息

## 🧪 测试

```bash
# 运行测试（默认跳过）
gradlew test
```

注：项目默认配置为构建时跳过测试，可在 `build.gradle.kts` 中修改。

## 📝 API 文档

项目集成 Knife4j，启动后访问：http://localhost:8080/doc.html

文档分组：
- 用户模块
- 文件模块
- 帖子模块
- 系统管理模块

## 🤝 贡献指南

欢迎提交 Issue 或 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 许可证

本项目采用 [MIT](LICENSE) 许可证。

## 📧 联系方式

如有问题或建议，请通过 Issue 联系。

---

**注意**：请在生产环境中修改默认密码和密钥配置！
## 演示图
![login.png](docs/images/demo/login.png)
![index.png](docs/images/demo/index.png)
![genDict.png](docs/images/demo/genDict.png)
![gen.png](docs/images/demo/gen.png)