341 lines
8.8 KiB
Markdown
341 lines
8.8 KiB
Markdown
# 开发指南
|
||
|
||
## 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 项目的开发环境搭建、代码规范和开发流程。通过本指南，您可以了解如何快速上手项目开发，确保代码质量和开发效率。
|