Java 工程师 LLM 工程化

Appearance

版本矩阵：把依赖一次定死 ​

1. 本节产出 ​

拿到一份可直接复制的依赖配置（含 Maven 仓库、BOM、starter 命名规则），并且学会在遇到版本冲突时的三步定位法。之后每一章都不再为环境问题分心。

2. 前置依赖 ​

3. 为什么版本问题在 Spring AI 里格外严重 ​

三个原因叠加：

  1. 框架年轻，跨版本有破坏性变更。Spring AI 从 1.0 GA 之后，starter 包名、部分 API 都调整过，网上大量教程用的是旧写法。
  2. 两个坐标要同时对齐：Spring Boot 版本 ↔ Spring AI 版本，其中之一不对就报各种奇怪的 NoSuchMethodError。
  3. 里程碑版本不在中央仓库。这是新手最常踩的坑：代码完全照抄，就是拉不到包。

典型故障现场：

java.lang.NoSuchMethodError: org.springframework.ai.chat.model.ChatResponse.getResult()

看起来是 API 用法错了，实际 99% 是 classpath 里混进了两个不同版本的 spring-ai 模块。

4. 核心原理：三条对齐规则 ​

规则一：大版本绑定 ​

Spring AI要求 Spring BootJDK 基线
1.x（如 1.1.x）3.x（3.4 / 3.5）17+
2.x（如 2.0.x）4.x17+，建议 21

提示：以官方发布的兼容矩阵为准。判断原则是大版本要匹配——AI 2.x 配 Boot 4.x，AI 1.x 配 Boot 3.x。混搭（AI 2.x + Boot 3.5）是最常见的作死姿势。

本课程的选择：主线演示走 Spring Boot 4.x + Spring AI 2.0.x + JDK 21。涉及 1.x 差异时，在章节内给出对照写法。

规则二：starter 命名 ​

Spring AI 1.0 GA 之后统一了命名，容易和老教程混淆：

类型旧命名（早期里程碑）现行命名
模型 starterspring-ai-spring-boot-starter-openaispring-ai-starter-model-openai
向量库 starterspring-ai-pgvector-store-spring-boot-starterspring-ai-starter-vector-store-pgvector

看到教程里出现 -spring-boot-starter- 这种中间式写法，就知道是老版本内容，直接按上表转换。

规则三：版本走 BOM，不逐个写 ​

所有 Spring AI 依赖都不要写 <version>，交给 BOM：

xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>${spring-ai.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
  </dependency>
</dependencies>

好处：模块之间版本天然一致，升级只需改一处。

5. 操作步骤 ​

步骤 1：加里程碑仓库 ​

如果选用的是尚未 GA 的版本（2.0.x 早期、各种 milestone），必须在 pom 里声明快照/里程碑仓库，否则拉不到：

xml
<repositories>
  <repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots><enabled>false</enabled></snapshots>
  </repository>
  <repository>
    <id>spring-snapshots</id>
    <name>Spring Snapshots</name>
    <url>https://repo.spring.io/snapshot</url>
    <snapshots><enabled>true</enabled></snapshots>
    <releases><enabled>false</enabled></releases>
  </repository>
</repositories>

提示：优先用 GA 版本。只有在确实需要新特性时才碰里程碑，并且要在 README 里记清楚，因为半年后你自己也会忘记配过这个仓库。

步骤 2：确认实际解析的版本 ​

bash
mvn dependency:tree | grep spring-ai

期望：所有 spring-ai-* 的版本号完全一致，只出现一个 spring-ai-core。

步骤 3：确认 Model Starter 实际生效 ​

启动应用，观察日志里有没有对应的自动配置类加载。更稳的办法是写个断言测试：

java
@SpringBootTest
class VersionMatrixTest {
    @Autowired ChatModel chatModel;

    @Test
    void shouldHaveChatModelBean() {
        assertThat(chatModel).isNotNull();
    }
}

能过，说明 starter 与自动配置都对上了。

步骤 4：锁定并写进 README ​

每个 demo 仓库的 README 里必须有一张「最低可运行版本矩阵」表：

组件本项目验证版本备注
JDK2117 可跑，个别语法需调整
Spring Boot4.1.x
Spring AI2.0.x需里程碑仓库
PGVectorpg16docker-compose 内提供
Redis7.xdocker-compose 内提供

6. 验证清单：三步定位法（出问题用这套） ​

步动作命令/方法
1看 classpath 有没有重复版本mvn dependency:tree | grep spring-ai
2看谁把旧版本带进来的mvn dependency:tree -Dincludes=org.springframework.ai
3排除掉传递依赖在引入方加 <exclusions>

绝大多数报错不需要改代码，把依赖理干净就好了。

7. 生产避坑 ​

  1. 不要混用两套版本体系。最典型的是 copy 老教程的 pom，把 spring-boot-starter-parent 3.x 和 spring-ai-bom 2.x 放一起。判断很简单：Boot 3 → AI 1，Boot 4 → AI 2。
  2. 里程碑版本的 demo 不要交付给学员当作业。它的 API 可能在你录完课两周就变了，会引发大量答疑。给学员的作业仓库一律锁 GA 版本，并在 dependencyManagement 里写死。
  3. 升级后必须跑一遍全量测试再录下一节。Spring AI 的 API 调整有时会只影响某个边缘方法，编译通过但运行报错，等到录屏现场才发现就晚了。

8. 延伸与锚点 ​

  • 思考题：你的公司现在用的是 Boot 2.x 还是 3.x？如果是 2.x，需要先评估升级路径——Spring AI 依赖较新的 Spring 框架版本，绕不过去。
  • 代码锚点：ch00-03-version-matrix
  • 下一章：00-04 成本速算