contract-manager/docs/DEVELOPMENT_GUIDE.md

Contract-Manager 开发环境配置指南

📋 系统要求

基础环境

• 操作系统: Windows 10/11, macOS, Linux
• Java版本: JDK 21+
• Maven版本: Maven 3.8+
• MySQL版本: MySQL 8.0+
• Redis版本: Redis 6.0+
• 内存: 最少 8GB RAM (推荐 16GB+)
• 磁盘: 最少 10GB 可用空间

开发工具 (推荐)

• IDE: IntelliJ IDEA 2023+
• 数据库工具: MySQL Workbench, DataGrip
• 缓存工具: Redis Desktop Manager
• API测试: Postman, Insomnia
• 版本控制: Git

🛠️ 开发工具安装

1. Java 21 安装

Windows

1. 下载 OpenJDK 21
2. 运行安装程序，选择安装路径 (如: C:\Program Files\Java\jdk-21)
3. 设置环境变量:

   # JAVA_HOME
   JAVA_HOME=C:\Program Files\Java\jdk-21
   
   # PATH (添加到现有PATH末尾)
   %JAVA_HOME%\bin
   

macOS

# 使用 Homebrew 安装
brew install openjdk@21

# 设置环境变量 (添加到 ~/.zshrc 或 ~/.bash_profile)
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH=$JAVA_HOME/bin:$PATH

Linux (Ubuntu/Debian)

# 安装 OpenJDK 21
sudo apt update
sudo apt install openjdk-21-jdk

# 设置环境变量
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2. Maven 安装

Windows

1. 下载 Apache Maven
2. 解压到 C:\Maven\apache-maven-3.9.x
3. 设置环境变量:

   # MAVEN_HOME
   MAVEN_HOME=C:\Maven\apache-maven-3.9.x
   
   # PATH
   %MAVEN_HOME%\bin
   

macOS

# 使用 Homebrew 安装
brew install maven

# 验证安装
mvn -version

Linux

# Ubuntu/Debian
sudo apt install maven

# 验证安装
mvn -version

3. IntelliJ IDEA 配置

插件安装 (推荐)

• Lombok Plugin: 支持 Lombok 注解
• Maven Helper: Maven 依赖管理
• Rainbow Brackets: 括号颜色区分
• Database Tools: 数据库操作支持

项目导入

1. 启动 IntelliJ IDEA
2. 选择 "Open" 或 "Import Project"
3. 选择项目根目录的 pom.xml
4. 等待 Maven 导入完成
5. 设置 JDK 为 Java 21

代码风格配置

1. File → Settings → Editor → Code Style → Java
2. 导入项目提供的代码风格配置 (如存在)
3. 设置自动格式化规则

📁 项目配置

1. 环境变量配置

创建项目根目录下的 .env 文件:

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=contract_manager
DB_PASSWORD=your_password
DB_DATABASE=contract_manager

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# 服务端口配置
SERVER_PORT=8080
CLIENT_PORT=8081

# 文件存储配置
FILE_BASE_PATH=C:/contract_files

# 云服务 API 密钥 (如有)
CLOUD_RK_API_KEY=your_rk_api_key
CLOUD_TYC_API_KEY=your_tyc_api_key
CLOUD_U8_API_KEY=your_u8_api_key

# 日志配置
LOG_LEVEL=INFO
LOG_PATH=./logs

# 开发环境配置
SPRING_PROFILES_ACTIVE=dev

2. 数据库配置

MySQL 安装与配置

# Ubuntu/Debian
sudo apt install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 安全配置
sudo mysql_secure_installation

创建数据库和用户

-- 登录 MySQL
mysql -u root -p

-- 创建数据库
CREATE DATABASE contract_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户
CREATE USER 'contract_manager'@'localhost' IDENTIFIED BY 'your_password';

-- 授权
GRANT ALL PRIVILEGES ON contract_manager.* TO 'contract_manager'@'localhost';
FLUSH PRIVILEGES;

数据初始化

# 导入数据库结构
mysql -u contract_manager -p contract_manager < docs/db/structs.sql

# 导入初始数据 (如需要)
mysql -u contract_manager -p contract_manager < docs/db/initial_data.sql

3. Redis 配置

Redis 安装

# Ubuntu/Debian
sudo apt install redis-server

# 启动 Redis
sudo systemctl start redis-server
sudo systemctl enable redis-server

# 测试连接
redis-cli ping
# 应该返回: PONG

Redis 配置优化 (开发环境)

# 编辑 Redis 配置文件
sudo nano /etc/redis/redis.conf

# 推荐配置 (开发环境)
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000

🚀 项目运行

1. 项目构建

# 克隆项目 (如使用 Git)
git clone <project-url>
cd Contract-Manager

# 清理并编译
mvn clean compile

# 运行测试
mvn test

# 打包 (生产环境)
mvn clean package -DskipTests

2. 启动服务

方式一: 分模块启动

# 启动服务端
cd server
mvn spring-boot:run

# 新终端窗口 - 启动客户端
cd client
mvn jfx:run

方式二: Maven 工具启动

# 启动服务端
mvn spring-boot:run -pl server

# 新终端窗口 - 启动客户端
mvn jfx:run -pl client

方式三: IDE 启动

1. 服务端: 运行 com.ecep.contract.ContractApplication
2. 客户端: 运行客户端的启动类

3. 访问应用

• 服务端: http://localhost:8080
• 客户端: 运行 JavaFX 应用后打开界面
• API 文档: http://localhost:8080/swagger-ui.html

📝 开发流程

1. 日常开发

# 获取最新代码
git pull origin main

# 创建功能分支
git checkout -b feature/your-feature-name

# 开发功能...

# 提交代码
git add .
git commit -m "feat: add new feature description"

# 推送分支
git push origin feature/your-feature-name

# 创建 Pull Request

2. 代码质量检查

# 代码检查
mvn checkstyle:check

# 静态分析
mvn spotbugs:check

# 测试覆盖率
mvn jacoco:report

3. 数据库迁移

# 执行数据库脚本
mysql -u contract_manager -p contract_manager < docs/db/your_migration.sql

# 或使用 Flyway (如已配置)
mvn flyway:migrate

🔧 IDE 配置

IntelliJ IDEA 配置

代码样式

<!-- 设置 UTF-8 编码 -->
File → Settings → Editor → File Encodings → Global Encoding: UTF-8

<!-- 设置 JDK -->
File → Project Structure → Project → SDK: 21

Maven 配置

<!-- 设置本地仓库路径 -->
File → Settings → Build → Maven → User Settings File: settings.xml

<!-- 设置 Maven HOME -->
File → Settings → Build → Maven → Maven home directory: /path/to/maven

插件配置

<!-- Lombok 插件 -->
Settings → Build → Compiler → Annotation Processors → Enable annotation processing

<!-- 代码格式化 -->
Settings → Tools → External Tools → 配置格式化命令

Git 配置

# 设置用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 设置默认分支
git config --global init.defaultBranch main

# 启用自动换行转换
git config --global core.autocrlf true

🔍 常见问题

1. 编译错误

Java 版本不匹配

# 检查 Java 版本
java -version

# 设置正确的 JAVA_HOME
echo $JAVA_HOME

依赖下载失败

# 清理 Maven 仓库
mvn dependency:purge-local-repository

# 强制更新依赖
mvn clean install -U

2. 数据库连接问题

连接被拒绝

# 检查 MySQL 服务状态
sudo systemctl status mysql

# 检查端口占用
netstat -an | grep 3306

权限问题

-- 检查用户权限
SHOW GRANTS FOR 'contract_manager'@'localhost';

-- 重新授权
GRANT ALL PRIVILEGES ON contract_manager.* TO 'contract_manager'@'localhost';
FLUSH PRIVILEGES;

3. Redis 连接问题

Redis 服务未启动

# 启动 Redis
sudo systemctl start redis-server

# 检查 Redis 状态
sudo systemctl status redis-server

端口占用

# 检查 Redis 端口
netstat -an | grep 6379

# 重启 Redis
sudo systemctl restart redis-server

4. 客户端启动问题

JavaFX 版本不匹配

<!-- 检查 pom.xml 中的 JavaFX 版本 -->
<properties>
    <maven.compiler.release>21</maven.compiler.release>
    <javafx.version>21</javafx.version>
</properties>

依赖冲突

# 清理客户端模块
cd client
mvn clean

# 重新导入依赖
mvn dependency:tree

📚 有用的命令

Maven 命令

# 清理项目
mvn clean

# 编译
mvn compile

# 打包
mvn package

# 运行测试
mvn test

# 运行特定测试
mvn test -Dtest=CompanyServiceTest

# 跳过后测试打包
mvn package -DskipTests

# 查看依赖树
mvn dependency:tree

# 依赖分析
mvn dependency:analyze

数据库操作

# 连接到数据库
mysql -u contract_manager -p

# 备份数据库
mysqldump -u contract_manager -p contract_manager > backup.sql

# 恢复数据库
mysql -u contract_manager -p contract_manager < backup.sql

# 查看表结构
SHOW TABLES;
DESCRIBE table_name;

Redis 操作

# 连接 Redis
redis-cli

# 查看所有键
KEYS *

# 清空数据库
FLUSHDB

# 监控命令
redis-cli monitor

🎯 性能优化建议

开发环境优化

1. 使用 SSD 硬盘: 加快构建和部署速度
2. 增加内存: 至少 8GB RAM，推荐 16GB+
3. 关闭不必要程序: 释放系统资源

IDE 优化

1. 启用编译缓存: Settings → Build → Compiler → Use build cache
2. 配置启动内存: -Xmx4g -Xms2g
3. 禁用不必要的插件: 减少启动时间

数据库优化

1. 连接池配置: 调整 HikariCP 连接池参数
2. 索引优化: 为常用查询字段添加索引
3. 查询优化: 避免 N+1 查询问题

---

本指南涵盖了 Contract-Manager 项目的完整开发环境配置。如有问题，请参考故障排除部分或联系项目维护者。