2. 项目初始化与环境搭建

说实话，很多新手拿到项目第一件事就是急着写代码。我见过太多团队，代码写了一半才发现 JDK 版本不对、依赖拉不下来、Git 分支乱成一锅粥。嗯，磨刀不误砍柴工，今天咱们就把这些基础工作做扎实。

这一章，我会带你走完三个关键步骤：用脚手架生成项目骨架、配置开发环境、初始化 Git 并制定分支策略。每一步我都会穿插一些实际踩过的坑，希望能帮你少走弯路。

2.1 脚手架：别从零开始

我个人习惯，不管项目大小，都先用脚手架生成基础结构。为什么？因为脚手架帮你解决了项目结构、构建配置、依赖管理这些重复劳动。你想想看，如果每个项目都手动配 Webpack 或 Maven，那得浪费多少时间？

我们这次的项目是一个典型的全栈应用，前端用 React + TypeScript，后端用 Spring Boot。所以我会分别用两个脚手架来生成。

2.1.1 前端项目：Create React App + TypeScript

虽然现在 Vite 很火，但 Create React App（CRA）对于教学项目来说，配置更透明，适合初学者理解底层原理。我在项目中遇到过几次因为 CRA 版本升级导致配置失效的情况，所以建议你锁定版本。

# 使用 npx 创建项目，指定模板为 TypeScript
npx create-react-app frontend --template typescript

# 进入项目目录
cd frontend

# 启动开发服务器
npm start

执行完上面三条命令，浏览器会自动打开 http://localhost:3000，看到 React 的默认页面就说明成功了。

2.1.2 后端项目：Spring Initializr

后端我推荐用 Spring Initializr。你可以访问 start.spring.io，或者像我一样用命令行生成。我个人更爱命令行，因为可以写脚本批量创建。

# 使用 curl 调用 Spring Initializr API
curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.2.0 \
  -d baseDir=backend \
  -d groupId=com.example \
  -d artifactId=app-framework \
  -d name=AppFramework \
  -d packageName=com.example.appframework \
  -d javaVersion=17 \
  -d dependencies=web,data-jpa,mysql,validation,lombok \
  -o backend.zip

# 解压
unzip backend.zip -d backend

这里我选了 Java 17 和 Spring Boot 3.2.0。为什么是 Java 17？因为它是 LTS 版本，而且 Spring Boot 3.x 已经不再支持 Java 8 了。我曾经有个项目因为用了 Java 8，导致 Spring Boot 3 的很多新特性用不了，最后不得不花两天时间升级，教训深刻。

2.2 开发环境配置：统一版本，避免「在我电脑上能跑」

「在我电脑上能跑啊！」——这大概是程序员最怕听到的话。说白了，环境不一致是协作开发的头号杀手。所以，咱们从一开始就把环境锁死。

2.2.1 JDK 配置

我们后端用 Java 17。我建议你用 SDKMAN 来管理多个 JDK 版本，比手动下载安装方便太多了。

# 安装 SDKMAN
curl -s "https://get.sdkman.io" | bash

# 安装 Java 17
sdk install java 17.0.9-tem

# 设置默认版本
sdk default java 17.0.9-tem

# 验证
java -version

2.2.2 Node.js 配置

前端需要 Node.js 18+。同样，我推荐用 nvm（Node Version Manager）来管理版本。

# 安装 nvm（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装 Node.js 18
nvm install 18

# 使用 Node.js 18
nvm use 18

# 验证
node -v
npm -v

Windows 用户可以用 nvm-windows，用法基本一样。

2.2.3 Python 配置（辅助工具）

虽然主项目是 Java + JavaScript，但我们会用 Python 写一些自动化脚本，比如批量生成数据、运行测试等。Python 3.10+ 就够了。

# 使用 pyenv 管理 Python 版本
brew install pyenv  # macOS
# 或
apt install pyenv  # Linux

# 安装 Python 3.11
pyenv install 3.11.0

# 设置全局版本
pyenv global 3.11.0

# 验证
python --version

2.3 Git 初始化与分支策略

版本控制是团队协作的基石。我见过太多团队在 Git 上翻车：有人直接在 master 上改代码，有人合并冲突不会处理，有人提交信息写「update」或「fix」。嗯，咱们从一开始就定好规矩。

2.3.1 初始化 Git 仓库

我们的项目结构是这样的：

app-framework/
├── frontend/          # React 前端
├── backend/           # Spring Boot 后端
├── docs/              # 文档
├── scripts/           # 自动化脚本
└── .gitignore

在根目录初始化 Git：

# 初始化仓库
git init

# 添加 .gitignore 文件
# 我习惯用 GitHub 的模板：https://github.com/github/gitignore

# 首次提交
git add .
git commit -m "chore: 初始化项目结构，包含前端和后端脚手架"

2.3.2 分支策略：Git Flow 简化版

完整的 Git Flow 对小型团队来说太重了。我个人习惯用简化版，只保留四个核心分支：

下面这张图展示了我们的分支流转关系：

2.3.3 分支命名规范

分支命名要能一眼看出用途。我常用的格式：

# 功能分支
feature/用户登录模块
feature/订单列表优化

# 修复分支
fix/修复空指针异常
fix/修复样式错乱

# 发布分支
release/v1.0.0
release/v1.1.0

2.3.4 提交信息规范

我推荐用 Conventional Commits 规范。这样不仅提交历史清晰，还能自动生成 changelog。

2.4 验证环境

所有配置完成后，我们做一次完整的验证：

1. 前端验证： cd frontend && npm start，确认页面正常显示
2. 后端验证： cd backend && ./mvnw spring-boot:run，确认控制台无报错
3. Git 验证： git log --oneline，确认首次提交存在