专栏导读：本专栏为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 智能问答功能！
