rui-docs/backend/guides/environment-setup.md

环境搭建指南

适用范围: 新加入的开发者
预计耗时: 30-60 分钟

---

一、必要工具安装

1.1 JDK 21

# macOS (使用 Homebrew)
brew install openjdk@21

# 验证
java -version
# Expected: openjdk version "21"

1.2 Maven 3.9+

# macOS
brew install maven

# 验证
mvn -version
# Expected: Apache Maven 3.9.x

1.3 MySQL 8.0

# macOS
brew install mysql@8.0
brew services start mysql@8.0

# 验证
mysql --version
# Expected: mysql Ver 8.0.x

1.4 Node.js 18+ 和 pnpm

# macOS
brew install node@18
npm install -g pnpm

# 验证
node --version
pnpm --version

1.5 Git

# macOS
brew install git

# 验证
git --version

---

二、项目初始化

2.1 克隆项目

git clone <repository-url>
cd spring-ai

2.2 配置本地开发环境

# 创建本地配置文件
cp backend/config/application-dev.yml.example backend/config/application-dev.yml

# 编辑配置（使用你的数据库连接信息）
# vim backend/config/application-dev.yml

配置示例：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/rui_platform?useUnicode=true&characterEncoding=utf8
    username: root
    password: your_password

2.3 初始化数据库

# 创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS rui_platform CHARACTER SET utf8mb4;"

# 执行初始化脚本
mysql -u root -p rui_platform < sql/init-database.sql

2.4 编译项目

cd backend
mvn clean install -DskipTests

Expected: BUILD SUCCESS

---

三、IDE 配置

3.1 IntelliJ IDEA

1. 打开项目（选择 backend/pom.xml）
2. 启用 Annotation Processing：
   • Settings → Build → Annotation Processors
   • 勾选 "Enable annotation processing"
3. 配置代码风格：
   • Settings → Editor → Code Style → Java
   • Import Scheme → Project

3.2 VS Code（前端）

1. 安装推荐插件：
   • ESLint
   • Prettier
   • Vue Language Features
2. 配置自动格式化：

   {
     "editor.formatOnSave": true,
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
   

---

四、验证清单

完成以上步骤后，请确认：

• java -version 显示 JDK 21
• mvn -version 显示 Maven 3.9+
• mysql --version 显示 MySQL 8.0+
• backend/mvn clean install -DskipTests 执行成功
• 数据库 rui_platform 已创建
• IntelliJ IDEA 已配置 Annotation Processing

---

五、常见问题

Q1: Maven 编译失败

可能原因: JDK 版本不对
解决: 确认 JAVA_HOME 指向 JDK 21

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Q2: 数据库连接失败

可能原因: MySQL 未启动或配置错误
解决:

brew services start mysql
# 检查 application-dev.yml 中的连接信息

Q3: Lombok 注解不生效

可能原因: Annotation Processing 未启用
解决: 按 3.1 节启用