手把手搭建 Spring AI 开发环境：依赖引入、版本选择、项目初始化-三亩地-编程学习日记

专栏导读：本专栏为Spring AI 科普实战系列，从框架认知、环境搭建、基础对话、流式输出、会话记忆、函数调用到 RAG 知识库，全方位讲解 Spring 生态 AI 集成方案，零基础 Java 开发者也可轻松上手。
上一篇我们从原理和痛点层面搞懂了：为什么要用 Spring AI。理论落地必须依赖实战，想要玩转 Spring AI 所有智能能力，第一步就是搭建一套稳定、规范、无坑的基础开发环境。
很多新手初学 Spring AI 最容易踩坑的地方：版本不匹配、依赖缺失、自动配置失效。
本篇文章专门解决环境问题，手把手带你完成：版本选型、项目创建、依赖引入、配置编写、项目启动、接口测试。读完本篇，你将拥有一个可以贯穿整个系列的通用 Spring AI 基础工程。

一、前置环境与版本适配（重点必看）

Spring AI 对版本要求比较严格，版本不对直接启动报错，这里直接给出生产通用稳定组合，无脑抄即可。

1. 基础环境要求

JDK：17 及以上（Spring Boot3 强制要求）
构建工具：Maven 3.8+ / Gradle 7.5+
开发工具：IDEA / Eclipse / VS Code 均可

2. 稳定版本组合（推荐）
本文及后续所有实战统一使用这套稳定版本，兼容性最好、BUG 最少：

Spring Boot：3.3.x
Spring AI：1.1.x 稳定版
避坑提示：不要强行使用最新的 Spring Boot 4.0、Spring AI 2.0 预览版，新特性多、兼容问题多，学习和落地优先稳定版。

二、两种项目创建方式

这里提供两种最常用的创建方式，任选其一即可，最终效果完全一致。

方式一：Spring Initializr 在线初始化（推荐）
官方在线脚手架，一键生成干净工程，无需手动配置版本。
访问官网：start.spring.io
参数配置：

Project：Maven
Language：Java
Spring Boot Version：3.3.x（稳定版）
Java Version：17
包名、项目名自定义
初始化完成后下载压缩包，导入 IDEA 等待依赖加载完毕。

方式二：IDEA 本地直接创建
打开 IDEA -> New Project -> 选择 Spring Initializr，参数同上，直接本地生成工程即可。

三、引入 Spring AI 核心依赖（Maven）

Spring AI 采用版本统一管理机制，需要先在 pom.xml 中声明 Spring AI 版本，再按需引入对应 Starter。
完整可直接运行的 pom 核心配置如下：

<properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><spring-ai.version>1.1.4</spring-ai.version></properties><!-- 统一版本管理 --><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><!-- Spring Web 必备，用于写接口测试 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Spring AI 核心基础包 --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-core</artifactId></dependency><!-- 测试依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies>

依赖说明

spring-ai-bom：统一管理所有 Spring AI 子依赖版本，避免版本冲突
spring-ai-starter-core：Spring AI 核心基础能力，包含 Prompt、ChatClient、Advisor 等顶层抽象
spring-boot-starter-web：用于开发 Web 接口，方便后续接口测试

四、全局配置文件说明

Spring AI 所有模型密钥、超时时间、模型参数，全部统一在 application.yml / application.properties 中配置。
本次环境搭建无需配置任何 AI 密钥，仅保证项目结构正常即可，后续对接模型会逐一补充配置。
初始默认空配置即可，干净无干扰。

五、项目结构预览（标准规范）

这里先统一整套系列的项目结构，后续所有实战代码全部遵循该规范：

com.ai.demo ├── config // AI 配置类 ├── controller // 接口层 ├──service// 业务层 ├── entity // 实体类 └── AiDemoApplication.java // 启动类

六、环境校验：编写第一个 AI 测试接口

为了验证我们的环境是否搭建成功，我们注入 Spring AI 核心的 ChatClient，编写一个最简单的测试接口。

1. 编写测试 Controller

package com.ai.demo.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;@RestController public class AiTestController{// 注入 Spring AI 核心客户端 private final ChatClient chatClient;public AiTestController(ChatClient.Builder chatClientBuilder){this.chatClient=chatClientBuilder.build();}@GetMapping("/ai/test")public Stringtest(){return"Spring AI 环境搭建成功！等待接入大模型能力...";}}

2. 启动项目验证
运行启动类，观察控制台：无报错、项目正常启动即为环境搭建成功。
浏览器访问：http://localhost:8080/ai/test
页面输出：Spring AI 环境搭建成功！等待接入大模型能力…

七、新手常见环境报错与解决

1. JDK 版本不匹配
报错关键词：class file has wrong version
解决方案：项目、模块、编译器全部统一设置为 JDK17。

2. 依赖无法导入、报红
解决方案：刷新 Maven、检查网络、确认 spring-ai-bom 版本书写正确。

3. 启动提示自动配置失效
解决方案：必须使用 Spring Boot3.x，不能使用 Spring Boot2.x，Spring AI 不兼容低版本。

八、本篇总结

本篇我们完成了 Spring AI 全套基础环境搭建，确定了统一版本规范、统一项目结构、导入了核心依赖，并通过接口验证了工程可用性。
目前我们的项目已经具备 Spring AI 完整运行基础，后续所有的：对话问答、流式输出、RAG、函数调用、记忆会话，全部基于当前工程迭代开发。
下一篇：Spring AI 实战：快速接入通义千问、OpenAI，实现基础对话问答
我们将正式接入大模型，实现第一个真正的 AI 智能问答功能！

日记详情

手把手搭建 Spring AI 开发环境：依赖引入、版本选择、项目初始化