CH 00环境准备

0.1版本基准：本课程所有代码基于这套环境

先记住这张表。全课程的每一行代码、每一条命令，都以它为基准。版本不一致是学生环境问题里占比最高的一类——遇到报错先回来对照这张表，再动手排查。

0.2软件清单与检查命令

★ 先看这里：三种终端的命令差异（照抄命令前必读）

后面每一章都会给可以直接复制的命令。但同一句命令在三种终端里不一定都能跑——这是学生"照抄了却报错"的第一大来源。花 3 分钟看完这张表，能省掉后面几十次无效排查。

把重复命令固化成一键脚本（强烈建议）

环境准备好之后，你会反复执行三类命令：清端口 → 启动应用 → 打接口验证。每次手敲既慢又容易错，建议在工程根目录存成三个脚本（本课程配套 lab 已自带，可直接用）：

① stop-app.ps1：解决「Port 8080 was already in use」（写成文件执行，避免长命令在终端里被引号拆坏）：

# stop-app.ps1 —— 找到并结束占用 8080 的进程
$pids = (netstat -ano | Select-String ":8080\s+.*LISTENING") -replace '.*\s+(\d+)$', '$1' | Sort-Object -Unique
if (-not $pids) { Write-Host "8080 未被占用"; exit }
foreach ($p in $pids) {
    Write-Host "结束进程 PID=$p"
    Stop-Process -Id $p -Force -ErrorAction SilentlyContinue
}
Write-Host "完成"

② start-app.ps1：把密钥注入本次会话再启动（避免"设了环境变量但进程读不到"）：

# start-app.ps1 —— 从用户级环境变量取密钥，注入当前会话后启动
$env:DEEPSEEK_API_KEY = [Environment]::GetEnvironmentVariable("DEEPSEEK_API_KEY", "User")
if (-not $env:DEEPSEEK_API_KEY) { Write-Host "找不到 DEEPSEEK_API_KEY，请先按 0.6 节设置"; exit 1 }
Set-Location "D:\path\to\lab"        # ★ 换成你自己的 pom.xml 所在目录
.\mvnw.cmd spring-boot:run

③ test-chat.ps1：一发请求验证服务真的活了（用 Invoke-RestMethod 绕开 curl 的引号问题）：

# test-chat.ps1 —— 冒烟测试：服务能收到请求并返回模型回答
try {
    $r = Invoke-RestMethod -Uri http://localhost:8080/api/v1/chat/ask `
         -Method Post -ContentType "application/json" `
         -Body '{"question":"只回答两个字：收到"}'
    Write-Host "成功：" -ForegroundColor Green; $r
} catch {
    Write-Host "失败：$_" -ForegroundColor Red
    Write-Host "排查：① 应用起来了吗（8080 是否监听）② 密钥非空吗 ③ 端口是否被别的程序占用" -ForegroundColor Yellow
}

运行方式（在脚本所在目录打开 PowerShell）：

powershell -ExecutionPolicy Bypass -File .\stop-app.ps1
powershell -ExecutionPolicy Bypass -File .\start-app.ps1
powershell -ExecutionPolicy Bypass -File .\test-chat.ps1

0.3安装 JDK 17 并验证

1. 下载并安装 JDK 17（推荐 Temurin 17，免费、无登录；Oracle 版本也可以）。安装时记下安装路径，例如 Windows 的 C:\Program Files\Java\jdk-17。

2. 配置环境变量 JAVA_HOME 指向安装根目录，并把 %JAVA_HOME%\bin（macOS/Linux 为 $JAVA_HOME/bin）加入 Path。IDEA 通常能自动识别，但命令行构建（第 11 章打包部署）依赖它。

3. 关掉所有已打开的终端窗口，重新开一个（环境变量改完不重开终端不生效——这是新手第一大坑），执行：

   java -version

   看到类似下面的输出即为成功：

   openjdk version "17.0.x" 2025-xx-xx
   OpenJDK Runtime Environment Temurin-17.0.x ...
   OpenJDK 64-Bit Server VM Temurin-17.0.x ...

0.4安装 IDEA

1. 下载 IDEA Community（社区版），安装时勾选「创建桌面快捷方式」和「添加到 PATH」（可选）。
2. 首次启动选择你喜欢的主题即可，不需要安装任何 AI 相关插件。本课程不使用 Lombok（所有 getter/setter 用 Java record 或手写，目的是让学生看全每一行代码），所以也不装 Lombok 插件。
3. 中文界面插件可选装（Plugins → 搜索 Chinese），不影响任何功能。

0.5配置 Maven（国内镜像，必做）

Maven 默认从国外中央仓库下载依赖，国内直连速度慢甚至超时。这一步不做，第 1 章第一次构建就会卡死在下载依赖上。

1. 找到 Maven 的配置文件 settings.xml：

   • 独立安装的 Maven：在安装目录 conf/settings.xml；
   • 建议复制一份到 ~/.m2/settings.xml（用户级配置，升级 Maven 不丢失）。

2. 在 <settings> 标签内加入以下两段（完整文件可直接照抄）：

   <?xml version="1.0" encoding="UTF-8"?>
   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
   
     <!-- ① 本地仓库路径：依赖 jar 包的存放位置。
          默认在 C 盘用户目录，建议改到 D 盘等其他数据盘 -->
     <localRepository>D:/maven-repo</localRepository>
   
     <mirrors>
       <!-- ② 阿里云公共仓库：国内下载依赖快且稳 -->
       <mirror>
         <id>aliyunmaven</id>
         <mirrorOf>central</mirrorOf>
         <name>阿里云公共仓库</name>
         <url>https://maven.aliyun.com/repository/public</url>
       </mirror>
     </mirrors>
   
   </settings>

3. 验证（重开终端）：

   mvn -v

   输出里确认两行：Maven 版本 ≥ 3.6.3，Java version 是 17。Maven 运行用的 JDK 和 JAVA_HOME 指向的一致，如果这里显示的不是 17，回去检查 JAVA_HOME。

4. IDEA 侧确认：File → Settings → Build Tools → Maven，把 Maven home path 指向你的 Maven 目录，User settings file 勾选 Override 并指向刚改的 settings.xml。

0.6申请 DeepSeek API Key

课程默认使用 DeepSeek（便宜、OpenAI 协议兼容、注册即用）。流程五步：

1. 打开 deepseek.com，右上角进入「API 开放平台」，用手机号注册登录（是开放平台，不是聊天 App）。
2. 左侧「充值」：先充 1～10 元即可。deepseek-chat 计价极低，做完全部课程实验花不了几块钱。
3. 左侧「API keys」→「创建 API key」，名称随意（如 springai-course）。
4. 创建后立刻复制保存——弹窗关掉后就再也看不到完整 key 了，只能重新创建。key 形如 sk-63956d56xxxxxxxxxxa3e4c2fc。
5. 把 key 设置为环境变量（见下），不要写在任何源码文件里。

Windows（PowerShell，设置后重开终端生效）：

setx DEEPSEEK_API_KEY "sk-你的完整key"

macOS / Linux（写入 ~/.zshrc 或 ~/.bashrc 后 source 生效）：

export DEEPSEEK_API_KEY="sk-你的完整key"

0.7创建课程工程（两种方式任选）

方式 A（推荐）：使用课程配套工程 springai-lab

课程提供配套可运行工程 springai-lab，与教程代码逐字一致、每行都有中文注释，已随本课程包放在本教程目录的 lab/ 文件夹。使用：

1. IDEA → Open → 选中 lab 目录（认准有 pom.xml 的那层）打开；
2. 等待右下角 Maven 同步完成（首次会下载依赖，配好镜像约 1～3 分钟）；
3. 检查 src/main/resources/application.yml 中密钥占位符与你的环境变量名一致。

方式 B：从零创建（体验完整流程）

1. 打开 start.spring.io，按下表选择：

2. Generate 下载 zip，解压后用 IDEA 打开；
3. 手动在 pom.xml 补上 spring-ai-bom 的 dependencyManagement 段（第 1 章会逐行讲解为什么必须有它）。

0.8全环境验收：三条命令

以下三条全部通过，环境才算就绪。课上教师逐人检查第 ①② 条的输出。

# ① JDK 版本（期望 17.x）
java -version

# ② Maven 版本 + 用的 JDK（期望 Maven ≥ 3.6.3，Java 17）
mvn -v

# ③ 环境变量里的密钥已就位（期望打印出 sk- 开头的 key，而不是空）
#    PowerShell:
echo $env:DEEPSEEK_API_KEY
#    macOS / Linux:
echo $DEEPSEEK_API_KEY

0.9常见问题排错表

0.10课堂练习与课后作业

0.11本章验收标准

• java -version、mvn -v、密钥 echo 三条命令输出全部符合预期（截图留存）。
• lab 工程能在 IDEA 中打开，Maven 同步无红线。
• 能口头说出：本课程的版本基准是什么、为什么密钥不能写进源码。
• 完成方式 B 的工程创建并提交 200 字依赖说明。