wurenzhi/makemd

Fork 0

Files

wurenzhi 8d04a0fd6e first commit

2026-03-30 16:55:04 +08:00

8.8 KiB

Raw Blame History

开发指南

1. 开发环境搭建

1.1 环境要求

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

1.2 安装步骤

Windows 系统:

下载并安装 JDK 17：Oracle JDK 17
下载并安装 Maven：Apache Maven
下载并安装 MySQL：MySQL Community Server
下载并安装 Redis：Redis for Windows
下载并安装 IntelliJ IDEA：IntelliJ IDEA

Linux 系统:

安装 JDK 17：
```
sudo yum install java-17-openjdk-devel
```
安装 Maven：
```
sudo yum install maven
```
安装 MySQL：
```
sudo yum install mysql-server
```
安装 Redis：
```
sudo yum install redis
```

安装 IntelliJ IDEA：

sudo snap install intellij-idea-community --classic

1.3 项目导入

IntelliJ IDEA:

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

Eclipse:

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

2. 代码规范

2.1 命名规范

类命名：

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

方法命名：

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

变量命名：

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

常量命名：

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

2.2 代码风格

缩进：

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

换行：

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

注释：

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

示例：

/**
 * 用户服务类，提供用户相关的业务逻辑
 */
@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

分支操作：

从 develop 分支创建特性分支
在特性分支上开发新功能
提交代码并推送特性分支
创建 Pull Request 到 develop 分支
代码审查通过后，合并到 develop 分支
从 main 分支创建热修复分支
在热修复分支上修复 bug
提交代码并推送热修复分支
创建 Pull Request 到 main 和 develop 分支
代码审查通过后，合并到 main 和 develop 分支

3.2 代码提交

提交规范：

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

提交频率：

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

3.3 代码审查

审查流程：

开发人员创建 Pull Request
团队成员审查代码
审查通过后，合并代码
审查不通过时，开发人员修改代码并重新提交

审查重点：

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

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

常用命令：

# 编译项目
mvn compile

# 运行测试
mvn test

# 构建项目
mvn clean package

# 运行项目
mvn spring-boot:run

4.3 版本控制

Git：

用于版本控制
配置文件：.gitignore

常用命令：

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

8.8 KiB Raw Blame History Unescape Escape