springboot-template/README.md

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. 克隆并配置

# 复制项目
cp -r springboot-template your-project
cd your-project

# 修改包名（按需）
# com.aisi.template -> com.yourcompany.project

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入实际的数据库密码、JWT 密钥等

3. 初始化数据库

CREATE DATABASE IF NOT EXISTS template DEFAULT CHARSET utf8mb4;

执行 src/main/resources/sql/init.sql，或依赖 JPA ddl-auto: update 自动建表。

4. 启动

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 部署

# 构建镜像
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

项目概览

详见 DETAILS.md

License

Apache License 2.0