手把手教你 Spring Boot 3.x 集成 Spring AI，打造你的第一个 AI 聊天应用

Spring AI 1.0.0 正式发布！本文带你从零开始搭建一个支持同步和流式对话的 AI 应用，兼容 OpenAI、DeepSeek 等多种模型。

---

前言

自从 ChatGPT 爆火以来，AI 应用开发成为了热门方向。但对于 Java 开发者来说，对接各种 AI 模型 API 往往需要处理复杂的 HTTP 请求、响应解析、流式传输等细节。

Spring AI 的出现改变了这一切 —— 它提供了统一的 API 抽象，让开发者可以像使用 Spring Data JPA 一样简单地进行 AI 应用开发。

本文将基于 Spring Boot 3.5.0 + Spring AI 1.0.0，手把手教你搭建一个完整的 AI 聊天应用，支持同步和流式两种对话模式，并兼容 DeepSeek、豆包等国产大模型。

---

本文亮点

• Spring Boot 3.5.0 + Spring AI 1.0.0 最新版本 —— 踩坑经验分享
• 同步 + 流式双模式 —— 满足不同业务场景需求
• DeepSeek 集成实践 —— OpenAI 兼容接口一键切换
• 完整项目代码 —— 可直接运行，拿来即用

---

一、技术栈准备

1.1 技术选型

技术	版本	说明
Java	17	LTS 版本，Spring Boot 3.x 最低要求
Spring Boot	3.5.0	最新稳定版本
Spring AI	1.0.0	Spring AI BOM 版本
DeepSeek	-	OpenAI 兼容接口的国产大模型

为什么选择 DeepSeek？
完全兼容 OpenAI API，价格更优惠，中文理解能力更强，最重要的是——国内访问稳定！

1.2 项目结构

本项目采用 Maven 多模块结构：

SpringAI-MCP-RAG-Dev/           # 父工程
├── pom.xml                     # 父工程配置
└── mcp-client/                 # 业务模块
    ├── pom.xml                 # 子模块依赖
    └── src/main/
        ├── java/com/zhou/
        │   ├── Application.java
        │   ├── controller/     # REST 接口
        │   ├── service/       # 业务服务
        │   └── aspect/         # AOP 切面
        └── resources/
            └── application.yml # 配置文件

---

二、依赖配置

2.1 父工程 pom.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 
         http://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.5.0</version>
        <relativePath/>
    </parent>

    <groupId>com.zhou</groupId>
    <artifactId>SpringAI-MCP-RAG-Dev</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
        <module>mcp-client</module>
    </modules>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
</project>

2.2 子模块 pom.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 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>com.zhou</groupId>
        <artifactId>SpringAI-MCP-RAG-Dev</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>

    <artifactId>mcp-client</artifactId>

    <!-- Spring AI BOM 版本管理 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.0.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot AOP -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>

        <!-- Spring AI OpenAI 模块 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Hutool 工具类 -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.30</version>
        </dependency>
    </dependencies>
</project>

关键点：spring-ai-starter-model-openai 不仅支持 OpenAI，还兼容所有提供 OpenAI 兼容接口的模型（DeepSeek、豆包、通义千问等），切换模型只需修改配置！

---

三、配置 AI 服务

3.1 application.yml 核心配置

spring:
  application:
    name: spring-ai-mcp-client
  profiles:
    active: test
  ai:
    openai:
      api-key: sk-xxx                      # 你的 API Key
      base-url: https://api.deepseek.com  # DeepSeek API 地址
      chat:
        options:
          model: deepseek-chat            # 模型名称

logging:
  level:
    root: info

3.2 多环境配置

application-test.yml（测试环境）：

server:
  port: 8090

application-prod.yml（生产环境）：

server:
  port: 9999

通过 spring.profiles.active: test/prod 即可切换不同环境配置。

---

四、实现聊天服务

4.1 定义服务接口

package com.zhou.service;

import reactor.core.publisher.Flux;

/**
 * 聊天服务接口
 */
public interface ChatService {

    /**
     * 同步聊天
     */
    String chat(String prompt);

    /**
     * 流式聊天（SSE）
     */
    Flux<String> chatFlux(String prompt);
}

4.2 实现服务类

package com.zhou.service.impl;

import com.zhou.service.ChatService;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;

@Service
public class ChatServiceImpl implements ChatService {

    private final ChatClient client;

    // 可选：设置系统提示词，让 AI 扮演特定角色
    private final String system = "你是一个解答大师，你的名字叫Lagogo";

    public ChatServiceImpl(ChatClient.Builder chatClientBuilder) {
        this.client = chatClientBuilder
                // .defaultSystem(system)  // 取消注释启用系统提示词
                .build();
    }

    @Override
    public String chat(String prompt) {
        // 同步调用：等待完整响应后返回
        return client.prompt(prompt).call().content();
    }

    @Override
    public Flux<String> chatFlux(String prompt) {
        // 流式调用：逐字返回，适合打字机效果
        return client.prompt(prompt).stream().content();
    }
}

核心要点解析：

注入方式	说明
ChatClient.Builder	推荐！可以自定义配置系统提示词、工具调用等
ChatClient	直接注入，使用默认配置

调用方法	特点	适用场景
.call()	同步阻塞，等待完整响应	后台任务、批量处理
.stream()	异步流式，逐字返回	前端打字机效果、实时对话

---

五、创建 REST 接口

package com.zhou.controller;

import com.zhou.service.ChatService;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
public class HelloController {

    @Autowired
    ChatService chatService;

    /**
     * 健康检查
     */
    @GetMapping("/hello")
    public String hello() {
        return "hello world";
    }

    /**
     * 同步聊天接口
     */
    @GetMapping("/chat")
    public String chat(String prompt) {
        return chatService.chat(prompt);
    }

    /**
     * 流式聊天接口（SSE）
     * 
     * 注意：必须设置 UTF-8 编码，否则中文会乱码
     */
    @GetMapping("/chat/flux")
    public Flux<String> chatFlux(String prompt, HttpServletResponse response) {
        response.setCharacterEncoding("utf-8");
        return chatService.chatFlux(prompt);
    }
}

接口测试：

接口	方法	说明
GET /hello	同步	健康检查
GET /chat?prompt=xxx	同步	返回完整响应
GET /chat/flux?prompt=xxx	SSE 流式	逐字返回响应

---

六、AOP 性能监控

为了监控 AI 服务调用性能，添加一个切面记录慢请求：

package com.zhou.aspect;

import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.stereotype.Component;

@Component
@Aspect
@Slf4j
public class LogAspect {

    /**
     * 环绕通知：拦截 service 层所有方法
     * 耗时超过 2 秒的请求记录为 ERROR 日志
     */
    @Around("execution(* com.zhou.service.*.*(..))")
    public Object log(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();

        Object proceed = joinPoint.proceed();

        String className = joinPoint.getTarget().getClass().getName();
        String methodName = joinPoint.getSignature().getName();
        long cost = System.currentTimeMillis() - start;

        if (cost > 2000) {
            log.error("慢请求警告: {}#{} 耗时 {} ms", className, methodName, cost);
        } else {
            log.info("请求完成: {}#{} 耗时 {} ms", className, methodName, cost);
        }

        return proceed;
    }
}

---

七、启动与测试

7.1 启动应用

cd mcp-client
mvn spring-boot:run

启动成功后访问：http://localhost:8090/hello

7.2 测试同步接口

curl "http://localhost:8090/chat?prompt=你好，介绍一下你自己"

响应示例：

你好！我是一个 AI 助手，可以帮助你回答各种问题、提供建议和解决方案...

7.3 测试流式接口

curl "http://localhost:8090/chat/flux?prompt=写一首关于春天的诗"

响应效果： 响应会逐字返回，就像打字机一样，非常适合前端实现流式输出效果。

---

八、扩展与优化

8.1 支持多种 AI 模型

Spring AI 支持多种模型供应商，只需更换依赖和配置即可：

模型	依赖 artifactId
OpenAI	spring-ai-starter-model-openai
Anthropic Claude	spring-ai-starter-model-anthropic
Google Gemini	spring-ai-starter-model-gemini
阿里通义千问	spring-ai-starter-model-alibaba

8.2 添加全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleException(Exception e) {
        log.error("AI 服务调用异常", e);
        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("服务繁忙，请稍后重试");
    }
}

8.3 后续扩展计划

本项目命名为 SpringAI-MCP-RAG-Dev，后续计划集成：

• MCP（Model Context Protocol）：实现 AI 模型与外部工具的安全交互
• RAG（Retrieval-Augmented Generation）：结合向量数据库实现知识库问答

---

总结

本文从零开始搭建了一个完整的 Spring AI 聊天应用，你学到了：

序号	内容
1	Maven 多模块项目结构设计
2	Spring AI BOM 依赖管理
3	DeepSeek 模型集成（OpenAI 兼容模式）
4	ChatClient 的同步和流式调用
5	REST 接口设计（含 SSE 流式响应）
6	AOP 切面实现性能监控

Spring AI 的核心优势：统一的 API 抽象，让开发者可以轻松切换不同的 AI 模型，而无需修改业务代码。

---

项目源码

完整项目已上传 GitHub，欢迎 Star ⭐️

---

如果这篇文章对你有帮助，欢迎 点赞 👍 收藏 ⭐️ 关注，你的支持是我持续创作的动力！

有问题欢迎在评论区讨论交流～