这是一个基于 Spring Boot 3.2.5 + Java 17 + MySQL 8.0 构建的现代化企业级开发框架，采用经典的 Repository + Service 分层架构，提供了完整的项目基础结构和最佳实践。

设计理念

• 开箱即用：提供完整的基础架构，快速启动新项目
• 规范统一：统一的代码风格、异常处理、返回格式
• 易于扩展：模块化设计，便于功能扩展和维护
• 生产就绪：包含监控、日志、事务等生产环境必需功能

技术栈

技术领域	技术选型
后端框架	Spring Boot 3.2.5
Java版本	Java 17
数据库	MySQL 8.0
ORM框架	Spring Data JPA + Hibernate
依赖管理	Maven
日志框架	SLF4J + Logback
监控	Spring Boot Actuator

项目结构

src/main/java/com/deepchart
├── DemoApplication.java          # 应用启动类（程序入口）
├── config/                       # 配置类目录
│   ├── JpaConfig.java           # JPA配置（实体映射、查询优化等）
│   └── WebConfig.java           # Web MVC配置（拦截器、资源映射等）
├── common/                       # 通用组件（全局复用）
│   ├── result/                  # 统一返回结果封装
│   │   ├── Result.java          # 统一响应体（含code、message、data等）
│   │   └── ResultCode.java      # 状态码枚举（成功/失败/参数错误等）
│   └── exception/               # 异常处理
│       ├── GlobalExceptionHandler.java  # 全局异常拦截器（统一处理所有异常）
│       └── BusinessException.java       # 业务异常类（自定义业务错误）
├── entity/                       # 数据库实体类（与表结构映射）
│   ├── BaseEntity.java          # 基础实体类（含公共字段：id、时间戳等）
│   └── User.java                # 用户实体类（示例）
├── repository/                   # 数据访问层（操作数据库）
│   ├── BaseRepository.java      # 基础Repository（封装通用CRUD）
│   └── UserRepository.java      # 用户Repository（用户表专属操作）
├── service/                      # 业务逻辑层（核心业务处理）
│   ├── UserService.java         # 用户服务接口（定义业务方法）
│   └── impl/                    # 服务实现类
│       └── UserServiceImpl.java # 用户服务实现（接口方法具体逻辑）
└── controller/                   # 控制层（接收请求、返回响应）
    └── UserController.java       # 用户控制器（处理用户相关API）

快速开始

环境要求

• JDK 17 或更高版本
• Maven 3.6 或更高版本
• MySQL 8.0 或更高版本

1. 数据库准备

-- 创建数据库
CREATE DATABASE IF NOT EXISTS deepchart CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 使用数据库
USE demo_db;

2. 配置修改

编辑 src/main/resources/application-dev.yml 文件，修改测试环境数据库连接配置：

spring:
datasource:
url: jdbc:mysql://localhost:3306/deepchart?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false
username: your_username      # 修改为你的数据库用户名
password: your_password      # 修改为你的数据库密码

编辑 src/main/resources/application-prod.yml 文件，修改生产环境数据库连接配置：

spring:
datasource:
url: jdbc:mysql://localhost:3306/deepchart?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false
username: your_username      # 修改为你的数据库用户名
password: your_password      # 修改为你的数据库密码

3. 启动应用

方式一：使用Maven

mvn spring-boot:run

方式二：打包后运行

mvn clean package
java -jar target/springboot-demo-1.0.0.jar

4. 验证启动

   访问 http://localhost:8080/api/actuator/health 查看应用健康状态。

核心功能

1. 统一响应格式

所有API返回统一的JSON格式：

成功响应：

{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "testuser"
},
"timestamp": 1640995200000,
"path": "/api/users/1"
}

错误响应：

{
"code": 400,
"message": "参数错误: 用户名不能为空",
"data": null,
"timestamp": 1640995200000,
"path": "/api/users"
}

2. 全局异常处理

框架自动处理各类异常：

异常类型	HTTP状态码	业务状态码	处理说明
BusinessException	200	自定义	业务逻辑异常
MethodArgumentNotValidException	200	1001	参数校验失败
DataAccessException	200	1002	数据访问异常
其他异常	200	500	系统内部错误

3. 数据实体规范

所有实体类继承 BaseEntity，自动包含：

• id: 主键
• createTime: 创建时间
• updateTime: 更新时间
• deleted: 软删除标志
• version: 乐观锁版本

4. 软删除支持

所有删除操作均为软删除，数据不会被物理删除：

// 软删除示例
userRepository.softDelete(userId, LocalDateTime.now());

开发指南

1. 创建新实体

@Data
@EqualsAndHashCode(callSuper = true)
@Entity
@Table(name = "product")
public class Product extends BaseEntity {

@NotBlank(message = "产品名称不能为空")
@Column(nullable = false, length = 100)
private String name;

@Column(columnDefinition = "decimal(10,2)")
private BigDecimal price;

@Column(columnDefinition = "int default 1")
private Integer status = 1;
}

2. 创建Repository

@Repository
public interface ProductRepository extends BaseRepository<Product> {

// 派生查询方法
List<Product> findByStatusOrderByCreateTimeDesc(Integer status);

// 自定义查询
@Query("SELECT p FROM Product p WHERE p.name LIKE %:keyword% AND p.deleted = false")
Page<Product> searchProducts(@Param("keyword") String keyword, Pageable pageable);
}

3. 创建Service

public interface ProductService extends BaseService<Product> {
// 自定义业务方法
Page<Product> searchProducts(String keyword, Pageable pageable);
void changeProductStatus(Long id, Integer status);
}

@Service
@Transactional
@RequiredArgsConstructor
public class ProductServiceImpl extends BaseServiceImpl<Product> implements ProductService {

 private final ProductRepository productRepository;
 
 @Override
 public Page<Product> searchProducts(String keyword, Pageable pageable) {
     return productRepository.searchProducts(keyword, pageable);
 }
 
 @Override
 public void changeProductStatus(Long id, Integer status) {
     Product product = getById(id);
     product.setStatus(status);
     productRepository.save(product);
 }
}

4. 创建Controller

@RestController
@RequestMapping("/products")
@RequiredArgsConstructor
public class ProductController extends BaseController<Product> {

private final ProductService productService;

public ProductController(ProductService productService) {
super(productService);
this.productService = productService;
}

@GetMapping("/search")
public Result<Page<Product>> searchProducts(
@RequestParam String keyword,
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "10") int size) {
Pageable pageable = PageRequest.of(page, size);
return Result.success(productService.searchProducts(keyword, pageable));
}
}

配置说明

数据库配置

spring:
datasource:
hikari:
maximum-pool-size: 20           # 最大连接数
minimum-idle: 5                 # 最小空闲连接
connection-timeout: 30000       # 连接超时时间(ms)
jpa:
hibernate:
ddl-auto: update               # 表结构自动更新
show-sql: true                   # 显示SQL
properties:
hibernate:
format_sql: true             # 格式化SQL
dialect: org.hibernate.dialect.MySQL8Dialect

日志配置

logging:
level:
com.example.demo: DEBUG          # 项目日志级别
org.hibernate.SQL: DEBUG         # Hibernate SQL日志
org.hibernate.type: TRACE        # SQL参数日志

API示例

用户管理接口

方法	路径	说明
POST	/api/users/create	创建用户
POST	/api/users/update	更新用户
GET	/api/users/detail	获取用户详情
GET	/api/users/list	用户列表(分页)
GET	/api/users/delete	删除用户
POST	/api/users/login	用户登录
GET	/api/users/search	搜索用户

使用示例

创建用户：

curl -X POST http://localhost:8080/api/users/create \
-H "Content-Type: application/json" \
-d '{
"username": "demo",
"password": "123456",
"email": "demo@example.com",
"nickname": "演示用户"
}'

查询用户列表：

curl -X GET "http://localhost:8080/api/users/list?page=0&size=10&sort=createTime,desc"

用户登录：

curl -X POST "http://localhost:8080/api/users/login?username=demo&password=123456"

测试指南

单元测试示例

@SpringBootTest
class UserServiceTest {

    @Autowired
    private UserService userService;

    @Test
    void testCreateUser() {
        User user = new User();
        user.setUsername("testuser");
        user.setPassword("password");
        user.setEmail("test@example.com");
        
        User created = userService.createUser(user);
        
        assertNotNull(created.getId());
        assertEquals("testuser", created.getUsername());
    }
}

集成测试示例

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class UserControllerIntegrationTest {

    @LocalServerPort
    private int port;

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    @Order(1)
    void testCreateUser() {
        String url = "http://localhost:" + port + "/api/users";
        
        User user = new User();
        user.setUsername("integration_test");
        user.setPassword("password");
        user.setEmail("integration@test.com");
        
        ResponseEntity<Result> response = restTemplate.postForEntity(url, user, Result.class);
        
        assertEquals(HttpStatus.OK, response.getStatusCode());
        assertNotNull(response.getBody());
        assertEquals(200, response.getBody().getCode().intValue());
    }
}

监控与调试

健康检查

  curl http://localhost:8080/api/actuator/health

应用信息

  curl http://localhost:8080/api/actuator/info

指标监控

  curl http://localhost:8080/api/actuator/metrics

常见问题

1. 数据库连接失败

问题：应用启动时报数据库连接错误 解决：检查 application.yml 中的数据库配置，确保数据库服务已启动。

2. 表结构不自动更新

问题：实体类修改后表结构未更新 解决：检查 ddl-auto 配置，开发环境建议使用 update。

3. 查询性能问题

问题：复杂查询性能较差 解决：使用 @Query 注解编写优化SQL，或使用数据库索引。

4. 事务不生效

问题：Service方法中的事务未正确回滚 解决：确保Service方法添加 @Transactional 注解，且异常为RuntimeException。

开发规范

代码规范

• 命名规范：使用驼峰命名法，类名首字母大写

• 注释要求：公共方法必须添加注释，复杂逻辑添加行内注释

• 异常处理：使用框架提供的统一异常处理，不捕获异常后静默处理

API设计规范

• RESTful风格：使用HTTP方法表示操作类型

• 统一响应：所有接口返回统一的Result格式

• 错误码规范：使用预定义的错误码，不随意创建新错误码

数据库规范

• 软删除：所有删除操作使用软删除

• 索引优化：频繁查询的字段添加索引

• 字段长度：字符串字段根据业务需求设置合适长度