Spring AI Alibaba 1.0：Java原生Agent工程化实践指南

1. 为什么 Java 开发者突然在朋友圈刷屏“Spring AI Alibaba 1.0”？

上周五下午三点，我正调试一个老系统的线程池参数，钉钉群里突然炸出十几条消息：“快看 Spring 官网！”“Alibaba 模块正式 GA 了！”“Java 写 Agent 终于不用硬套 Python 脚本了”。不是营销号，是清一色的后端同事——有带三个项目的架构师，有刚转正半年的应届生，还有常年只写 SQL 和 MyBatis 的 DBA。他们转发的链接指向 Spring 官方博客那篇标题为《Spring AI Alibaba 1.0 is Generally Available》的公告，配图是一行干净的 Maven 依赖坐标和一段三行代码的 Agent 初始化示例。

这背后不是偶然。过去两年，我参与过 7 个涉及大模型能力的内部项目，其中 5 个最终都卡在“最后一公里”：业务系统用 Spring Boot 写，核心流程跑在 Tomcat 或 GraalVM 上，但只要一碰 Agent 编排、工具调用、记忆管理、流式响应这些事，团队就得临时拉个 Python 工程师搭个 FastAPI 中间层，再用 HTTP 调用。结果呢？一次线上故障排查花了 6 小时——Java 端日志显示“请求已发出”，Python 端日志却压根没收到；另一个项目上线后发现，Java 服务每分钟发起 2000 次 HTTP 调用，而 Python 中间层 CPU 常驻 95%，根本扛不住流量峰。我们不是不会写 Python，是不敢把核心链路交给跨进程、跨语言、跨 GC 的胶水层。

Spring AI Alibaba 1.0 的真正价值，不在于它“支持通义千问”或“能连 DashScope”，而在于它把 Agent 的生命周期、工具注册、提示词编排、流式响应、错误重试这些原本散落在 Python LangChain/LlamaIndex 各个模块里的能力，原生塞进了 Spring 的 Bean 容器、AOP 切面、事件总线和配置中心里。它让 Agent 不再是一个“外部黑盒”，而是像 @Service 一样可注入、可代理、可监控、可灰度的 Spring 原生组件。你不需要新建一个 Python 项目，不需要维护两套配置中心，不需要在 Java 里手写 OkHttp 调用封装——你只需要声明一个 @Bean ，加一个 @AIListener 注解，Agent 就自动接入你的 Spring 生态。这才是标题里“终于不用羡慕 Python”的底层逻辑：不是 Java 抄了 Python 的功能，而是 Spring 把 AI 工程化这件事，重新定义了一遍。

关键词里反复出现的 “Spring AI”“Alibaba”“Java”“Agent”，其实指向一个被长期忽视的现实：AI 应用落地的主战场从来不在 Jupyter Notebook 里，而在每天处理百万级订单、承载千万用户登录、与 Oracle 和 Kafka 实时交互的企业级 Java 系统中。当 Python 社区还在争论 asyncio 和 threading 在 LLM 调用中的性能差异时，Spring AI Alibaba 已经把 Agent 的并发控制、熔断降级、链路追踪、配置热更新这些企业级能力，作为默认项写进了 starter 的 auto-configuration 里。这不是一场语言之争，而是一次工程范式的迁移——从“用脚本拼凑能力”到“用框架治理能力”。

2. 从零跑通第一个 Java Agent：三步完成，但每步都有坑

我用一台刚重装系统的 MacBook（M2 Pro，16GB 内存），从零开始搭建环境、写代码、跑通第一个能调用通义千问并执行数据库查询的 Agent。整个过程耗时 47 分钟，其中 38 分钟花在填坑上。下面我把真实操作步骤、每个环节的预期与实际差异、以及填坑的关键动作，按时间线还原出来。

2.1 环境准备：JDK 版本不是越高越好，17 是当前最稳选择

官方文档写着“JDK 17+”，但没说清楚“+”的边界。我一开始装了 JDK 21， mvn clean compile 直接报错：

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.11.0:compile 
(compile) on project demo: Fatal error compiling: java.lang.IllegalAccessError: 
class org.springframework.boot.devtools.restart.classloader.RestartClassLoader 

查 issue 发现这是 Spring Boot 3.2.x 与 JDK 21 的 --enable-preview 兼容性问题。降级到 JDK 17 后，编译通过，但运行时报 NoClassDefFoundError: jakarta/servlet/Filter ——因为 Spring AI Alibaba 1.0 默认依赖 Spring Boot 3.2.0，而该版本强制要求 Jakarta EE 9+，但我的 IDE（IntelliJ IDEA 2023.2）默认创建的 Spring Initializr 项目仍勾选了 spring-boot-starter-web （基于 Servlet API 4.x）。解决方案不是升级 IDEA，而是手动修改 pom.xml ：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- 显式排除旧版 servlet -->
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- 替换为 Jakarta 兼容版本 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

提示：Spring AI Alibaba 的流式响应（Streaming）强依赖 WebFlux 的 Flux ，用传统 spring-boot-starter-web 会导致 StreamingChatClient 初始化失败，且错误日志极不友好，只会打印 Failed to instantiate [org.springframework.ai.chat.client.ChatClient] 。这是新手最容易卡住的第一关。

2.2 依赖引入：starter 不能只加一个，必须成对出现

官方 Quick Start 只给了这一行：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

但实际运行时， ChatClient 创建失败，日志里反复出现 Could not resolve placeholder 'alibaba.dashscope.api-key' 。排查发现，这个 starter 只负责“连接阿里云模型”，却不提供“Agent 编排引擎”。必须额外引入：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>1.0.0</version>
</dependency>

更关键的是， spring-ai-core 依赖 spring-ai-chat 模块，而后者又依赖 spring-ai-document ——如果你的 Agent 需要 RAG（比如从本地 PDF 加载知识库），还必须显式引入：

&