makemd/serverjava/docs/09_Development_Guide.md

# 开发指南

## 1. 开发环境搭建

### 1.1 环境要求

- **Java**: JDK 17 或更高版本
- **Maven**: 3.6 或更高版本
- **MySQL**: 8.0 或更高版本
- **Redis**: 6.0 或更高版本
- **IDE**: IntelliJ IDEA 或 Eclipse

### 1.2 安装步骤

**Windows 系统**:
1. 下载并安装 JDK 17：[Oracle JDK 17](https://www.oracle.com/java/technologies/downloads/#java17)
2. 下载并安装 Maven：[Apache Maven](https://maven.apache.org/download.cgi)
3. 下载并安装 MySQL：[MySQL Community Server](https://dev.mysql.com/downloads/mysql/)
4. 下载并安装 Redis：[Redis for Windows](https://github.com/tporadowski/redis/releases)
5. 下载并安装 IntelliJ IDEA：[IntelliJ IDEA](https://www.jetbrains.com/idea/download/)

**Linux 系统**:
1. 安装 JDK 17：
   ```bash
   sudo yum install java-17-openjdk-devel
   ```
2. 安装 Maven：
   ```bash
   sudo yum install maven
   ```
3. 安装 MySQL：
   ```bash
   sudo yum install mysql-server
   ```
4. 安装 Redis：
   ```bash
   sudo yum install redis
   ```
5. 安装 IntelliJ IDEA：
   ```bash
   sudo snap install intellij-idea-community --classic
   ```

### 1.3 项目导入

**IntelliJ IDEA**:
1. 打开 IntelliJ IDEA
2. 点击「File」→「Open」
3. 选择项目目录 `d:\trae_projects\makemd\makemd\serverjava`
4. 点击「OK」，等待项目导入完成
5. 点击「File」→「Project Structure」→「Project」，设置 JDK 为 17
6. 点击「File」→「Project Structure」→「Modules」，确保 Maven 依赖正确导入

**Eclipse**:
1. 打开 Eclipse
2. 点击「File」→「Import」→「Maven」→「Existing Maven Projects」
3. 选择项目目录 `d:\trae_projects\makemd\makemd\serverjava`
4. 点击「Finish」，等待项目导入完成
5. 右键点击项目，选择「Properties」→「Java Build Path」→「Libraries」，确保 JDK 为 17

## 2. 代码规范

### 2.1 命名规范

**类命名**：
- 使用驼峰命名法，首字母大写
- 类名应该清晰描述类的功能
- 服务类使用 `Service` 后缀
- 控制器类使用 `Controller` 后缀
- 配置类使用 `Config` 后缀

**方法命名**：
- 使用驼峰命名法，首字母小写
- 方法名应该清晰描述方法的功能
- 动词开头，如 `createUser`, `updateProduct`

**变量命名**：
- 使用驼峰命名法，首字母小写
- 变量名应该清晰描述变量的用途
- 避免使用缩写，如 `usr` 应该改为 `user`

**常量命名**：
- 使用全大写，单词之间用下划线分隔
- 常量名应该清晰描述常量的用途

### 2.2 代码风格

**缩进**：
- 使用 4 个空格进行缩进
- 避免使用制表符

**换行**：
- 每行代码长度不超过 120 个字符
- 适当换行，提高代码可读性

**注释**：
- 为类、方法、变量添加适当的注释
- 使用 Javadoc 注释格式
- 注释应该清晰描述代码的功能和用途

**示例**：
```java
/**
 * 用户服务类，提供用户相关的业务逻辑
 */
@Service
public class UserService {
    /**
     * 创建用户
     * @param user 用户信息
     * @return 创建的用户
     */
    public User createUser(User user) {
        // 实现创建用户的逻辑
        return userRepository.save(user);
    }
}
```

### 2.3 代码质量

**代码检查**：
- 使用 ESLint 检查代码质量
- 使用 SonarQube 分析代码质量
- 定期进行代码审查

**测试覆盖**：
- 为代码添加单元测试和集成测试
- 确保测试覆盖率达到 80% 以上

**性能优化**：
- 优化代码逻辑，提高性能
- 避免不必要的计算和操作
- 使用缓存减少数据库查询

## 3. 开发流程

### 3.1 分支管理

**分支策略**：
- `main`：主分支，用于发布生产版本
- `develop`：开发分支，用于集成开发
- `feature`：特性分支，用于开发新功能
- `hotfix`：热修复分支，用于修复生产环境的 bug

**分支命名**：
- 特性分支：`feature/feature-name`
- 热修复分支：`hotfix/bug-description`

**分支操作**：
1. 从 `develop` 分支创建特性分支
2. 在特性分支上开发新功能
3. 提交代码并推送特性分支
4. 创建 Pull Request 到 `develop` 分支
5. 代码审查通过后，合并到 `develop` 分支
6. 从 `main` 分支创建热修复分支
7. 在热修复分支上修复 bug
8. 提交代码并推送热修复分支
9. 创建 Pull Request 到 `main` 和 `develop` 分支
10. 代码审查通过后，合并到 `main` 和 `develop` 分支

### 3.2 代码提交

**提交规范**：
- 提交消息应该清晰描述提交的内容
- 使用以下格式：`[模块] 描述`
- 例如：`[User] 修复用户注册功能`

**提交频率**：
- 每次提交应该只包含一个功能或 bug 修复
- 避免一次提交多个不相关的更改
- 定期提交代码，避免代码丢失

### 3.3 代码审查

**审查流程**：
1. 开发人员创建 Pull Request
2. 团队成员审查代码
3. 审查通过后，合并代码
4. 审查不通过时，开发人员修改代码并重新提交

**审查重点**：
- 代码质量和风格
- 功能实现是否正确
- 测试覆盖是否充分
- 性能是否优化
- 安全性是否考虑

## 4. 开发工具

### 4.1 IDE 插件

**IntelliJ IDEA 插件**：
- **Lombok**：简化 Java 代码
- **Spring Boot Assistant**：Spring Boot 开发辅助
- **MyBatis Plugin**：MyBatis 开发辅助
- **SonarLint**：代码质量检查
- **CheckStyle**：代码风格检查

**Eclipse 插件**：
- **Lombok**：简化 Java 代码
- **Spring Tools Suite**：Spring Boot 开发辅助
- **MyBatis Generator**：MyBatis 开发辅助
- **SonarLint**：代码质量检查
- **CheckStyle**：代码风格检查

### 4.2 构建工具

**Maven**：
- 用于项目构建和依赖管理
- 配置文件：`pom.xml`
- 常用命令：
  ```bash
  # 编译项目
  mvn compile
  
  # 运行测试
  mvn test
  
  # 构建项目
  mvn clean package
  
  # 运行项目
  mvn spring-boot:run
  ```

### 4.3 版本控制

**Git**：
- 用于版本控制
- 配置文件：`.gitignore`
- 常用命令：
  ```bash
  # 克隆仓库
  git clone <repository-url>
  
  # 查看状态
  git status
  
  # 添加文件
  git add .
  
  # 提交代码
  git commit -m "[模块] 描述"
  
  # 推送代码
  git push
  
  # 拉取代码
  git pull
  ```

## 5. 开发最佳实践

### 5.1 代码组织

**目录结构**：
- 遵循 Spring Boot 标准目录结构
- 按功能模块组织代码
- 保持代码结构清晰

**示例目录结构**：
```
serverjava/
  ├── src/
  │   ├── main/
  │   │   ├── java/com/crawlful/hub/
  │   │   │   ├── api/controllers/  # 控制器
  │   │   │   ├── service/          # 服务
  │   │   │   ├── model/            # 模型
  │   │   │   ├── config/           # 配置
  │   │   │   ├── util/             # 工具类
  │   │   │   ├── security/         # 安全
  │   │   │   └── monitoring/       # 监控
  │   │   └── resources/            # 资源文件
  │   │       ├── i18n/             # 国际化资源
  │   │       ├── db/migration/     # 数据库迁移脚本
  │   │       ├── application.yml   # 应用配置
  │   │       └── logback.xml       # 日志配置
  │   └── test/                     # 测试代码
  ├── pom.xml                       # Maven 配置
  └── docs/                         # 文档
```

### 5.2 依赖管理

**依赖版本**：
- 使用 Spring Boot 3.2.0 版本
- 统一管理依赖版本
- 定期更新依赖，修复安全漏洞

**依赖范围**：
- `compile`：编译和运行时依赖
- `test`：测试依赖
- `provided`：编译时依赖，运行时由容器提供

### 5.3 错误处理

**全局异常处理**：
- 实现 `GlobalExceptionHandler` 类
- 统一处理系统异常
- 返回统一的错误格式

**自定义异常**：
- 定义业务异常类
- 提供错误码和错误消息
- 便于异常处理和日志记录

### 5.4 日志管理

**日志级别**：
- `DEBUG`：开发调试，详细执行路径
- `INFO`：正常业务流程，如订单创建、状态流转
- `WARN`：潜在问题，如重试、熔断触发
- `ERROR`：错误异常，如 API 调用失败、数据库异常

**日志格式**：
- 包含时间戳、日志级别、类名、消息等
- 使用 Logback 配置日志格式

### 5.5 测试策略

**单元测试**：
- 测试单个方法或类
- 使用 JUnit 5 和 Mockito
- 测试边界条件和异常情况

**集成测试**：
- 测试组件之间的交互
- 使用 Spring Test
- 测试完整的业务流程

**系统测试**：
- 测试整个系统的功能
- 使用 Postman 测试 API 接口
- 测试用户场景

## 6. 总结

本开发指南详细介绍了 Crawlful Hub 项目的开发环境搭建、代码规范和开发流程。通过本指南，您可以了解如何快速上手项目开发，确保代码质量和开发效率。