springboot3-quickstart

🚀 Spring Boot 3 企业级快速开发模板

开箱即用的最佳实践 | 让你专注业务逻辑，不再重复造轮子

如果对你有帮助，给个 ⭐ Star 支持一下！

---

✨ 特性

功能	说明	状态
🔐 JWT 认证	Token 生成/解析/验证，注解拦截	✅
📄 统一响应	Result 封装，规范前后端交互	✅
🚨 全局异常处理	覆盖常见异常场景，统一错误码	✅
📑 接口文档	Knife4j + OpenAPI 3.0，自动生成	✅
📄 分页查询	MyBatis-Plus 分页封装，一行搞定	✅
📁 文件上传	单文件/多文件上传，按日期分目录	✅
⏰ 定时任务	Cron 表达式，开箱即用	✅
🗄️ 数据库	MyBatis-Plus + MySQL + 自动填充	✅
💾 Redis 缓存	集成 Spring Data Redis	✅
🌐 跨域配置	CORS 开箱即用	✅
💚 健康监控	Spring Boot Actuator	✅
🧩 完整 CRUD 示例	用户模块：注册/登录/查询/更新	✅

---

🛠️ 技术栈

组件	版本	说明
Spring Boot	3.4.5	应用框架
Java	21	编程语言
MyBatis-Plus	3.5.7	ORM 框架
JWT (jjwt)	0.12.6	Token 认证
Knife4j	4.4.0	接口文档
Hutool	5.8.27	工具类库
MySQL	8.0+	数据库
Redis	6.0+	缓存

---

📁 项目结构

springboot3-quickstart/
├── src/main/java/com/quickstart/
│   ├── QuickstartApplication.java        # 启动类
│   ├── common/                           # 公共模块
│   │   ├── Result.java                   # 统一响应
│   │   ├── ErrorCode.java                # 错误码枚举
│   │   ├── BusinessException.java        # 业务异常
│   │   ├── GlobalExceptionHandler.java   # 全局异常处理
│   │   └── PageRequest.java              # 分页参数
│   ├── config/                           # 配置模块
│   │   ├── MybatisPlusConfig.java        # MyBatis-Plus 配置
│   │   ├── OpenApiConfig.java            # 接口文档配置
│   │   ├── CorsConfig.java               # 跨域配置
│   │   └── FileController.java           # 文件上传
│   ├── demo/                             # 示例模块（CRUD 完整示例）
│   │   ├── controller/UserController.java
│   │   ├── service/UserService.java
│   │   ├── service/impl/UserServiceImpl.java
│   │   ├── mapper/UserMapper.java
│   │   ├── entity/User.java
│   │   └── dto/
│   │       ├── RegisterRequest.java
│   │       ├── LoginRequest.java
│   │       └── UserResponse.java
│   ├── task/                             # 定时任务
│   │   └── ScheduledTask.java
│   └── util/                             # 工具类
│       ├── JwtUtil.java                  # JWT 工具
│       ├── RequireLogin.java             # 登录拦截注解
│       └── CurrentUserUtil.java          # 当前用户工具
└── src/main/resources/
    └── application.yml

---

🚀 快速开始

1. 创建数据库

CREATE DATABASE quickstart_db DEFAULT CHARACTER SET utf8mb4;

-- 用户表示例（Demo 模块需要）
CREATE TABLE sys_user (
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    username    VARCHAR(50)  NOT NULL UNIQUE,
    password    VARCHAR(255) NOT NULL,
    nickname    VARCHAR(50),
    email       VARCHAR(100),
    phone       VARCHAR(20),
    avatar      VARCHAR(255),
    status      TINYINT DEFAULT 1 COMMENT '0-禁用 1-启用',
    deleted     TINYINT DEFAULT 0,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

2. 修改配置

编辑 src/main/resources/application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/quickstart_db
    username: your_username
    password: your_password

jwt:
  secret: your-secret-key-at-least-32-chars
  expiration: 86400000  # 24小时

3. 启动项目

mvn spring-boot:run

4. 访问接口文档

打开浏览器：http://localhost:8080/doc.html

---

📖 使用示例

用户注册

curl -X POST http://localhost:8080/api/user/register \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456","nickname":"演示用户"}'

用户登录

curl -X POST http://localhost:8080/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}'

响应示例：

{
  "code": 200,
  "message": "登录成功",
  "data": { "token": "eyJhbGciOiJIUzI1NiJ9..." }
}

带 Token 请求

curl http://localhost:8080/api/user/info \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

文件上传

curl -X POST http://localhost:8080/api/file/upload \
  -F "file=@/path/to/image.png"

统一响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": { ... },
  "timestamp": 1716528000000
}

异常响应

{
  "code": 1001,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1716528000000
}

---

🔧 扩展指南

添加新模块

# 1. 在 src/main/java/com/quickstart/ 下创建模块目录
mkdir -p src/main/java/com/quickstart/order/{controller,service,mapper,entity,dto}

# 2. 按 demo 模块的模式编写代码
# 3. Mapper 接口添加 @Mapper 注解即可

添加新定时任务

@Component
public class MyTask {
    @Scheduled(cron = "0 0 9 * * ?")  // 每天上午9点
    public void dailyReport() {
        // 你的逻辑
    }
}

添加 Redis 缓存

@Autowired
private StringRedisTemplate redis;

// 写缓存
redis.opsForValue().set("key", "value", 30, TimeUnit.MINUTES);

// 读缓存
String value = redis.opsForValue().get("key");

---

📐 设计原则

1. 约定优于配置 — 遵循 Spring Boot 默认行为
2. 统一响应格式 — 所有接口返回 Result<T>
3. 全局异常处理 — Controller 中不 try-catch
4. 参数校验前置 — 使用 Jakarta Validation
5. 接口文档先行 — Knife4j 自动生成

---

⭐ Star History

---

📄 License

MIT