deepChart/README.md

# 这是一个基于 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             |

## 项目结构
```text
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. 数据库准备
```sql
-- 创建数据库
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格式：

成功响应：
```json
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "testuser"
},
"timestamp": 1640995200000,
"path": "/api/users/1"
}
```
错误响应：
```json
{
"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. 软删除支持
   所有删除操作均为软删除，数据不会被物理删除：

```java
// 软删除示例
userRepository.softDelete(userId, LocalDateTime.now());
```
## 开发指南
### 1. 创建新实体
   ```java
   @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
   ```java
   @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
   ```java
   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
   ```java
   @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));
   }
   }
   ```
   ## 配置说明
   ### 数据库配置
   ``` yaml
   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
   ```
   日志配置
   ```yaml
   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 | 	搜索用户     |
   ## 使用示例
   ### 创建用户：

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

```bash
curl -X GET "http://localhost:8080/api/users/list?page=0&size=10&sort=createTime,desc"
```
### 用户登录：

```bash
curl -X POST "http://localhost:8080/api/users/login?username=demo&password=123456"
```
## 测试指南
### 单元测试示例
```java
@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());
    }
}
```
### 集成测试示例
```java
@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());
    }
}
```
## 监控与调试
### 健康检查
```bash
  curl http://localhost:8080/api/actuator/health
```
### 应用信息
```bash
  curl http://localhost:8080/api/actuator/info
```
### 指标监控
```bash
  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格式

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

### 数据库规范
* 软删除：所有删除操作使用软删除

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

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