# springboot3-init

**Repository Path**: gaoerkai/springboot3-init

## Basic Information

- **Project Name**: springboot3-init
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot Init Framework

🚀 一个开箱即用的 Spring Boot 3.x 初始化框架，集成?MyBatis-Flex、Sa-Token、Hutool 等主流技术栈，帮助您快速开?RESTful API?

## ?技术栈

| 技?| 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.2.5 | 核心框架 |
| JDK | 17 | Java 开发工具包 |
| MyBatis-Flex | 1.9.7 | 轻量?ORM 框架 |
| Sa-Token | 1.38.0 | 访问控制框架 |
| Hutool | 5.8.29 | Java 工具?|
| Druid | 1.2.23 | 数据库连接池 |
| Redis | - | 缓存和会话存?|
| SpringDoc | 2.5.0 | API 文档 (Swagger UI) |
| Lombok | 1.18.32 | 简化代?|

## 📁 项目结构

```
springboot-init-gek/
├── sql/                          # SQL 脚本
?  └── init.sql                  # 数据库初始化脚本
├── src/main/
?  ├── java/com/gek/springbootinit/
?  ?  ├── annotation/           # 自定义注?
?  ?  ├── aop/                  # AOP 切面
?  ?  ├── common/               # 通用?
?  ?  ?  ├── BaseResponse.java      # 统一响应封装
?  ?  ?  ├── ErrorCode.java         # 错误码枚?
?  ?  ?  ├── PageRequest.java       # 分页请求基类
?  ?  ?  └── DeleteRequest.java     # 删除请求
?  ?  ├── config/               # 配置?
?  ?  ?  ├── CorsConfig.java        # 跨域配置
?  ?  ?  ├── JsonConfig.java        # JSON 配置
?  ?  ?  ├── MyBatisFlexConfig.java # MyBatis-Flex 配置
?  ?  ?  ├── OpenApiConfig.java     # OpenAPI 配置
?  ?  ?  └── SaTokenConfig.java     # Sa-Token 配置
?  ?  ├── constant/             # 常量定义
?  ?  ?  └── UserConstant.java      # 用户常量
?  ?  ├── controller/           # 控制器层
?  ?  ?  └── UserController.java    # 用户控制?
?  ?  ├── exception/            # 异常处理
?  ?  ?  ├── BusinessException.java        # 业务异常
?  ?  ?  └── GlobalExceptionHandler.java   # 全局异常处理?
?  ?  ├── mapper/               # 数据访问?
?  ?  ?  └── UserMapper.java        # 用户 Mapper
?  ?  ├── model/                # 数据模型
?  ?  ?  ├── dto/              # 数据传输对象
?  ?  ?  ?  └── user/
?  ?  ?  ?      ├── UserLoginRequest.java
?  ?  ?  ?      ├── UserRegisterRequest.java
?  ?  ?  ?      ├── UserQueryRequest.java
?  ?  ?  ?      └── UserUpdateRequest.java
?  ?  ?  ├── entity/           # 实体?
?  ?  ?  ?  └── User.java
?  ?  ?  ├── enums/            # 枚举?
?  ?  ?  └── vo/               # 视图对象
?  ?  ?      └── UserVO.java
?  ?  ├── service/              # 业务逻辑?
?  ?  ?  ├── UserService.java
?  ?  ?  └── impl/
?  ?  ?      └── UserServiceImpl.java
?  ?  ├── utils/                # 工具?
?  ?  ?  ├── ResultUtils.java       # 响应工具?
?  ?  ?  └── ThrowUtils.java        # 异常抛出工具?
?  ?  └── SpringBootInitApplication.java  # 启动?
?  └── resources/
?      ├── application.yml           # 主配置文?
?      ├── application-dev.yml       # 开发环境配?
?      └── application-prod.yml      # 生产环境配置
└── pom.xml                       # Maven 依赖配置
```

## 🚀 快速开?

### 1. 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- Redis 5.0+

### 2. 数据库初始化

执行 `sql/init.sql` 脚本创建数据库和表：

```bash
mysql -u root -p < sql/init.sql
```

默认创建了两个测试账号：
- 管理员：`admin` / `admin123`
- 普通用户：`test` / `test123`

### 3. 修改配置

编辑 `src/main/resources/application-dev.yml`，修改数据库?Redis 连接信息?

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/springboot_init?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 你的密码
  data:
    redis:
      host: localhost
      port: 6379
      password: 你的密码
```

### 4. 启动项目

```bash
# 使用 Maven 启动
mvn spring-boot:run

# 或者使?IDE 直接运行 SpringBootInitApplication.java
```

### 5. 访问接口文档

启动成功后，访问 Swagger UI?

```
http://localhost:8080/api/swagger-ui.html
```

## 📖 核心功能

### 1. 统一响应格式

所有接口返回统一?`BaseResponse<T>` 格式?

```json
{
  "code": 0,
  "data": {},
  "message": "ok"
}
```

### 2. 全局异常处理

自动捕获并处理各类异常，返回友好的错误信息：

```java
// 使用 ThrowUtils 抛出业务异常
ThrowUtils.throwIf(user == null, ErrorCode.NOT_FOUND_ERROR, "用户不存?);

// 使用 BusinessException
throw new BusinessException(ErrorCode.PARAMS_ERROR, "参数错误");
```

### 3. Sa-Token 权限控制

支持登录认证和角色权限控制：

```java
// 检查登?
@SaCheckLogin
public BaseResponse<UserVO> getUser() { }

// 检查角?
@SaCheckRole("admin")
public BaseResponse<Boolean> deleteUser() { }
```

### 4. MyBatis-Flex 链式查询

使用 MyBatis-Flex 进行优雅的数据库操作?

```java
QueryWrapper queryWrapper = QueryWrapper.create()
    .where(USER.USERNAME.eq(username))
    .and(USER.STATUS.eq(0))
    .orderBy(USER.CREATE_TIME.desc());

List<User> users = userMapper.selectListByQuery(queryWrapper);
```

### 5. Hutool 工具?

集成 Hutool 常用工具?

```java
// 字符串工?
StrUtil.isBlank(str);
StrUtil.format("Hello, {}", name);

// 日期工具
DateUtil.format(date, "yyyy-MM-dd");

// 对象拷贝
BeanUtil.copyProperties(source, target);

// JSON 处理
JSONUtil.toJsonStr(object);

// 加密工具
DigestUtil.md5Hex(password);
```

## 🔧 开发指?

### 1. 创建新的业务模块

#### 步骤 1：创建实体类

```java
@Data
@Table("your_table")
public class YourEntity implements Serializable {
    @Id(keyType = KeyType.Auto)
    private Long id;
    // 其他字段...
}
```

#### 步骤 2：创?Mapper

```java
@Mapper
public interface YourMapper extends BaseMapper<YourEntity> {
}
```

#### 步骤 3：创?Service

```java
public interface YourService extends IService<YourEntity> {
    // 自定义方?
}

@Service
public class YourServiceImpl extends ServiceImpl<YourMapper, YourEntity> 
        implements YourService {
    // 实现自定义方?
}
```

#### 步骤 4：创?Controller

```java
@RestController
@RequestMapping("/your")
@Tag(name = "YourController", description = "业务描述")
public class YourController {
    @Resource
    private YourService yourService;
    
    @PostMapping("/create")
    @Operation(summary = "创建", description = "创建新记?)
    public BaseResponse<Long> create(@RequestBody YourRequest request) {
        // 业务逻辑
        return ResultUtils.success(id);
    }
}
```

### 2. 分页查询示例

```java
@PostMapping("/list/page")
public BaseResponse<Page<YourVO>> listByPage(@RequestBody YourQueryRequest request) {
    int current = request.getCurrent();
    int pageSize = request.getPageSize();
    
    QueryWrapper queryWrapper = QueryWrapper.create()
        .where(YOUR_ENTITY.NAME.like(request.getName()))
        .orderBy(YOUR_ENTITY.CREATE_TIME.desc());
    
    Page<YourEntity> page = yourService.page(new Page<>(current, pageSize), queryWrapper);
    
    // 转换?VO
    Page<YourVO> voPage = new Page<>(page.getPageNumber(), page.getPageSize(), page.getTotalRow());
    voPage.setRecords(page.getRecords().stream()
        .map(this::convertToVO)
        .toList());
    
    return ResultUtils.success(voPage);
}
```

### 3. 事务管理

```java
@Service
public class YourServiceImpl extends ServiceImpl<YourMapper, YourEntity> 
        implements YourService {
    
    @Transactional(rollbackFor = Exception.class)
    public void complexOperation() {
        // 多个数据库操?
        // 任何异常都会回滚
    }
}
```

## 🔐 权限控制

### Sa-Token 配置

?`SaTokenConfig.java` 中配置路由拦截规则：

```java
@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new SaInterceptor(handle -> {
        // 需要登录的路由
        SaRouter.match("/**")
            .notMatch("/api/user/login", "/api/user/register")
            .check(r -> StpUtil.checkLogin());
        
        // 需要管理员权限的路?
        SaRouter.match("/api/admin/**")
            .check(r -> StpUtil.checkRole("admin"));
    })).addPathPatterns("/**");
}
```

### 使用注解控制权限

```java
// 需要登?
@SaCheckLogin
@GetMapping("/info")
public BaseResponse<UserVO> getInfo() { }

// 需要管理员角色
@SaCheckRole("admin")
@PostMapping("/delete")
public BaseResponse<Boolean> delete() { }

// 需要特定权?
@SaCheckPermission("user:delete")
@PostMapping("/delete")
public BaseResponse<Boolean> delete() { }
```

## 📊 监控和管?

### Druid 监控

访问 Druid 监控页面?

```
http://localhost:8080/api/druid/index.html
```

默认账号密码：`admin` / `admin`

### API 文档

访问 Swagger UI?

```
http://localhost:8080/api/swagger-ui.html
```

## 🎯 最佳实?

### 1. 分层职责

- **Controller**：接收请求、参数校验、调?Service、返回响?
- **Service**：业务逻辑处理、事务管?
- **Mapper**：数据库操作

### 2. 命名规范

- **实体?*：`User`、`Order`
- **DTO**：`UserLoginRequest`、`UserQueryRequest`
- **VO**：`UserVO`、`OrderVO`
- **Service**：`UserService`、`UserServiceImpl`
- **Controller**：`UserController`

### 3. 异常处理

```java
// 推荐：使?ThrowUtils
ThrowUtils.throwIf(condition, ErrorCode.PARAMS_ERROR, "错误信息");

// 或者直接抛?BusinessException
throw new BusinessException(ErrorCode.PARAMS_ERROR, "错误信息");
```

### 4. 日志记录

```java
@Slf4j
@Service
public class YourService {
    public void doSomething() {
        log.info("操作开? param={}", param);
        try {
            // 业务逻辑
            log.info("操作成功");
        } catch (Exception e) {
            log.error("操作失败", e);
            throw e;
        }
    }
}
```

## 🔄 环境切换

### 开发环?

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

### 生产环境

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=prod
```

## 📦 打包部署

### 1. 打包

```bash
mvn clean package -DskipTests
```

### 2. 运行

```bash
java -jar target/springboot-init-1.0.0.jar --spring.profiles.active=prod
```

### 3. Docker 部署（可选）

创建 `Dockerfile`?

```dockerfile
FROM openjdk:17-jdk-slim
WORKDIR /app
COPY target/springboot-init-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar", "--spring.profiles.active=prod"]
```

构建和运行：

```bash
docker build -t springboot-init .
docker run -d -p 8080:8080 springboot-init
```

## 🛠?常见问题

### 1. 数据库连接失?

检?`application-dev.yml` 中的数据库配置是否正确?

### 2. Redis 连接失败

确保 Redis 服务已启动，检查配置文件中?Redis 地址和端口?

### 3. 端口被占?

修改 `application.yml` 中的 `server.port` 配置?

### 4. MyBatis-Flex 表定义类找不?

运行项目后，MyBatis-Flex 会自动生成表定义类（?`UserTableDef`），首次运行可能需要重新编译?

## 📝 更新日志

### v1.0.0 (2024-02-04)

- ?集成 Spring Boot 3.2.5
- ?集成 MyBatis-Flex 1.9.7
- ?集成 Sa-Token 1.38.0
- ?集成 Hutool 5.8.29
- ?实现用户注册、登录、查询功?
- ?统一响应格式和异常处?
- ?集成 Swagger UI 文档
- ?集成 Druid 监控

## 📄 License

[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

## 👥 贡献

欢迎提交 Issue ?Pull Request?

## 📧 联系方式

如有问题，请联系：support@example.com