shenjianZ
40c85c3c1f
在初始认证基础上，新增完整的 RBAC 权限模型（角色、权限、菜单三级管理）， 集成审计日志、接口限流、登录失败锁定、Refresh Token 机制、Redis 分布式缓存与锁、 RocketMQ 消息队列，并引入 Flyway 数据库版本管理，同时补充项目文档与使用示例
163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# Spring Boot Template
|
||
|
||
基于 Spring Boot 3.5 的通用后端模板项目，开箱即用的认证体系和基础设施，快速启动新业务项目。
|
||
|
||
## 内置功能
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| **JWT 认证** | 注册、登录、Token 验证 |
|
||
| **用户管理** | 用户 CRUD、角色（USER/ADMIN）、状态管理 |
|
||
| **密码找回** | 邮箱验证码方式重置密码 |
|
||
| **Spring Security** | 方法级权限控制、CORS、路由权限 |
|
||
| **Redis** | 完整的工具类（String/Hash/List/Set/ZSet/Bitmap/HyperLogLog） |
|
||
| **全局异常处理** | 统一响应格式、参数校验、业务异常、系统异常 |
|
||
| **JPA 审计** | 自动填充 createdAt / updatedAt |
|
||
| **日志拦截** | 请求 ID、用户信息、耗时统计 |
|
||
| **Swagger UI** | 在线 API 文档 + 调试（Bearer Token 认证） |
|
||
| **多环境配置** | dev / prod 配置分离，支持 .env 环境变量 |
|
||
|
||
## 技术栈
|
||
|
||
- Java 17 + Spring Boot 3.5.6
|
||
- Spring Data JPA + MySQL
|
||
- Spring Data Redis + Lettuce
|
||
- Spring Security + JWT (jjwt)
|
||
- Springdoc OpenAPI (Swagger)
|
||
- Lombok
|
||
- Maven
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
- JDK 17+
|
||
- MySQL 8.0+
|
||
- Redis 6.0+
|
||
- Maven 3.9+
|
||
|
||
### 2. 克隆并配置
|
||
|
||
```bash
|
||
# 复制项目
|
||
cp -r springboot-template your-project
|
||
cd your-project
|
||
|
||
# 修改包名（按需）
|
||
# com.aisi.template -> com.yourcompany.project
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，填入实际的数据库密码、JWT 密钥等
|
||
```
|
||
|
||
### 3. 初始化数据库
|
||
|
||
```sql
|
||
CREATE DATABASE IF NOT EXISTS template DEFAULT CHARSET utf8mb4;
|
||
```
|
||
|
||
执行 `src/main/resources/sql/init.sql`，或依赖 JPA `ddl-auto: update` 自动建表。
|
||
|
||
### 4. 启动
|
||
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
启动后访问：
|
||
- Swagger UI: http://localhost:8080/swagger-ui/index.html
|
||
- OpenAPI JSON: http://localhost:8080/v3/api-docs
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/com/aisi/template/
|
||
├── TemplateApplication.java # 入口
|
||
├── config/
|
||
│ ├── SecurityConfig.java # Security + CORS + JWT 过滤器
|
||
│ ├── JacksonConfig.java # JSON 日期格式
|
||
│ ├── JpaConfig.java # JPA 审计
|
||
│ ├── RedisConfig.java # Redis 序列化配置
|
||
│ ├── WebConfig.java # 日志拦截器注册
|
||
│ └── OpenApiConfig.java # Swagger Bearer Token
|
||
├── controller/
|
||
│ └── UserController.java # 用户相关接口
|
||
├── domain/
|
||
│ ├── RestBean.java # 统一响应包装
|
||
│ ├── RestCode.java # 响应状态码
|
||
│ ├── CustomUserDetails.java # Spring Security UserDetails
|
||
│ ├── dto/ # 请求 DTO
|
||
│ ├── vo/ # 响应 VO
|
||
│ ├── entity/ # JPA 实体
|
||
│ └── enums/ # 枚举（Role, ErrorCode）
|
||
├── exception/
|
||
│ └── BusinessException.java # 业务异常
|
||
├── filter/
|
||
│ └── JwtAuthenticationFilter.java # JWT 认证过滤器
|
||
├── handler/
|
||
│ └── GlobalExceptionHandler.java # 全局异常处理
|
||
├── interceptor/
|
||
│ └── LoggingInterceptor.java # 请求日志
|
||
├── repository/ # Spring Data JPA 仓库
|
||
├── service/ # 业务接口 + 实现
|
||
│ └── impl/
|
||
└── utils/
|
||
├── JwtUtil.java # JWT 工具
|
||
├── SecurityUtils.java # 安全上下文工具
|
||
└── RedisUtils.java # Redis 工具（全数据类型）
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
通过 `.env` 文件或环境变量配置，关键配置项：
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `DB_HOST` | localhost | MySQL 地址 |
|
||
| `DB_PORT` | 3306 | MySQL 端口 |
|
||
| `DB_NAME` | template | 数据库名 |
|
||
| `DB_USER` | root | 数据库用户 |
|
||
| `DB_PASS` | root | 数据库密码 |
|
||
| `REDIS_HOST` | localhost | Redis 地址 |
|
||
| `REDIS_PORT` | 6379 | Redis 端口 |
|
||
| `REDIS_PASSWORD` | 空 | Redis 密码 |
|
||
| `JWT_SECRET` | (内置默认值) | JWT 签名密钥，**生产环境必须替换** |
|
||
| `MAIL_HOST` | smtp.163.com | 邮件 SMTP 地址 |
|
||
| `MAIL_USERNAME` | 空 | 邮件账号 |
|
||
| `MAIL_PASSWORD` | 空 | 邮件授权码 |
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t springboot-template .
|
||
|
||
# 运行
|
||
docker run -d -p 8080:8080 \
|
||
-e DB_HOST=host.docker.internal \
|
||
-e REDIS_HOST=host.docker.internal \
|
||
-e JWT_SECRET=your_production_secret_at_least_64_chars_long \
|
||
springboot-template
|
||
```
|
||
|
||
## 使用模板创建新项目
|
||
|
||
1. 复制整个项目目录
|
||
2. 全局替换 `com.aisi.template` 为你的包名
|
||
3. 修改 `pom.xml` 中的 `artifactId`、`name`、`description`
|
||
4. 修改 `application.yaml` 中的 `spring.application.name`
|
||
5. 删除不需要的 Controller/Service，添加你的业务代码
|
||
6. 在 `ErrorCode` 枚举中添加业务错误码（预留了 2000-2999 范围）
|
||
|
||
## API 文档
|
||
|
||
详见 [API_DOCUMENT.md](API_DOCUMENT.md)
|
||
|
||
## 项目概览
|
||
|
||
详见 [DETAILS.md](DETAILS.md)
|
||
## License
|
||
|
||
Apache License 2.0
|