最近在给一个新项目做技术选型前期准备阶段差点被Maven依赖下载折腾到怀疑人生。项目打算用Spring AI做智能问答模块结果代码还没写一行光是在IDEA里拉取spring-ai相关的jar包就爆红大半天maven中央仓库连接超时、依赖下载到一半卡死、版本对不上各种问题轮着来。后来我把自己踩过的坑重新捋了一遍从Maven环境检查、镜像仓库配置到Spring AI到底该引哪些依赖整理出了一套适合新项目的开发前期准备清单。这篇东西就是把这套经验完整写出来给同样准备上手Spring AI的开发者做个参考尽量让大家少走弯路。1. 开发前期到底要准备什么Spring AI的版本、模型与接入方式1.1 Spring AI是什么从官方定位到实际价值Spring AI是Spring官方推出的AI应用开发框架它做的事情可以理解成“把和大模型对话这件事封装成了Spring风格的API”。以前我们接一个大模型要自己写HTTP客户端、处理请求参数、解析流式返回、管理会话上下文每个模型厂商的协议还不一样换一家就要改一堆代码。Spring AI把这一层统一掉了你用ChatClient、ChatModel这类抽象接口写业务代码底层对接OpenAI也好、通义千问也好、本地部署的DeepSeek也好只需要换依赖和配置。对Java开发者来说这个框架最大的价值是降低了AI功能的接入门槛。你可以像以前用JdbcTemplate操作数据库一样用几行代码完成一次模型调用。而且它天然融入Spring Boot生态配置项走application.yml依赖走Maven中央仓库或者Spring官方仓库对习惯了Spring开发范式的人几乎没有额外学习成本。我个人的判断是现在做Java后端如果要在项目里加AI能力Spring AI应该是优先级最高的候选方案。相比自己封装模型调用它省掉的不是一点点工作量。1.2 版本选型Spring AI 1.0 GA与2.0的取舍开始配置依赖之前先要把版本选清楚。Spring AI在1.0.0 GA版本发布之前有一段时间一直用快照版本SNAPSHOT那时候用起来确实有点痛苦依赖版本号每隔几天就变。现在1.0.0已经正式发布了对应的Spring Boot版本是3.2.x或者3.3.xJDK要求是17以上。最近网上也在传Spring AI 2.0的消息有一些文档和全链路实战案例放出来了。我的建议是如果不是做技术预研或者实验性项目正式项目先用1.0.x稳定版。原因很简单2.0版本对应的Spring Boot版本更高依赖树变化比较大很多第三方库的兼容性还没跟上。前期开发本来就要处理一堆环境问题没必要再给自己增加版本适配的负担。有一点要特别注意Spring AI的依赖管理需要用它的BOMBill of Materials否则版本号很容易冲突。官方文档里推荐的写法是在pom.xml的dependencyManagement中引入spring-ai-bom然后在具体依赖里不写版本号让BOM统一管理。这个习惯最好一开始就养成。1.3 模型接入方式云端API还是本地部署Spring AI支持两种模型接入方式一种是直接调用云平台的API比如通义千问、OpenAI、智谱等这种方式需要在配置里填API Key和模型名称另一种是对接本地部署的模型服务比如用Ollama跑一个DeepSeek或者用vLLM部署的模型服务这种方式走的是OpenAI兼容协议配置一个base-url指向本地端口就行。两种方式在Spring AI里的核心代码没有区别只是配置项和依赖不同。前期开发阶段我建议先用云端API把业务流程跑通因为云平台的模型稳定、接口响应快方便调试。等业务逻辑验证没问题了再切换到本地部署的模型做私有化交付。这样可以有效降低前期调试的复杂度。2. Maven环境搭建装对、配好、跑通三步走2.1 Maven到底是干嘛的依赖管理和构建的底层逻辑很多刚接触Spring AI的开发者其实真正的拦路虎不是AI概念而是Maven本身。Maven是一个Java项目的依赖管理和构建工具它做的事情可以通俗地理解为两个第一你告诉它项目需要哪些第三方库它自动去仓库里下载并管理这些jar包第二它负责把项目编译、测试、打包成一整套流程。Maven的核心配置文件是pom.xml里面声明了项目的依赖坐标每个坐标由groupId、artifactId、version三个要素组成。比如我们要引入Spring AI的核心依赖坐标就是io.spring.ai和spring-ai-openai-spring-boot-starter。Maven下载的jar包会存在一个本地仓库中默认在用户目录下的.m2/repository文件夹里。首次构建项目时本地仓库是空的所有依赖都要从远程仓库拉取这时候如果网络不稳定或者仓库地址不通就会出现依赖下载失败的情况。理解了这套逻辑后面排查问题就有方向了。依赖爆红也好构建失败也好本质上是Maven无法从远程仓库获取到对应的jar包要么是网络问题要么是坐标写错要么是仓库地址配置不对。2.2 安装Maven下载、解压、配置环境变量如果机器上还没有Maven需要先装一个。步骤不复杂但有几个细节值得注意。第一步去Maven官网下载二进制压缩包选择apache-maven-3.8.x或者3.9.x版本都可以不用刻意追求最新版。下载的时候注意选择bin.tar.gzLinux/macOS或者bin.zipWindows不要下成src源码包。第二步解压到本地目录。Windows用户建议解压到D:\dev\apache-maven这种纯英文路径下避免路径中出现中文和空格导致一些奇怪的问题。macOS用户可以用Homebrew安装执行brew install maven也可以手动解压到/usr/local目录下。第三步配置环境变量。Windows用户在系统变量的Path中新增Maven解压目录下的bin文件夹路径同时新建变量名M2_HOME指向Maven根目录。macOS和Linux用户需要编辑~/.bash_profile或者~/.zshrc添加export M2_HOME/path/to/maven和export PATH$PATH:$M2_HOME/bin。第四步验证安装。打开命令行执行mvn -v如果能看到Maven版本号和JDK版本信息说明环境变量配置成功。这里要提醒一下Maven依赖的JAVA_HOME环境变量也要正确配置否则即使Maven本身装好了执行时也会报找不到JDK的错误。2.3 IDEA集成三个关键的配置位置安装了Maven之后还需要在IDEA里配置好否则IDEA用的是自带Maven不一定符合我们的需求。打开IDEA的Settings在Build, Execution, Deployment下的Build Tools里找到Maven这里有几个关键配置项。第一个是Maven home path要指向我们自己安装的Maven解压目录而不是IDEA内置的Maven。第二个是User settings file这里要指向Maven的settings.xml配置文件后面配置阿里云镜像仓库就是改这个文件。第三个是Local repository默认会跟着settings.xml的配置走如果改了settings.xml里的本地仓库路径这里也会自动变化。配置好这三个位置之后记得点击右下角的Apply让配置生效。我见过不少人在IDEA里改了配置没点Apply结果一直用的还是旧配置排查了半天才发现问题。2.4 验证环境一条命令确认Maven可用环境配置完成后最好先手动执行一遍Maven命令确认整个链路是通的。打开命令行进入一个空目录执行mvn archetype:generate可以快速生成一个项目骨架或者直接在已有的项目目录下执行mvn clean install测试依赖下载和构建。对于刚开始接触Maven的开发者我建议先在一个简单的项目上执行mvn clean install -DskipTests观察控制台日志。如果依赖下载正常最后出现BUILD SUCCESS的字样说明Maven环境基本没问题。如果这一步就出现了下载失败、超时等报错那就是典型的依赖下载问题接下来就要处理镜像仓库配置了。3. Maven依赖下载失败问题根因与阿里云镜像配置3.1 依赖下载慢/失败到底卡在哪Maven默认从中央仓库下载依赖中央仓库的服务器在国外国内网络环境下下载速度确实不够稳定。遇到慢的时候一个小型项目上百个依赖可能要等很久还经常出现下载到一半连接重置的情况。更麻烦的是Maven下载中断之后会保留.lastUpdated后缀的文件导致下次构建时直接跳过重新下载这就是为什么有时候删掉重来反而能解决。除了网络因素还有几种常见情况settings.xml配置了错误的镜像地址、依赖坐标版本号写错、仓库无法访问返回404等。定位问题的时候建议先看IDEA的Maven工具窗口或者命令行的报错信息它会明确指出是哪个依赖下载失败。比如报Could not transfer artifact io.spring.ai:spring-ai-bom:pom:1.0.0说明是这个坐标的pom文件拉不下来先检查坐标是否正确再看网络和仓库地址。3.2 配置阿里云镜像settings.xml的标准写法解决依赖下载慢最直接的办法是把Maven默认的中央仓库镜像替换成阿里云Maven仓库。阿里云仓库对国内网络非常友好速度和稳定性都很好。具体操作是找到Maven安装目录下的conf/settings.xml文件在mirrors节点中添加一个mirror配置。如果没有mirrors节点就需要手动创建。配置内容如下mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirrormirrorOf配置成*表示所有中央仓库的请求都走这个镜像。添加完成后保存文件回到IDEA点击Maven工具窗口的刷新按钮重新拉取依赖。如果在命令行中使用Maven直接重新执行构建命令即可。我个人的经验是配置好阿里云镜像之后绝大多数依赖下载问题都会迎刃而解。如果还是下载失败再看是不是某个依赖只存在于特定仓库中需要额外添加仓库地址。3.3 多镜像仓库配置mirrorOf匹配规则与profile切换有些项目除了公共依赖还会用到公司内部的私有仓库这时候就需要配置多个镜像或者仓库地址。Maven的mirrorOf支持精确匹配和通配符匹配比如配置成central只会代理中央仓库的请求配置成*,!internal表示代理所有仓库但排除名为internal的仓库。如果项目里需要同时使用多个仓库有两种方式一种是在pom.xml的repositories节点中逐个添加仓库地址这种方式适合只在这个项目里需要的仓库另一种是在settings.xml中使用profile配置不同的仓库组合通过激活不同的profile来实现环境切换这种方式适合多环境部署的场景。放一个多环境profile的简单示例profiles profile iddev/id repositories repository idaliyun-dev/id urlhttps://maven.aliyun.com/repository/public/url /repository /repositories /profile /profiles激活profile的方式很简单在settings.xml中配置activeProfiles节点或者在命令行加-Pdev参数。用这种方式开发和测试环境可以分别用不同的仓库配置不用反复修改settings.xml。不过这里要提醒一点mirror配置和repository配置是两个层级的东西mirror会把所有请求拦截转发到统一地址而repository是逐个声明仓库并尝试下载。如果既配置了mirror又配置了repository优先级和匹配规则容易让人困惑。实际情况中我倾向于用mirror通配符配置一个主仓库再通过profile添加私有仓库这样逻辑最清晰。3.4 依赖缓存清理与强制更新mvn -U的用法Maven为了提高构建效率会把下载过的依赖缓存在本地仓库如果某个依赖是SNAPSHOT版本Maven默认每天只会检查一次更新。如果你在开发过程中发现代码改了但构建结果没变或者引用了最新版本的依赖但下载的还是旧包多半是本地缓存的问题。这时候可以在命令行执行mvn clean install -U-U参数表示强制检查远程仓库的SNAPSHOT版本更新。如果依赖下载中断导致本地出现.lastUpdated文件可以手动删除本地仓库中对应的目录或者执行mvn dependency:purge-local-repository清理本地缓存然后再重新构建。日常开发中我养成了一个习惯每次切换分支、拉取新代码、或者修改依赖版本之后都用mvn clean install -DskipTests -U跑一遍这样能避免很多因为缓存导致的奇怪问题。虽然多花一点时间但能让构建结果更可预期。4. Spring AI到底要引哪些jar包依赖清单与配置示例4.1 官方OpenAI兼容starter快速接入的标准姿势Spring AI官方提供了一套按模型厂商区分的starter其中最常用的是spring-ai-openai-spring-boot-starter。这个starter不仅支持OpenAI的模型还支持OpenAI兼容协议的服务也就是说凡是提供OpenAI兼容接口的模型服务都可以用这个starter来接入。在pom.xml中引入依赖之前先要加上spring-ai-bom的依赖管理。完整的配置片段如下dependencyManagement dependencies dependency groupIdio.spring.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdio.spring.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies引入依赖后还需要在application.yml中配置模型相关的参数。以对接OpenAI兼容接口为例spring: ai: openai: base-url: https://api.example.com/v1 api-key: your-api-key chat: options: model: gpt-3.5-turbo temperature: 0.7这里的关键点是base-url必须指向一个OpenAI兼容的服务地址。如果是官方OpenAI就填https://api.openai.com如果是第三方兼容层就填对应的地址。配置完成后在代码中注入ChatModel或者在Spring AI 1.0之后推荐使用的ChatClient就可以直接调用模型接口了。4.2 Spring AI Alibaba国内开发者的千问接入方案Spring AI Alibaba是阿里云通义千问官方和Spring团队合作推出的适配包它主要的作用是让Spring AI的开发者能更方便地对接通义千问的模型。如果你是国内的开发者用通义千问作为模型底座这个依赖是首选。引入方式和官方starter类似先加BOM再加依赖。Spring AI Alibaba的BOM是dependencyManagement dependencies dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后在dependencies中添加spring-ai-alibaba-starter。配置项大致如下spring: ai: dashscope: api-key: your-dashscope-api-key chat: options: model: qwen-plus这里要说明一点通义千问的API Key需要去阿里云百炼平台申请申请之后在控制台能看到。模型名称按照实际使用的千问模型名称填写比如qwen-plus、qwen-turbo等。Spring AI Alibaba还提供了原生支持的ChatClient接口代码写法和官方OpenAI的写法基本一致这让我切换底层模型时几乎没有额外成本。4.3 本地部署的DeepSeek怎么对接本地部署的模型服务是很多企业的选型方向因为数据不外传、可控性更强。近期我研究比较多的就是Spring AI对接本地部署的DeepSeek。DeepSeek的模型权重是开源的可以用Ollama在本地运行也可以用vLLM等推理框架部署成兼容OpenAI协议的服务。在Spring AI中对接本地DeepSeek最省事的方式还是用spring-ai-openai-spring-boot-starter因为Ollama和vLLM默认都提供OpenAI兼容的HTTP接口。配置只需要修改base-url指向本地地址spring: ai: openai: base-url: http://localhost:11434/v1 api-key: ollama chat: options: model: deepseek-r1:7b这里api-key可以随便填一个非空值就行因为本地服务一般不做鉴权。model名称要匹配你在Ollama里拉取的模型名称比如deepseek-r1:7b。配置好之后Spring AI的ChatModel就会把请求发到本地的11434端口。如果你用的是vLLM部署base-url就是http://localhost:8000/v1这样的地址。这套方式的优势非常明显从云端API切到本地模型只需要改配置文件业务代码一行不动。4.4 其他高频依赖Hutool、Gson等的版本确认Spring AI项目里通常还会用到一些工具类库比如Hutool、Gson、Fastjson等。这些库的版本确认有个简单的原则去Maven中央仓库搜坐标看最新的release版选择稳定版本即可不需要刻意追求最新。Hutool的最新版本可以通过搜索引擎搜“hutool maven 最新版”一般会直接出来Maven仓库页面确认版本号之后在pom.xml里引用。Gson同理搜索“gson maven”就能找到对应的坐标。引用的时候注意看groupId和artifactId是否正确Gson的groupId是com.google.code.gsonartifactId是gson。这里要提醒一句在Spring AI项目里如果同时使用多个JSON库要注意版本冲突。比如Gson版本和Spring Boot内置的Jackson版本不一致可能导致序列化异常。这类问题排查起来比较费劲建议能用一个库就尽量用一个库不要动辄引入重复功能的依赖。5. 常见问题速查表依赖爆红、数据库驱动与命令行操作5.1 IDEA依赖爆红从刷新到清缓存的标准处理流程IDEA里Maven依赖爆红是最常见的问题处理起来有一套标准的排查流程。第一步先看IDEA右侧Maven工具窗口点击刷新按钮让Maven重新加载依赖信息。很多时候爆红只是因为依赖还没下载完或者IDEA的缓存没刷新。第二步如果刷新之后还是爆红检查pom.xml中是否有波浪线提示。把鼠标放到红色代码上IDEA会显示具体错误原因可能是版本号错误、依赖冲突、或者仓库访问失败。第三步检查本地仓库中对应的jar包状态。打开用户目录下的.m2/repository文件夹找到对应的groupId和artifactId目录看看是否有.lastUpdated结尾的文件。如果存在说明依赖下载中断把这个目录整个删除重新在IDEA里刷新。第四步如果以上步骤都不行执行mvn clean install -U强制更新并观察控制台日志看看具体是哪个依赖下载失败。第五步还是不行的话检查settings.xml的镜像配置确认阿里云镜像已经生效。可以临时在IDEA的Maven设置里勾选Always update snapshots再试一次。这个流程我执行过很多次绝大多数爆红问题都能在第三、第四步解决。5.2 缺少数据库Driver以Oracle为例Spring AI项目如果同时要操作数据库会遇到缺少数据库Driver的问题。典型报错是java.lang.ClassNotFoundException: oracle.jdbc.driver.OracleDriver或者提示Failed to load driver class。这类问题的原因很明确就是pom.xml中没有引入对应的JDBC驱动依赖或者驱动的scope配置错了。Oracle驱动的Maven坐标比较特殊groupId是com.oracle.database.jdbcartifactId是ojdbc11版本根据Oracle数据库版本选择。配置如下dependency groupIdcom.oracle.database.jdbc/groupId artifactIdojdbc11/artifactId version23.3.0.23.09/version /dependency引入依赖之后再检查application.yml中的数据源配置driver-class-name要写成oracle.jdbc.OracleDriverurl格式是jdbc:oracle:thin:localhost:1521:orcl。另外如果项目用的是Spring Boot 3.x建议使用对应版本的ojdbc版本否则可能出现兼容性报错。5.3 Maven命令行常用操作clean install/package/skipTests虽然IDEA提供了图形界面的Maven操作按钮但命令行方式依然很重要尤其在服务器上构建项目时是唯一选择。Maven最常用的命令就那几条。mvn clean是清理target目录下的编译产物mvn compile是编译主代码mvn test是运行测试mvn package是打包成jar或者warmvn install是把打包产物安装到本地仓库供其他模块引用。组合起来最常见的是mvn clean install先清理再编译测试打包并安装。跳过测试参数-DskipTests很实用打包的时候加上可以节省大量时间。完整命令是mvn clean install -DskipTests。从这里延伸一个小技巧如果需要把某个本地开发的jar包安装到本地仓库给其他项目用可以在那个项目目录下执行mvn install -DskipTests之后其他项目就能在pom.xml里直接引用了。5.4 依赖版本冲突如何定位并排除传递依赖Maven项目中依赖冲突是隐藏的定时炸弹平时不报错一旦报错就是莫名其妙的ClassNotFoundException或者NoSuchMethodError。这类问题几乎都指向同一个根因项目里某个类被多个版本的jar包同时引入了导致运行时加载到了错误版本。定位冲突的标准方式是执行mvn dependency:tree -Dverbose这条命令会输出完整的依赖树把每个依赖的传递依赖都列出来。看到同一个坐标出现多个版本时就找到了冲突点。解决冲突的办法是在pom.xml中排除旧版本的传递依赖然后在顶层显式声明新版本。举个例子如果spring-ai-openai-spring-boot-starter间接引入了旧版commons-io而项目里另一个库需要新版可以在依赖中用exclusions排除旧版dependency groupIdio.spring.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId exclusions exclusion groupIdcommons-io/groupId artifactIdcommons-io/artifactId /exclusion /exclusions /dependency我的经验是不要过度依赖排除依赖这个操作能升级版本统一就不排除。因为每次排除都意味着你放弃了Maven默认的依赖调解规则会破坏原有的依赖树结构引出更多问题。踩了这么多坑之后我最大的体会是Spring AI开发前期的大部分痛苦都不是AI本身带来的而是基础设施层面的问题。Maven环境准备好了、依赖下载顺畅了、模型连接通了后面的开发反而很顺利。如果你也正在配Spring AI的环境把镜像仓库配好、BOM引入对、先用云端API跑通流程这三件事做好了前期基本就稳了一大半。这个项目里我后面还会继续深挖Spring AI的Agent和Skill机制到时候有什么新坑再回来分享。
Spring AI开发前期准备：Maven镜像配置与依赖引入实战
最近在给一个新项目做技术选型前期准备阶段差点被Maven依赖下载折腾到怀疑人生。项目打算用Spring AI做智能问答模块结果代码还没写一行光是在IDEA里拉取spring-ai相关的jar包就爆红大半天maven中央仓库连接超时、依赖下载到一半卡死、版本对不上各种问题轮着来。后来我把自己踩过的坑重新捋了一遍从Maven环境检查、镜像仓库配置到Spring AI到底该引哪些依赖整理出了一套适合新项目的开发前期准备清单。这篇东西就是把这套经验完整写出来给同样准备上手Spring AI的开发者做个参考尽量让大家少走弯路。1. 开发前期到底要准备什么Spring AI的版本、模型与接入方式1.1 Spring AI是什么从官方定位到实际价值Spring AI是Spring官方推出的AI应用开发框架它做的事情可以理解成“把和大模型对话这件事封装成了Spring风格的API”。以前我们接一个大模型要自己写HTTP客户端、处理请求参数、解析流式返回、管理会话上下文每个模型厂商的协议还不一样换一家就要改一堆代码。Spring AI把这一层统一掉了你用ChatClient、ChatModel这类抽象接口写业务代码底层对接OpenAI也好、通义千问也好、本地部署的DeepSeek也好只需要换依赖和配置。对Java开发者来说这个框架最大的价值是降低了AI功能的接入门槛。你可以像以前用JdbcTemplate操作数据库一样用几行代码完成一次模型调用。而且它天然融入Spring Boot生态配置项走application.yml依赖走Maven中央仓库或者Spring官方仓库对习惯了Spring开发范式的人几乎没有额外学习成本。我个人的判断是现在做Java后端如果要在项目里加AI能力Spring AI应该是优先级最高的候选方案。相比自己封装模型调用它省掉的不是一点点工作量。1.2 版本选型Spring AI 1.0 GA与2.0的取舍开始配置依赖之前先要把版本选清楚。Spring AI在1.0.0 GA版本发布之前有一段时间一直用快照版本SNAPSHOT那时候用起来确实有点痛苦依赖版本号每隔几天就变。现在1.0.0已经正式发布了对应的Spring Boot版本是3.2.x或者3.3.xJDK要求是17以上。最近网上也在传Spring AI 2.0的消息有一些文档和全链路实战案例放出来了。我的建议是如果不是做技术预研或者实验性项目正式项目先用1.0.x稳定版。原因很简单2.0版本对应的Spring Boot版本更高依赖树变化比较大很多第三方库的兼容性还没跟上。前期开发本来就要处理一堆环境问题没必要再给自己增加版本适配的负担。有一点要特别注意Spring AI的依赖管理需要用它的BOMBill of Materials否则版本号很容易冲突。官方文档里推荐的写法是在pom.xml的dependencyManagement中引入spring-ai-bom然后在具体依赖里不写版本号让BOM统一管理。这个习惯最好一开始就养成。1.3 模型接入方式云端API还是本地部署Spring AI支持两种模型接入方式一种是直接调用云平台的API比如通义千问、OpenAI、智谱等这种方式需要在配置里填API Key和模型名称另一种是对接本地部署的模型服务比如用Ollama跑一个DeepSeek或者用vLLM部署的模型服务这种方式走的是OpenAI兼容协议配置一个base-url指向本地端口就行。两种方式在Spring AI里的核心代码没有区别只是配置项和依赖不同。前期开发阶段我建议先用云端API把业务流程跑通因为云平台的模型稳定、接口响应快方便调试。等业务逻辑验证没问题了再切换到本地部署的模型做私有化交付。这样可以有效降低前期调试的复杂度。2. Maven环境搭建装对、配好、跑通三步走2.1 Maven到底是干嘛的依赖管理和构建的底层逻辑很多刚接触Spring AI的开发者其实真正的拦路虎不是AI概念而是Maven本身。Maven是一个Java项目的依赖管理和构建工具它做的事情可以通俗地理解为两个第一你告诉它项目需要哪些第三方库它自动去仓库里下载并管理这些jar包第二它负责把项目编译、测试、打包成一整套流程。Maven的核心配置文件是pom.xml里面声明了项目的依赖坐标每个坐标由groupId、artifactId、version三个要素组成。比如我们要引入Spring AI的核心依赖坐标就是io.spring.ai和spring-ai-openai-spring-boot-starter。Maven下载的jar包会存在一个本地仓库中默认在用户目录下的.m2/repository文件夹里。首次构建项目时本地仓库是空的所有依赖都要从远程仓库拉取这时候如果网络不稳定或者仓库地址不通就会出现依赖下载失败的情况。理解了这套逻辑后面排查问题就有方向了。依赖爆红也好构建失败也好本质上是Maven无法从远程仓库获取到对应的jar包要么是网络问题要么是坐标写错要么是仓库地址配置不对。2.2 安装Maven下载、解压、配置环境变量如果机器上还没有Maven需要先装一个。步骤不复杂但有几个细节值得注意。第一步去Maven官网下载二进制压缩包选择apache-maven-3.8.x或者3.9.x版本都可以不用刻意追求最新版。下载的时候注意选择bin.tar.gzLinux/macOS或者bin.zipWindows不要下成src源码包。第二步解压到本地目录。Windows用户建议解压到D:\dev\apache-maven这种纯英文路径下避免路径中出现中文和空格导致一些奇怪的问题。macOS用户可以用Homebrew安装执行brew install maven也可以手动解压到/usr/local目录下。第三步配置环境变量。Windows用户在系统变量的Path中新增Maven解压目录下的bin文件夹路径同时新建变量名M2_HOME指向Maven根目录。macOS和Linux用户需要编辑~/.bash_profile或者~/.zshrc添加export M2_HOME/path/to/maven和export PATH$PATH:$M2_HOME/bin。第四步验证安装。打开命令行执行mvn -v如果能看到Maven版本号和JDK版本信息说明环境变量配置成功。这里要提醒一下Maven依赖的JAVA_HOME环境变量也要正确配置否则即使Maven本身装好了执行时也会报找不到JDK的错误。2.3 IDEA集成三个关键的配置位置安装了Maven之后还需要在IDEA里配置好否则IDEA用的是自带Maven不一定符合我们的需求。打开IDEA的Settings在Build, Execution, Deployment下的Build Tools里找到Maven这里有几个关键配置项。第一个是Maven home path要指向我们自己安装的Maven解压目录而不是IDEA内置的Maven。第二个是User settings file这里要指向Maven的settings.xml配置文件后面配置阿里云镜像仓库就是改这个文件。第三个是Local repository默认会跟着settings.xml的配置走如果改了settings.xml里的本地仓库路径这里也会自动变化。配置好这三个位置之后记得点击右下角的Apply让配置生效。我见过不少人在IDEA里改了配置没点Apply结果一直用的还是旧配置排查了半天才发现问题。2.4 验证环境一条命令确认Maven可用环境配置完成后最好先手动执行一遍Maven命令确认整个链路是通的。打开命令行进入一个空目录执行mvn archetype:generate可以快速生成一个项目骨架或者直接在已有的项目目录下执行mvn clean install测试依赖下载和构建。对于刚开始接触Maven的开发者我建议先在一个简单的项目上执行mvn clean install -DskipTests观察控制台日志。如果依赖下载正常最后出现BUILD SUCCESS的字样说明Maven环境基本没问题。如果这一步就出现了下载失败、超时等报错那就是典型的依赖下载问题接下来就要处理镜像仓库配置了。3. Maven依赖下载失败问题根因与阿里云镜像配置3.1 依赖下载慢/失败到底卡在哪Maven默认从中央仓库下载依赖中央仓库的服务器在国外国内网络环境下下载速度确实不够稳定。遇到慢的时候一个小型项目上百个依赖可能要等很久还经常出现下载到一半连接重置的情况。更麻烦的是Maven下载中断之后会保留.lastUpdated后缀的文件导致下次构建时直接跳过重新下载这就是为什么有时候删掉重来反而能解决。除了网络因素还有几种常见情况settings.xml配置了错误的镜像地址、依赖坐标版本号写错、仓库无法访问返回404等。定位问题的时候建议先看IDEA的Maven工具窗口或者命令行的报错信息它会明确指出是哪个依赖下载失败。比如报Could not transfer artifact io.spring.ai:spring-ai-bom:pom:1.0.0说明是这个坐标的pom文件拉不下来先检查坐标是否正确再看网络和仓库地址。3.2 配置阿里云镜像settings.xml的标准写法解决依赖下载慢最直接的办法是把Maven默认的中央仓库镜像替换成阿里云Maven仓库。阿里云仓库对国内网络非常友好速度和稳定性都很好。具体操作是找到Maven安装目录下的conf/settings.xml文件在mirrors节点中添加一个mirror配置。如果没有mirrors节点就需要手动创建。配置内容如下mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirrormirrorOf配置成*表示所有中央仓库的请求都走这个镜像。添加完成后保存文件回到IDEA点击Maven工具窗口的刷新按钮重新拉取依赖。如果在命令行中使用Maven直接重新执行构建命令即可。我个人的经验是配置好阿里云镜像之后绝大多数依赖下载问题都会迎刃而解。如果还是下载失败再看是不是某个依赖只存在于特定仓库中需要额外添加仓库地址。3.3 多镜像仓库配置mirrorOf匹配规则与profile切换有些项目除了公共依赖还会用到公司内部的私有仓库这时候就需要配置多个镜像或者仓库地址。Maven的mirrorOf支持精确匹配和通配符匹配比如配置成central只会代理中央仓库的请求配置成*,!internal表示代理所有仓库但排除名为internal的仓库。如果项目里需要同时使用多个仓库有两种方式一种是在pom.xml的repositories节点中逐个添加仓库地址这种方式适合只在这个项目里需要的仓库另一种是在settings.xml中使用profile配置不同的仓库组合通过激活不同的profile来实现环境切换这种方式适合多环境部署的场景。放一个多环境profile的简单示例profiles profile iddev/id repositories repository idaliyun-dev/id urlhttps://maven.aliyun.com/repository/public/url /repository /repositories /profile /profiles激活profile的方式很简单在settings.xml中配置activeProfiles节点或者在命令行加-Pdev参数。用这种方式开发和测试环境可以分别用不同的仓库配置不用反复修改settings.xml。不过这里要提醒一点mirror配置和repository配置是两个层级的东西mirror会把所有请求拦截转发到统一地址而repository是逐个声明仓库并尝试下载。如果既配置了mirror又配置了repository优先级和匹配规则容易让人困惑。实际情况中我倾向于用mirror通配符配置一个主仓库再通过profile添加私有仓库这样逻辑最清晰。3.4 依赖缓存清理与强制更新mvn -U的用法Maven为了提高构建效率会把下载过的依赖缓存在本地仓库如果某个依赖是SNAPSHOT版本Maven默认每天只会检查一次更新。如果你在开发过程中发现代码改了但构建结果没变或者引用了最新版本的依赖但下载的还是旧包多半是本地缓存的问题。这时候可以在命令行执行mvn clean install -U-U参数表示强制检查远程仓库的SNAPSHOT版本更新。如果依赖下载中断导致本地出现.lastUpdated文件可以手动删除本地仓库中对应的目录或者执行mvn dependency:purge-local-repository清理本地缓存然后再重新构建。日常开发中我养成了一个习惯每次切换分支、拉取新代码、或者修改依赖版本之后都用mvn clean install -DskipTests -U跑一遍这样能避免很多因为缓存导致的奇怪问题。虽然多花一点时间但能让构建结果更可预期。4. Spring AI到底要引哪些jar包依赖清单与配置示例4.1 官方OpenAI兼容starter快速接入的标准姿势Spring AI官方提供了一套按模型厂商区分的starter其中最常用的是spring-ai-openai-spring-boot-starter。这个starter不仅支持OpenAI的模型还支持OpenAI兼容协议的服务也就是说凡是提供OpenAI兼容接口的模型服务都可以用这个starter来接入。在pom.xml中引入依赖之前先要加上spring-ai-bom的依赖管理。完整的配置片段如下dependencyManagement dependencies dependency groupIdio.spring.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdio.spring.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies引入依赖后还需要在application.yml中配置模型相关的参数。以对接OpenAI兼容接口为例spring: ai: openai: base-url: https://api.example.com/v1 api-key: your-api-key chat: options: model: gpt-3.5-turbo temperature: 0.7这里的关键点是base-url必须指向一个OpenAI兼容的服务地址。如果是官方OpenAI就填https://api.openai.com如果是第三方兼容层就填对应的地址。配置完成后在代码中注入ChatModel或者在Spring AI 1.0之后推荐使用的ChatClient就可以直接调用模型接口了。4.2 Spring AI Alibaba国内开发者的千问接入方案Spring AI Alibaba是阿里云通义千问官方和Spring团队合作推出的适配包它主要的作用是让Spring AI的开发者能更方便地对接通义千问的模型。如果你是国内的开发者用通义千问作为模型底座这个依赖是首选。引入方式和官方starter类似先加BOM再加依赖。Spring AI Alibaba的BOM是dependencyManagement dependencies dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后在dependencies中添加spring-ai-alibaba-starter。配置项大致如下spring: ai: dashscope: api-key: your-dashscope-api-key chat: options: model: qwen-plus这里要说明一点通义千问的API Key需要去阿里云百炼平台申请申请之后在控制台能看到。模型名称按照实际使用的千问模型名称填写比如qwen-plus、qwen-turbo等。Spring AI Alibaba还提供了原生支持的ChatClient接口代码写法和官方OpenAI的写法基本一致这让我切换底层模型时几乎没有额外成本。4.3 本地部署的DeepSeek怎么对接本地部署的模型服务是很多企业的选型方向因为数据不外传、可控性更强。近期我研究比较多的就是Spring AI对接本地部署的DeepSeek。DeepSeek的模型权重是开源的可以用Ollama在本地运行也可以用vLLM等推理框架部署成兼容OpenAI协议的服务。在Spring AI中对接本地DeepSeek最省事的方式还是用spring-ai-openai-spring-boot-starter因为Ollama和vLLM默认都提供OpenAI兼容的HTTP接口。配置只需要修改base-url指向本地地址spring: ai: openai: base-url: http://localhost:11434/v1 api-key: ollama chat: options: model: deepseek-r1:7b这里api-key可以随便填一个非空值就行因为本地服务一般不做鉴权。model名称要匹配你在Ollama里拉取的模型名称比如deepseek-r1:7b。配置好之后Spring AI的ChatModel就会把请求发到本地的11434端口。如果你用的是vLLM部署base-url就是http://localhost:8000/v1这样的地址。这套方式的优势非常明显从云端API切到本地模型只需要改配置文件业务代码一行不动。4.4 其他高频依赖Hutool、Gson等的版本确认Spring AI项目里通常还会用到一些工具类库比如Hutool、Gson、Fastjson等。这些库的版本确认有个简单的原则去Maven中央仓库搜坐标看最新的release版选择稳定版本即可不需要刻意追求最新。Hutool的最新版本可以通过搜索引擎搜“hutool maven 最新版”一般会直接出来Maven仓库页面确认版本号之后在pom.xml里引用。Gson同理搜索“gson maven”就能找到对应的坐标。引用的时候注意看groupId和artifactId是否正确Gson的groupId是com.google.code.gsonartifactId是gson。这里要提醒一句在Spring AI项目里如果同时使用多个JSON库要注意版本冲突。比如Gson版本和Spring Boot内置的Jackson版本不一致可能导致序列化异常。这类问题排查起来比较费劲建议能用一个库就尽量用一个库不要动辄引入重复功能的依赖。5. 常见问题速查表依赖爆红、数据库驱动与命令行操作5.1 IDEA依赖爆红从刷新到清缓存的标准处理流程IDEA里Maven依赖爆红是最常见的问题处理起来有一套标准的排查流程。第一步先看IDEA右侧Maven工具窗口点击刷新按钮让Maven重新加载依赖信息。很多时候爆红只是因为依赖还没下载完或者IDEA的缓存没刷新。第二步如果刷新之后还是爆红检查pom.xml中是否有波浪线提示。把鼠标放到红色代码上IDEA会显示具体错误原因可能是版本号错误、依赖冲突、或者仓库访问失败。第三步检查本地仓库中对应的jar包状态。打开用户目录下的.m2/repository文件夹找到对应的groupId和artifactId目录看看是否有.lastUpdated结尾的文件。如果存在说明依赖下载中断把这个目录整个删除重新在IDEA里刷新。第四步如果以上步骤都不行执行mvn clean install -U强制更新并观察控制台日志看看具体是哪个依赖下载失败。第五步还是不行的话检查settings.xml的镜像配置确认阿里云镜像已经生效。可以临时在IDEA的Maven设置里勾选Always update snapshots再试一次。这个流程我执行过很多次绝大多数爆红问题都能在第三、第四步解决。5.2 缺少数据库Driver以Oracle为例Spring AI项目如果同时要操作数据库会遇到缺少数据库Driver的问题。典型报错是java.lang.ClassNotFoundException: oracle.jdbc.driver.OracleDriver或者提示Failed to load driver class。这类问题的原因很明确就是pom.xml中没有引入对应的JDBC驱动依赖或者驱动的scope配置错了。Oracle驱动的Maven坐标比较特殊groupId是com.oracle.database.jdbcartifactId是ojdbc11版本根据Oracle数据库版本选择。配置如下dependency groupIdcom.oracle.database.jdbc/groupId artifactIdojdbc11/artifactId version23.3.0.23.09/version /dependency引入依赖之后再检查application.yml中的数据源配置driver-class-name要写成oracle.jdbc.OracleDriverurl格式是jdbc:oracle:thin:localhost:1521:orcl。另外如果项目用的是Spring Boot 3.x建议使用对应版本的ojdbc版本否则可能出现兼容性报错。5.3 Maven命令行常用操作clean install/package/skipTests虽然IDEA提供了图形界面的Maven操作按钮但命令行方式依然很重要尤其在服务器上构建项目时是唯一选择。Maven最常用的命令就那几条。mvn clean是清理target目录下的编译产物mvn compile是编译主代码mvn test是运行测试mvn package是打包成jar或者warmvn install是把打包产物安装到本地仓库供其他模块引用。组合起来最常见的是mvn clean install先清理再编译测试打包并安装。跳过测试参数-DskipTests很实用打包的时候加上可以节省大量时间。完整命令是mvn clean install -DskipTests。从这里延伸一个小技巧如果需要把某个本地开发的jar包安装到本地仓库给其他项目用可以在那个项目目录下执行mvn install -DskipTests之后其他项目就能在pom.xml里直接引用了。5.4 依赖版本冲突如何定位并排除传递依赖Maven项目中依赖冲突是隐藏的定时炸弹平时不报错一旦报错就是莫名其妙的ClassNotFoundException或者NoSuchMethodError。这类问题几乎都指向同一个根因项目里某个类被多个版本的jar包同时引入了导致运行时加载到了错误版本。定位冲突的标准方式是执行mvn dependency:tree -Dverbose这条命令会输出完整的依赖树把每个依赖的传递依赖都列出来。看到同一个坐标出现多个版本时就找到了冲突点。解决冲突的办法是在pom.xml中排除旧版本的传递依赖然后在顶层显式声明新版本。举个例子如果spring-ai-openai-spring-boot-starter间接引入了旧版commons-io而项目里另一个库需要新版可以在依赖中用exclusions排除旧版dependency groupIdio.spring.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId exclusions exclusion groupIdcommons-io/groupId artifactIdcommons-io/artifactId /exclusion /exclusions /dependency我的经验是不要过度依赖排除依赖这个操作能升级版本统一就不排除。因为每次排除都意味着你放弃了Maven默认的依赖调解规则会破坏原有的依赖树结构引出更多问题。踩了这么多坑之后我最大的体会是Spring AI开发前期的大部分痛苦都不是AI本身带来的而是基础设施层面的问题。Maven环境准备好了、依赖下载顺畅了、模型连接通了后面的开发反而很顺利。如果你也正在配Spring AI的环境把镜像仓库配好、BOM引入对、先用云端API跑通流程这三件事做好了前期基本就稳了一大半。这个项目里我后面还会继续深挖Spring AI的Agent和Skill机制到时候有什么新坑再回来分享。
