Spring AI 学习篇（二）| 开发环境搭建（保姆级）

Slow菜鸟2026-06-23 10:40

Spring AI 学习篇（二）| 开发环境搭建（保姆级）

  • 一、本章核心学习目标
  • 二、前置知识准备
  • 三、严格的环境版本要求（必须遵守）
  • 四、一步步搭建开发环境
    • [1. 安装JDK 17](#1. 安装JDK 17)
      • [(1) 下载JDK 17](#(1) 下载JDK 17)
      • [(2) 安装JDK 17](#(2) 安装JDK 17)
      • [(3) 验证安装](#(3) 验证安装)
    • [2. 安装并配置Maven 3.9.9](#2. 安装并配置Maven 3.9.9)
      • [(1) 下载Maven](#(1) 下载Maven)
      • [(2) 解压并配置环境变量](#(2) 解压并配置环境变量)
      • [(3) 配置阿里云镜像（必须配置）](#(3) 配置阿里云镜像（必须配置）)
      • [(4) 配置本地仓库](#(4) 配置本地仓库)
      • [(5) 验证安装](#(5) 验证安装)
    • [3. 配置IDEA](#3. 配置IDEA)
      • [(1) 设置项目SDK（全局默认JDK）](#(1) 设置项目SDK（全局默认JDK）)
      • [(2) 配置Maven Runner 的 JDK](#(2) 配置Maven Runner 的 JDK)
      • [(3) 配置Maven](#(3) 配置Maven)
  • [五、创建第一个Spring AI项目](#五、创建第一个Spring AI项目)
    • [1. 使用Spring Initializr创建项目](#1. 使用Spring Initializr创建项目)
    • [2. 配置pom.xml依赖（核心）](#2. 配置pom.xml依赖（核心）)
    • [3. 配置application.yml](#3. 配置application.yml)
    • [如何获取DeepSeek API Key：](#如何获取DeepSeek API Key：)
  • [六、编写第一个Spring AI应用：Hello World聊天机器人](#六、编写第一个Spring AI应用：Hello World聊天机器人)
    • [1. 创建ChatController](#1. 创建ChatController)
    • [2. 启动项目](#2. 启动项目)
    • [3. 测试聊天接口](#3. 测试聊天接口)
  • 七、企业级最佳实践
  • 八、常见坑与解决方案
    • [1. ❌ Spring Boot版本错误](#1. ❌ Spring Boot版本错误)
    • [2. ❌ JDK版本错误](#2. ❌ JDK版本错误)
    • [3. ❌ Maven依赖下载失败](#3. ❌ Maven依赖下载失败)
    • [4. ❌ API Key错误或无效](#4. ❌ API Key错误或无效)
    • [5. ❌ 网络问题无法访问DeepSeek API](#5. ❌ 网络问题无法访问DeepSeek API)
    • [6. ❌ IDEA缓存问题](#6. ❌ IDEA缓存问题)
  • 九、本章总结与下章预告
  • 十、课后练习

一、本章核心学习目标

学完本章，你将能够：

  1. 独立搭建符合Spring AI 1.0要求的完整开发环境
  2. 创建并运行你的第一个Spring AI项目
  3. 对接DeepSeek大模型，实现一个简单的聊天机器人
  4. 解决常见的Spring AI环境配置问题
  5. 掌握Maven依赖管理和Spring Boot项目的基本结构

二、前置知识准备

  • 已经完成第1篇的学习，了解Spring AI的基本定位
  • 具备Java基础语法和面向对象编程知识
  • 了解Maven的基本使用方法

三、严格的环境版本要求（必须遵守）

Spring AI 1.0稳定版对环境版本有严格要求，请务必使用以下版本：

软件 最低要求 推荐版本 说明
JDK 17 17.0.11 LTS Spring Boot 3.x的最低要求，不支持JDK 8/11
Spring Boot 3.4.0 3.4.3 Spring AI 1.0仅支持Spring Boot 3.4.x及以上
Maven 3.6.3 3.9.9 低于3.6.3会出现依赖解析错误
IDEA 2024.1 2026.1 旧版本IDEA对Spring Boot 3.4和JDK 17支持不完善

四、一步步搭建开发环境

1. 安装JDK 17

(1) 下载JDK 17

(2) 安装JDK 17

  • 双击安装包，点击"Next"
  • 重要 ：安装路径不要包含中文和空格，推荐D:\EclipseAdoptium\jdk-17
  • 勾选"Add to PATH"和"Set JAVA_HOME variable"
  • 点击"Install"完成安装

(3) 验证安装

打开命令提示符（CMD），输入以下命令：

cmd 复制代码 
java -version
javac -version

如果输出类似以下内容，说明安装成功：

复制代码 
openjdk version "17.0.11" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-17.0.11+9 (build 17.0.11+9-LTS)
OpenJDK 64-Bit Server VM Temurin-17.0.11+9 (build 17.0.11+9-LTS, mixed mode, sharing)

2. 安装并配置Maven 3.9.9

(1) 下载Maven

(2) 解压并配置环境变量

  • 解压到D:\apache-maven-3.9.9
  • 右键"此电脑"→"属性"→"高级系统设置"→"环境变量"
  • 新建系统变量：MAVEN_HOME，值为D:\apache-maven-3.9.9
  • 编辑系统变量Path，添加%MAVEN_HOME%\bin

(3) 配置阿里云镜像（必须配置）

打开D:\apache-maven-3.9.9\conf\settings.xml，找到<mirrors>标签，添加以下内容：

xml 复制代码 
<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

(4) 配置本地仓库

在settings.xml中找到<localRepository>标签，修改为：

xml 复制代码 
<localRepository>D:\maven-repository</localRepository>

这样所有Maven依赖都会下载到D盘，不会占用C盘空间。

(5) 验证安装

打开CMD，输入：

cmd 复制代码 
mvn -v

如果输出类似以下内容，说明安装成功：

复制代码 
Apache Maven 3.9.9 (db4a4f498d78d670909629997732f5060302938a)
Maven home: D:\apache-maven-3.9.9
Java version: 17.0.11, vendor: Eclipse Adoptium, runtime: D:\EclipseAdoptium\jdk-17
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

3. 配置IDEA

(1) 设置项目SDK（全局默认JDK）

  • 打开IDEA，进入"File"→"Project Structure"（快捷键Ctrl+Alt+Shift+S）
  • 在"Project"选项卡中，将"SDK"设置为刚才安装的JDK 17
  • 如果没有，点击"Add SDK"→"JDK"，选择安装目录D:\EclipseAdoptium\jdk-17

(2) 配置Maven Runner 的 JDK

  • 进入"Settings"（快捷键Ctrl+Alt+S）
  • 找到"Build, Execution, Deployment"→"Build Tools"→"Maven"→"Runner"
  • 在"JRE"下拉菜单中选择JDK 17

(3) 配置Maven

  • 找到"Build, Execution, Deployment"→"Build Tools"→"Maven"
  • 在"Maven home path"中选择我们刚才安装的Maven目录D:\apache-maven-3.9.9
  • 在"User settings file"中选择D:\apache-maven-3.9.9\conf\settings.xml
  • 在"Local repository"中选择D:\maven-repository
  • 勾选"Override"所有选项
  • 点击"Apply"保存配置

五、创建第一个Spring AI项目

1. 使用Spring Initializr创建项目

  • 打开IDEA，点击"New Project"
  • 选择"Spring Initializr"
  • 填写项目信息：
    • Group：com.example
    • Artifact：spring-ai-demo
    • Name：spring-ai-demo
    • Description：Spring AI 1.0 Demo Project
    • Package name：com.example.springaidemo
    • Java：17
    • Packaging：Jar
  • 点击"Next"
  • 选择Spring Boot版本：3.4.3（必须是3.4.x版本）
  • 暂时不勾选任何依赖，我们后面手动添加
  • 点击"Create"创建项目

2. 配置pom.xml依赖（核心）

打开pom.xml文件，替换为以下内容：

xml 复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>spring-ai-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-ai-demo</name>
    <description>Spring AI 1.0 Demo Project</description>
    
    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.0.0</spring-ai.version>
    </properties>
    
    <!-- BOM 统一管理版本，必须放在 dependencyManagement 中 -->
    <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 Boot Web Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Spring AI DeepSeek Starter（版本由BOM管理，无需指定version） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-deepseek</artifactId>
        </dependency>
        
        <!-- Spring Boot Test Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

重要说明：

  • 我们使用了Spring AI BOM来管理所有Spring AI模块的版本，确保版本一致
  • 我们选择了DeepSeek作为第一个对接的大模型，因为它免费额度高，中文能力强，Spring AI官方原生支持
  • 后面我们会学到如何切换到其他模型，甚至本地部署的模型，代码几乎不需要修改

3. 配置application.yml

将src/main/resources/application.properties重命名为application.yml，然后添加以下内容：

yaml 复制代码 
spring:
  application:
    name: spring-ai-demo
  # DeepSeek大模型配置
  ai:
    deepseek:
      api-key: 你的DeepSeek API Key
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
          max-tokens: 2048

# 服务器配置
server:
  port: 8080

如何获取DeepSeek API Key：

  1. 访问DeepSeek开放平台：https://platform.deepseek.com/
  2. 注册并登录账号
  3. 新用户会赠送500万tokens免费额度，足够学习使用
  4. 点击"API Keys"→"Create API Key"
  5. 复制生成的API Key，替换上面的"你的DeepSeek API Key"

安全提示：永远不要把API Key提交到Git仓库。

操作步骤：

  1. 在项目根目录创建.gitignore文件，添加一行：application.yml
  2. 同时创建一个application-example.yml（不含真实Key）作为模板提交到Git

生产环境应使用环境变量（${DEEPSEEK_API_KEY}）或配置中心管理敏感信息，这会在第17篇详细讲解。

六、编写第一个Spring AI应用：Hello World聊天机器人

1. 创建ChatController

在com.example.springaidemo包下创建一个新的Java类ChatController：

java 复制代码 
package com.example.springaidemo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatClient chatClient;

    // 构造函数注入ChatClient，Spring AI会自动为我们创建实例
    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    // 简单的聊天接口
    @GetMapping("/chat")
    public String chat(@RequestParam(defaultValue = "你好，介绍一下你自己") String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

2. 启动项目

  • 找到SpringAiDemoApplication类

  • 点击类名旁边的绿色三角形按钮启动项目

  • 等待项目启动完成，看到类似以下日志说明启动成功：

    Started SpringAiDemoApplication in 2.345 seconds (process running for 3.123)

3. 测试聊天接口

打开浏览器，访问以下地址：

复制代码 
http://localhost:8080/chat?message=用Java写一个Hello World程序

你应该会看到大模型返回的Java Hello World程序代码。

恭喜你！你已经成功运行了你的第一个Spring AI应用。

七、企业级最佳实践

1. 使用BOM管理依赖版本。 BOM（Bill of Materials）统一管理所有Spring AI模块的版本，确保不会出现版本冲突。注意：BOM必须放在<dependencyManagement>中，不是<dependencies>。这样后续添加其他Spring AI模块时不需要写版本号。

2. 配置文件按环境分离。 创建三个配置文件：application-dev.yml（开发）、application-test.yml（测试）、application-prod.yml（生产）。在application.yml中用spring.profiles.active: dev指定。不同环境的API Key、模型参数、日志级别都可能不同。

3. 敏感信息不要写死在代码里。 API Key绝对不能提交到Git仓库。推荐做法：

  • 开发环境：用环境变量${DEEPSEEK_API_KEY}引用
  • 生产环境：用配置中心（Nacos、Apollo）或K8s Secret管理

4. 统一项目命名和包结构。 本章为了简单，ChatController 直接放在根包下。当项目逐渐变大时，建议按以下结构分包：

复制代码 
com.example.springaidemo
├── controller    # 接口层
├── service       # 业务层
├── config        # 配置类
└── model         # 数据模型

后续章节我们会随着代码增多逐步引入这种分包方式。

5. 尽早配置好日志。 在application.yml中添加日志配置，至少把Spring AI相关的包设为DEBUG级别，方便排查问题：

yaml 复制代码 
logging:
  level:
    org.springframework.ai: DEBUG
    com.example: DEBUG

八、常见坑与解决方案

1. ❌ Spring Boot版本错误

错误信息 ：NoClassDefFoundError或ClassNotFoundException

解决方案：确保Spring Boot版本是3.4.x，不能使用3.3及以下版本

2. ❌ JDK版本错误

错误信息 ：UnsupportedClassVersionError（class file version 61）

解决方案：确保JDK版本是17+，并且IDEA配置的JDK也是17+

3. ❌ Maven依赖下载失败

错误信息 ：Could not resolve dependencies

解决方案 ：检查阿里云镜像配置是否正确，然后执行mvn clean install -U强制更新依赖

4. ❌ API Key错误或无效

错误信息 ：401 Unauthorized

解决方案：检查API Key是否正确，是否有拼写错误，是否已经过期

5. ❌ 网络问题无法访问DeepSeek API

错误信息 ：ConnectException或SocketTimeoutException

解决方案：检查网络连接，尝试使用代理，或者切换到其他国内模型如智谱AI

6. ❌ IDEA缓存问题

现象 ：代码没有错误，但IDEA显示红色报错

解决方案：点击"File"→"Invalidate Caches / Restart"→"Invalidate and Restart"

九、本章总结与下章预告

本章总结

  1. 我们搭建了符合Spring AI 1.0要求的完整开发环境，包括JDK 17、Maven 3.9.9和IDEA
  2. 我们创建了第一个Spring AI项目，配置了Spring AI BOM和DeepSeek依赖
  3. 我们编写了一个简单的聊天接口，成功调用了DeepSeek大模型
  4. 我们了解了常见的环境配置问题和解决方案

预告式提及：我们现在使用的是DeepSeek的云端API，后面我们会学到如何使用Ollama本地部署模型，不需要API Key也能运行AI应用，数据100%不出本地。

下章预告

下一章我们将深入学习Spring AI大模型API对接的统一范式。你将学会：

  • ChatClient核心API的详细用法
  • 如何配置模型参数（temperature、top_p等）
  • 如何实现流式输出，让回复像打字一样逐个显示
  • 如何一行代码切换不同的大模型
  • 如何处理模型调用的异常和重试

十、课后练习

  1. 尝试修改application.yml中的temperature参数（0.0-1.0），看看不同的值对输出结果有什么影响
  2. 尝试实现一个流式输出的聊天接口（提示：使用stream()方法代替call()方法）
  3. 尝试将DeepSeek换成智谱AI，看看需要修改哪些配置和代码（提示：添加spring-ai-zhipuai-spring-boot-starter依赖）
热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点06Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析07AI科技热点日报 | 2026年6月1日08AI一周事件 · 2026-06-03 至 2026-06-0909Codex 下载安装指南：Windows 和 macOS 官方版下载10上线仅72小时被强制下架：Claude Fable 5 的短命