# baseProject

**Repository Path**: danwuxin/baseProject

## Basic Information

- **Project Name**: baseProject
- **Description**: springBoot基础框架
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, Java, 基础框架

## README

# Spring Boot 基础框架

## 项目简介

这是一个基于 Spring Boot 的基础框架，提供了统一返回结果、全局异常处理、JWT 认证、审计日志、分页功能等常用功能，适用于博客、管理台等各类系统的快速开发。

## 技术栈

- **Spring Boot**：2.7.18
- **Spring MVC**：Web 开发框架
- **Spring Data JPA**：ORM 框架，简化数据库操作
- **Spring Security**：安全框架，用于认证和授权
- **JWT**：无状态认证
- **MySQL**：关系型数据库
- **Redis**：缓存数据库
- **Swagger**：API 文档
- **Lombok**：简化 Java 代码
- **Hutool**：Java 工具包

## 核心功能

- ✅ 统一返回结果
- ✅ 全局异常处理
- ✅ 分页功能
- ✅ JWT 认证
- ✅ 审计日志
- ✅ 跨域配置
- ✅ 线程池配置
- ✅ 常用工具类
- ✅ API 文档
- ✅ 测试框架

## 目录结构

```
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── baseproduct/
│   │   │           ├── common/           # 公共组件
│   │   │           │   ├── ResponseCode.java      # 响应码枚举
│   │   │           │   ├── ResponseResult.java    # 统一返回结果
│   │   │           │   ├── PageRequest.java       # 分页请求
│   │   │           │   └── PageResult.java        # 分页结果
│   │   │           ├── config/            # 配置类
│   │   │           │   ├── CorsConfig.java         # 跨域配置
│   │   │           │   ├── RedisConfig.java        # Redis 配置
│   │   │           │   ├── ThreadPoolConfig.java   # 线程池配置
│   │   │           │   ├── JwtUtils.java           # JWT 工具类
│   │   │           │   ├── JwtAuthenticationFilter.java  # JWT 认证过滤器
│   │   │           │   └── SecurityConfig.java     # Spring Security 配置
│   │   │           ├── controller/        # 控制器
│   │   │           │   └── UserController.java     # 用户控制器
│   │   │           ├── entity/            # 实体类
│   │   │           │   ├── User.java               # 用户实体
│   │   │           │   └── AuditLog.java          # 审计日志实体
│   │   │           ├── exception/         # 异常处理
│   │   │           │   ├── BusinessException.java  # 业务异常
│   │   │           │   └── GlobalExceptionHandler.java  # 全局异常处理器
│   │   │           ├── repository/        # 数据访问层
│   │   │           │   ├── UserRepository.java     # 用户数据访问
│   │   │           │   └── AuditLogRepository.java  # 审计日志数据访问
│   │   │           ├── service/           # 业务层
│   │   │           │   ├── BaseService.java        # 通用 Service 接口
│   │   │           │   └── impl/          # Service 实现
│   │   │           │       ├── BaseServiceImpl.java  # 通用 Service 实现
│   │   │           │       └── UserDetailsServiceImpl.java  # UserDetailsService 实现
│   │   │           ├── utils/             # 工具类
│   │   │           │   ├── DateUtils.java          # 日期工具
│   │   │           │   ├── SecurityUtils.java      # 加密工具
│   │   │           │   └── IpUtils.java            # IP 工具
│   │   │           └── BaseProductApplication.java  # 应用入口
│   │   └── resources/
│   │       └── application.yml           # 应用配置
│   └── test/                              # 测试目录
│       └── java/
│           └── com/
│               └── baseproduct/
│                   └── BaseProductApplicationTests.java  # 应用测试
├── pom.xml                                # Maven 配置
└── README.md                              # 项目说明
```

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+
- MySQL 5.7+
- Redis 5.0+

### 配置修改

1. 修改 `application.yml` 中的数据库配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/base_product?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
```

2. 修改 Redis 配置：

```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password: 
    database: 0
```

### 启动项目

使用 Maven 命令启动项目：

```bash
mvn spring-boot:run
```

或直接运行 `BaseProductApplication.java` 类。

### 访问 API 文档

项目启动后，可通过以下地址访问 Swagger API 文档：

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

## 配置说明

### 统一返回结果

框架提供了统一的返回结果格式，所有 API 接口都应该返回 `ResponseResult` 对象：

```java
@GetMapping("/health")
public ResponseResult<String> health() {
    return ResponseResult.success("服务健康运行中");
}
```

返回结果格式：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": "服务健康运行中",
  "timestamp": "2025-12-30T12:00:00"
}
```

### 全局异常处理

框架提供了全局异常处理器，自动处理各类异常并返回统一格式的错误信息：

1. **业务异常**：通过抛出 `BusinessException` 自定义业务错误：

```java
throw new BusinessException(ResponseCode.PARAM_ERROR, "参数错误");
```

2. **参数验证异常**：使用 `@Validated` 注解验证参数，自动返回验证错误信息。

3. **其他异常**：如空指针异常、数据库异常等，自动返回 500 错误。

### 分页功能

框架提供了统一的分页请求和响应格式：

1. **分页请求**：继承 `PageRequest` 类，添加自定义查询条件：

```java
@Data
public class UserQueryRequest extends PageRequest {
    private String username;
    private String email;
}
```

2. **分页响应**：使用 `PageResult` 类包装分页结果：

```java
@GetMapping("/list")
public ResponseResult<PageResult<User>> list(UserQueryRequest request) {
    Pageable pageable = PageRequest.of(request.getPageNum() - 1, request.getPageSize());
    Page<User> page = userRepository.findAll(pageable);
    PageResult<User> pageResult = PageResult.build(
            request.getPageNum(),
            request.getPageSize(),
            page.getTotalElements(),
            page.getContent()
    );
    return ResponseResult.success(pageResult);
}
```

### JWT 认证

框架集成了 JWT 认证，使用步骤如下：

1. **生成令牌**：使用 `JwtUtils` 生成 JWT 令牌：

```java
String token = jwtUtils.generateToken(user.getUsername(), claims);
```

2. **验证令牌**：请求时在 `Authorization` 头中携带 JWT 令牌：

```
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMSIsImV4cCI6MTcwNDA0NzQ3MX0.xxx
```

3. **配置放行路径**：在 `SecurityConfig` 类中配置不需要认证的路径：

```java
.authorizeRequests()
.antMatchers("/api/auth/**").permitAll()
.anyRequest().authenticated()
```

### 审计日志

框架自动记录所有控制器方法的调用，包括请求参数、响应结果、执行时间等信息，存储在 `audit_log` 表中。

### 常用工具类

框架提供了以下常用工具类：

1. **DateUtils**：日期时间处理
2. **SecurityUtils**：密码加密、随机字符串生成等
3. **IpUtils**：获取客户端真实 IP 地址

## 测试

框架集成了 JUnit 5 测试框架，可通过以下命令运行测试：

```bash
mvn test
```

## 扩展建议

1. **添加缓存注解**：使用 `@Cacheable`、`@CachePut`、`@CacheEvict` 等注解简化缓存操作。
2. **添加消息队列**：集成 RabbitMQ 或 Kafka，实现异步消息处理。
3. **添加定时任务**：使用 `@Scheduled` 注解实现定时任务。
4. **添加文件上传**：实现文件上传和下载功能。
5. **添加多环境配置**：使用 `application-dev.yml`、`application-prod.yml` 等实现多环境配置。
6. **添加 API 版本控制**：实现 API 版本管理。
7. **添加限流功能**：使用 Redis 实现接口限流。
8. **添加熔断降级**：使用 Sentinel 或 Hystrix 实现服务熔断和降级。

## 许可证

MIT