降SpringAI阿里第2掌-飞龙在天-筑基环境

降SpringAI阿里第2掌-飞龙在天-筑基环境

环境不统一，后面全是坑。

[读者] 正在尝试 Spring AI Alibaba 的 Java 开发者
[痛点] 依赖冲突、环境差异、跑不起来官方示例
[现在读] 需要一套可复现的统一开发基线
[读完] 能在一台新机器上从零跑通 ChatBot 并调试

[旧方案] 手动拼凑 Spring AI 与 Extensions 版本
    |
    v
[新需求] 需要稳定、可复现的 Spring AI Alibaba v1.1.2.2 环境
    |
    v
[冲突] 版本不匹配、JDK 五花八门、工具缺失，示例跑不通
    |
    v
[后果] 时间浪费在环境上，无法聚焦业务与 Agent 开发

我是老李，一个在深圳摸爬滚打多年的架构师。最近团队要启动一个数字人项目，技术栈选定 Spring AI Alibaba v1.1.2.2。项目刚立项，第一个任务就是统一开发基线，让每个人都能快速跑起来。

团队里有人用 JDK 8，有人用 17，有人用 21；有人用 IDEA，有人用 Eclipse；有人手动加依赖，结果 Spring AI 和 Extensions 版本对不上，启动就报 NoSuchMethodError。这样的环境，根本没法协作。

怎么办？是继续各自为战，还是强制统一？

统一之后，又怎么保证新机器能一键复现？

选错了，后面每个章节都要在环境问题上反复折腾；选对了，才能把精力放在框架能力上。

01、故事

时间：2024年某月，深圳。团队接到一个数字人项目，需要快速搭建一个 AI 对话系统。技术选型会上，我拍板使用 Spring AI Alibaba，版本锁定 v1.1.2.2。任务是搭建一套统一的开发环境，让所有成员都能克隆代码、配置密钥、启动官方 ChatBot 示例，并能断点调试。

当时，团队尝试直接手动引入依赖，有人用 Spring AI 1.0.0，有人用 Extensions 1.0.0-M2，结果项目启动失败，报错 ClassNotFoundException。还有人本地 JDK 是 11，编译都过不去。

我们意识到，必须有一个统一、可复现的基线。这个基线要包括：JDK 21 LTS、Maven Wrapper、Git、IDEA、curl、Docker，以及模型 API Key 的配置方式。更重要的是，依赖版本必须由 SAA BOM 统一管理，不能各写各的。

这个基线，就是数字人项目的地基。

基不牢地动山摇
版不齐事倍功半
统一工具链
方能快起步

02、问题

旧方案是：每个开发者根据自己的习惯安装环境，手动在 pom.xml 中添加依赖，版本凭记忆或搜索。业务影响是：新成员加入需要一两天才能跑通项目，甚至跑不通；技术表现是：编译报错、启动报错、模型调用失败。我们需要的完成标准是：在一台全新机器上，按照文档执行 clone → 配置 Key → 运行 ./mvnw -pl examples/chatbot spring-boot:run → 浏览器访问 → 能对话 → IDEA 断点生效 → 模块级测试通过。

这个标准必须可验证，不能含糊。

标准不清晰
验证无依据
一步一命令
结果可复现

03、原理

Spring AI Alibaba 是一个基于 Spring AI 的框架，它提供了 DashScope 等模型接入、MCP、RAG、Agent 等能力。官方最低要求 JDK 17，但本教程统一使用 JDK 21 LTS，因为 21 是长期支持版本，且 Spring Boot 3.x 对 21 支持更好。另一个反直觉判断是：不要追求最新版本，而应该锁定一个经过验证的版本，比如 v1.1.2.2，并让 BOM 管理所有依赖。手工拼接版本会导致传递依赖冲突，而 BOM 能保证版本一致性。

为什么使用 mvnw？因为它能保证所有开发者使用相同的 Maven 版本，避免因 Maven 版本差异导致的构建问题。为什么优先 DashScope/Qwen？因为它是阿里云官方模型，与 Spring AI Alibaba 集成度最高，且国内访问稳定。另备 OpenAI-compatible 或 DeepSeek 作为切换验证，是为了测试框架的模型抽象层是否正常工作。

这些原理支撑了后面的架构和实战。

版本要锁定
依赖交BOM
工具需统一
原理心中明

04、架构

[输入] 开发者执行 clone 与启动命令
    |
    v
[模块] JDK 21 + Maven Wrapper + SAA BOM
    |
    v
[数据/状态] 环境变量 AI_DASHSCOPE_API_KEY
    |
    v
[处理] Spring Boot 加载 ChatClient 与 DashScope 模型
    |
    v
[输出] ChatBot 示例可访问，支持对话与调试

边界：这个架构只解决开发环境统一问题，不涉及生产部署。收益：新成员可快速上手，依赖冲突归零。代价：需要所有成员安装 JDK 21 并配置环境变量。适用条件：使用 Spring AI Alibaba v1.1.2.2 及兼容版本。

架构分层明
边界要划清
收益与代价
权衡而后行

05、实战一次

环境：macOS / Linux / Windows WSL2，JDK 21，Git，IDEA，curl，Docker。版本：Spring AI Alibaba v1.1.2.2。

首先，安装 JDK 21。推荐使用 SDKMAN 或直接下载。配置 JAVA_HOME。

sdk install java 21.0.3-tem
sdk use java 21.0.3-tem
java -version

输出示例：

openjdk version "21.0.3" 2024-04-16 LTS

然后克隆官方示例仓库或本教程仓库。为了验证基线，我们直接使用官方 examples 中的 chatbot。

git clone https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba
git checkout v1.1.2.2

注意：官方 examples 在仓库的 examples 目录下。我们使用 mvnw 运行 chatbot 模块。

./mvnw -pl examples/chatbot spring-boot:run

但在运行前，需要设置 DashScope API Key。环境变量：

export AI_DASHSCOPE_API_KEY=sk-xxxx

application.yml 中已经配置了读取该环境变量。启动后，控制台输出 Tomcat 启动端口，默认 8080。访问 http://localhost:8080 或者使用 curl 测试。

curl http://localhost:8080/chat?message=你好

示例输出：

你好！我是 Spring AI Alibaba 的 ChatBot，很高兴为你服务。

然后，在 IDEA 中打开项目，找到 ChatBot 的 Controller，打上断点，再次请求，断点命中。模块级测试运行：

./mvnw -pl examples/chatbot test

测试通过。

至此，V1 环境跑通。

克隆即用
配置即通
断点可调
测试有据

06、排查

现象一：启动时报错 "java.lang.UnsupportedClassVersionError: ... class file version 61.0"。怀疑：JDK 版本不对。检查：运行 java -version，发现是 JDK 17。证据：类文件版本 61 对应 JDK 17，而项目要求编译版本 65（JDK 21）。根因：本地 JAVA_HOME 指向旧版本。修复：安装并切换 JDK 21。

错误尝试： 在 pom.xml 中降低 maven.compiler.source 到 17。为什么错误？因为 Spring AI Alibaba v1.1.2.2 依赖的 Spring Boot 3.4.x 要求 JDK 17+，但官方推荐 21，且部分依赖可能用到了 21 的特性。降级可能引发其他不兼容问题，应保持与官方一致。

现象二：启动时提示 "No qualifying bean of type 'ChatModel'"。怀疑：依赖没引入。检查：查看 pom.xml，发现手动添加了 spring-ai-dashscope-spring-boot-starter 版本 1.0.0，而不是 SAA BOM 管理的版本。证据：Maven 依赖树中出现了多个 Spring AI 核心包的不同版本。根因：版本冲突导致自动配置失效。修复：使用 SAA BOM 管理依赖，移除手动版本号。

排查看证据
根因定方向
修复要彻底
避免再踩坑

07、优化

根据第 06 章的根因，我们优化 V1：统一使用 SAA BOM。在根 pom.xml 中导入 BOM：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.alibaba.cloud.ai</groupId>
      <artifactId>spring-ai-alibaba-bom</artifactId>
      <version>1.1.2.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

然后子模块引入 starter 不写版本：

<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>

原因：BOM 管理了所有 Spring AI 和 Extensions 的版本，确保一致性。新行为：依赖树干净，无冲突。验证：重新运行 ./mvnw -pl examples/chatbot spring-boot:run，启动成功，对话正常。

另外，在 IDEA 中配置 Reactor 调试：可以在启动配置中添加 VM 参数 -Dreactor.trace.operatorStacktrace=true，方便排查响应式流问题。但本篇不深入，后续章节再讲。

依赖归BOM
版本自统一
调试加参数
问题无处藏

08、演进

[同一输入] 克隆代码并启动 ChatBot
    |
    +--[V1] 手动拼版本 / 启动失败，调试困难
    |
    +--[V2] SAA BOM 统一管理 / 启动成功，可断点调试
    |
[Trade-off]
得到：可复现的开发环境，依赖冲突归零
失去：灵活性降低，必须遵循 BOM 版本
适用边界：开发、测试环境；生产环境仍需考虑部署

比较：V1 正确性差，稳定性低，复杂度高（需要手动解决冲突），成本高（时间浪费）。V2 正确性高，稳定性高，复杂度低，成本低。遗留问题：K8s 工具尚未安装，后续章节补充。

演进有代价
取舍需权衡
基线虽简单
价值在长远

09、洞见

9.1 环境统一是团队协作的第一性原理

反直觉判断：很多人认为环境是个人的事，但团队协作中，环境必须是共享资产。只有统一，才能让问题聚焦在代码本身。

9.2 版本锁定比追求最新更可靠

反直觉判断：最新版本往往有未知坑，而锁定一个经过验证的版本（如 v1.1.2.2）能避免大量兼容性问题。BOM 是版本锁定的最佳实践。

9.3 官方示例是最佳入门路径

官方 examples 提供了可运行的 ChatBot，直接用来验证环境，比从头写 demo 更高效。从官方示例入手，能快速理解框架结构。

9.4 调试能力要提前建设

断点、Reactor 调试、模块级测试，这些调试能力应在项目初期就配好，否则后期排查问题效率极低。

洞见来自实践
判断源于证据
环境即代码
统一即效率

10、系统落地

原来：团队各自为战，环境混乱。本篇新增：统一开发基线，包括 JDK 21、Maven Wrapper、SAA BOM、DashScope Key 配置、官方 ChatBot 运行与调试。现在能做什么：任何成员可在全新机器上快速启动 ChatBot 并调试。还缺什么：模型切换验证、K8s 工具链。下一步：在第 3 章中，我们将基于这个基线，搭建数字人项目的底座。

落地有基线
后续有方向
步步为营
稳扎稳打

11、小结

Q1 → 统一 JDK 21、mvnw、IDE、Docker，使用 SAA BOM 管理依赖。
Q2 → 配置 AI_DASHSCOPE_API_KEY，运行 ./mvnw -pl examples/chatbot spring-boot:run，验证对话与断点。
Q3 → 确保全新机器可复现，模块测试通过，环境变量生效。
状态 → 完成统一开发基线，官方 ChatBot 可运行、可调试、可测试。

小结有答案
问题不再悬
基线已建成
扬帆再起航

12、作业

12.1 理解题：为什么本教程强制使用 JDK 21 而不是 JDK 17？

参考答案：官方最低要求 JDK 17，但 JDK 21 是 LTS，且 Spring Boot 3.x 对 21 支持更完善，统一使用 21 可避免版本碎片化，利于长期维护。

12.2 实战题：在你的机器上从零克隆 spring-ai-alibaba 仓库， checkout v1.1.2.2，并运行 examples/chatbot，记录所有步骤和遇到的错误。

参考答案：步骤包括安装 JDK 21、Git、Maven Wrapper 自动下载、设置环境变量、运行命令。可能的错误包括 JDK 版本不对、API Key 未设置等，需根据错误信息排查。

12.3 排障题：启动 ChatBot 时报错 "Cannot resolve symbol 'spring-ai-dashscope-spring-boot-starter'"，如何解决？

参考答案：检查 pom.xml 是否通过 SAA BOM 管理依赖，确保依赖坐标正确，版本由 BOM 提供，不要手动指定版本。

12.4 架构判断题：如果团队中有人坚持使用 JDK 17，你该如何说服他统一到 JDK 21？

参考答案：从协作效率、长期维护、框架兼容性角度说明统一的价值，并指出 JDK 21 是 LTS，官方推荐，减少因环境差异导致的问题。

作业练思维
理解加实践
排障有方法
判断见格局

13、思考

回到本篇的核心冲突：环境不统一导致协作效率低下。可复用的工程判断是：在项目启动阶段，必须优先建立可复现的开发基线，包括统一 JDK、构建工具、依赖管理、模型接入和调试能力。不要等到问题暴露才补救。基线一旦建立，后续所有开发都建立在其上，价值远超一次性投入。

统一是前提
基线是保障
冲突化动力
工程无止境