# 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