Spring AI 项目中的 pom.xml、application.yml 与 Nacos：从依赖管理到运行配置

在 Spring AI 项目中，pom.xml、application.yml 和 Nacos 经常同时出现。三者看起来都在"配置项目"，实际对应软件运行过程中的不同阶段。理解它们的关键是建立一条连续的工程链路：Maven 决定项目具备哪些能力，Spring Boot 决定这些能力怎样运行，Nacos 管理运行过程中需要集中维护和动态变化的配置。

一、pom.xml：定义项目具备哪些能力

pom.xml 属于 Maven 构建配置，主要作用是管理依赖、版本和构建过程。一个 Spring AI 项目能够使用 Chat Model、Vector Store、Redis、Web 等组件，前提是对应 Java 类已经通过 Maven 依赖进入项目的 Classpath。

例如项目需要使用 Spring AI 的某个模型 Starter，就需要先引入相应依赖。对于 Spring AI、Spring Cloud 这类包含大量模块的生态，通常还会使用 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>

这里需要区分 dependencyManagement 和 dependencies。前者主要声明版本管理规则，并不会自动把所有组件加入项目；真正使用某个 Starter 时，仍然需要在 dependencies 中引入对应依赖。

因此，pom.xml 解决的核心问题可以概括为：项目在编译和运行时拥有哪些代码能力。

这也解释了为什么切换不同 Vector Store 时，往往需要修改 Maven 依赖。即使 application.yml 中写好了 Elasticsearch 或 Redis 的地址，如果项目中没有对应的实现类和 Starter，Spring Boot 也无法创建相关 Bean。配置只能控制已有能力，不能凭空增加新的 Java 实现。

二、application.yml：定义应用启动后的运行方式

依赖进入项目以后，还需要告诉这些组件具体怎样运行，这就是 application.yml 的职责。

常见配置包括：

yaml 复制代码

server:
  port: 8080

spring:
  application:
    name: ai-service

Spring AI 项目还会加入模型名称、服务地址、超时时间、数据库、Redis 或向量存储等参数。pom.xml 告诉项目"拥有某个模型客户端"，application.yml 则进一步说明"这个客户端连接哪里、使用什么参数"。

这两者之间存在非常清晰的先后关系：

text 复制代码

pom.xml
    ↓
组件进入 Classpath
    ↓
Spring Boot 自动配置
    ↓
读取 application.yml
    ↓
创建并配置 Bean

Spring Boot Starter 的价值就在这里。它通常会提供 Auto Configuration，根据项目中是否存在某些类、相关配置是否存在，以及开发者是否已经自定义 Bean，自动完成对象装配。因此在 Spring AI 中可以直接注入部分 Builder 或 Model 对象，本质上是 Spring Boot 已经根据依赖和配置完成了初始化。

三、Profile：分离公共配置与环境差异

一个项目通常会运行在本地开发、测试和生产等不同环境中。数据库地址、Redis 地址、日志级别等参数很可能不同，如果全部写进同一个配置文件，后续维护会逐渐混乱。

Spring Boot 因此提供 Profile 机制。例如：

text 复制代码

application.yml
application-local.yml
application-dev.yml
application-prod.yml

application.yml 可以保存相对稳定的公共配置，不同 Profile 文件保存环境差异。在本地开发环境中，可以通过：

yaml 复制代码

spring:
  profiles:
    active: local

加载对应配置。

Profile 名称没有统一要求，项目可以采用 local/dev/test/prod，也可以使用其他环境划分。真正需要掌握的是一个设计原则：稳定配置与环境差异应该分开管理。

这一步以后，配置已经从"所有参数写在一个文件中"发展成了"不同环境拥有不同运行参数"。

四、Nacos：管理外部化与动态配置

继续向生产环境发展，又会出现新的问题。有些参数在程序运行以后仍然可能变化，例如模型名称、Prompt、灰度开关、限流阈值等。如果每次修改这些参数都重新修改配置文件、构建项目并发布服务，维护成本会明显增加。

Nacos 的配置中心能力就是在这一阶段发挥作用。Nacos 官方将动态配置管理和服务发现列为其核心能力 ，其中动态配置支持集中管理 和运行期更新配置 ，服务发现则负责维护当前可用的服务实例。Nacos 官网

因此，在 Spring AI 项目中，可以把变化频率较高的参数放入外部配置中心：

复制代码

模型名称
Prompt 配置
业务开关
超时时间
限流参数

应用启动时读取这些参数，配置发生变化后还可以通过监听机制更新当前值。这样，配置生命周期已经与代码发布生命周期分离。

需要强调的是，微服务并不要求必须使用 Nacos。Nacos 是服务发现和配置管理的一种实现方案。项目是否采用它，应由现有 Spring Cloud 技术栈和基础设施决定。

五、三类配置的完整协作关系

把三者放在一起以后，整个结构就非常清晰：

复制代码

pom.xml
决定项目具备什么能力
        ↓
application.yml
决定这些能力怎样启动
        ↓
Nacos
管理运行时需要集中维护和动态变化的参数

以一个模型客户端为例，Maven Starter 首先让项目具备调用模型的代码能力；Spring Boot 根据 application.yml 和自动配置机制创建模型相关 Bean；模型名称、Prompt 或部分运行参数还可以进一步从 Nacos 中读取。

因此，三者并不是三个彼此独立的"配置文件"，而是分别对应构建期、启动期和运行期。这也是理解这篇文章最重要的一条主线。

六、配置内容的放置原则

明确三层结构以后，实际项目中还需要判断一个参数应该放在哪里。可以使用一套简单规则。

依赖版本、Starter 和 Java 库属于构建期，放在 pom.xml；端口、服务名称和默认组件配置属于应用运行参数，可以放在 application.yml；模型切换、Prompt、业务开关等需要集中调整的参数适合进入配置中心。

API Key、数据库密码等敏感信息还需要单独考虑安全性。配置中心能够解决外部化问题，却不意味着普通明文配置就是理想的生产方案。敏感凭据应结合环境变量、Secret 管理、权限控制和日志脱敏进行处理。

最终可以形成四类判断：

复制代码

代码依赖       → pom.xml
稳定运行参数   → application.yml
环境差异       → Profile / 环境配置
动态运行参数   → Nacos 等配置中心

七、版本兼容与依赖排查

Spring AI、Spring Boot 和 Spring Cloud 之间存在版本兼容关系，因此升级时不能只修改一个版本号。截至 2026 年 10 月，Spring AI 官方最新稳定版为 2.0.1，官方兼容说明指出 2.0.x 支持 Spring Boot 4.0.x 和 4.1.x 。Home

遇到依赖问题时，可以按照固定顺序排查：首先确认 JDK 和 Spring Boot 版本，再检查 Spring AI BOM 和相关 Starter，随后检查 Spring Cloud 体系，最后通过 mvn dependency:tree 查看实际依赖树。

NoSuchMethodError、ClassNotFoundException 等异常很多时候并非业务代码错误，而是依赖版本组合不一致。BOM 的价值就在于减少这一类模块间版本冲突。

八、总结

pom.xml、application.yml 和 Nacos 分别解决三个不同阶段的问题。pom.xml 管理项目拥有的依赖和能力；application.yml 描述应用启动以后如何运行；Nacos 将需要集中管理和动态修改的运行参数从应用中进一步外置。

三者之间可以用一句话概括：

Maven 管能力，Spring Boot 配置管运行，配置中心管变化。

理解这一层关系以后，再看到模型 Starter、Vector Store、Profile、Prompt 热更新或服务注册时，就可以直接判断它属于哪一个阶段，而不需要逐个背配置项。对于 Spring AI 项目而言，这种配置分层能力本身就是标准 Java 工程能力在 AI 应用中的自然延伸。