序言：用 Java 把 Spring AI 与 LangGraph4j 做成可交付能力

技术分享 · Day 0 总览 固定版本：Spring AI 2.0.1 × LangGraph4j 1.8.25

更新节奏：每日一篇（工作日优先）。已发布文章会按反馈小幅修订，主版本契约不变。

---

为什么开这个系列

很多 Java 后端团队接大模型时，会经历同一条曲线：Demo 能跑 → 格式不稳定 → 工具不敢开 → 流程写进 prompt → 出问题无法复盘。Python 社区资料很多，但 Maven 坐标、Spring 自动配置、Feign / SSE / 审计习惯与 Java 工程并不一一对应。

本系列面向已经会 Spring Boot、准备把大模型接进真实业务的开发者。目标不是背模块清单，而是回答一组可交付的问题：

• 一次模型调用在 Java 里落到哪些对象？

• 工具、记忆、RAG 的边界在哪里？

• 什么时候用 ChatClient，什么时候必须上图？

• 中断、人工审批、恢复上线后怎么测、怎么观测？

文风： 分享笔记——为什么 → 怎么用 → 边界与坑。 依据： 官方 GitHub 全量源码（_upstream/）与 analysis/ 能力地图；正文与 BOM 冲突时，以检出源码为准并回写。

---

两个框架，各管一层

层	框架	主要职责	你会反复见到的对象
应用能力层	Spring AI 2.0.1	模型接入、对话、工具、记忆、RAG、知识图谱、流式、MCP、观测	ChatModel、ChatClient、Advisor、@Tool、VectorStore
流程编排层	LangGraph4j 1.8.25	状态图、分支、循环、Checkpoint、HITL、AgentExecutor	AgentState、Channel、Node / Edge、CompiledGraph、Saver

口诀（全集共用）：

共享模型与工具，替换编排引擎；MCP 扩展工具目录，不替代编排。

简单对话走 ChatClient；当流程本身成为业务资产——需要显式分支、限轮、暂停、恢复——再上 LangGraph4j。两层共用同一套模型、工具目录、记忆 / RAG 与权限审计，对外仍走统一的 DTO / SSE / 错误协议。

---

三个卡点，三层解法

现象	先解哪一层	系列会展开的方向
只会调模型，回答飘、空结果、限流不会处理	Message / Prompt / 结构化输出	请求链路、空结果处理、DTO 校验
需要查资料、调业务 Bean、跨轮记忆	Tool / Advisor / RAG / MCP	工具白名单、记忆策略、检索与权限
要分支、循环、人工审批、中断后继续	StateGraph / Checkpoint / HITL	显式编排、暂停恢复、审计与观测

选型拿不准时，先写四项约束：是否需要工具、是否需要跨轮状态、是否需要显式分支、是否允许中断后恢复——再选最小方案。复杂度不是能力证明，每加一层，测试、升级和运维责任都会增加。

---

每日连载怎么跟

阶段	内容
Day 0（本文）	总览、版本契约、两层分工、更新说明
随后每日	一篇独立正文：前置、可运行结果、失败样例、边界与坑
修订	勘误与示例对齐会回写已发文章；不静默换主版本号

每篇尽量自包含，方便单独转发；连载按「先打底、再加深、再落地」推进，但不要求你按目录表逐条勾选——遇到卡点，跳到对应主题即可。

---

源码地图：写教程的底气

本系列不是翻译官方文档，而是以固定 tag 全量检出为契约：

地图	用途
Spring AI 2.0.1 源码地图	Providers、VectorStore、MCP、Tool、Observation
LangGraph4j 1.8.25 源码地图	Core / Agent / 全部 Saver / Studio / OTEL / Spring AI 桥

索引入口 → analysis/README.md

---

读完后你应该能做什么

1. 说清 Spring AI 核心抽象的职责边界，并在 Boot 4.x 工程里钉住 BOM 与 starter。

2. 用 ChatClient 完成同步、流式、结构化输出，并处理空结果、超时与限流。

3. 配置 Advisor、Tool、RAG、MCP，并知道哪些逻辑不该塞进 prompt。

4. 用 LangGraph4j 表达分支、循环、Checkpoint 与人工审批，理解 Compile 与 Runnable 配置差异。

5. 设计双模式架构：共享底座 + 可替换编排，统一 SSE / 错误协议。

6. 按生产能力门禁逐步上线，而不是一次堆满能力。

每一关都要有：成功指标、失败样例、回滚方案、负责人、可观察证据。

---

开始前的准备

项	要求
语言 / 框架	Java 17+（推荐 21）、Spring Boot 4.x、Maven 3.8+
模型	兼容 Spring AI 2.0.1 的供应商 endpoint 与模型名
密钥	仅环境变量（如 OPENAI_API_KEY），不进 yml / 日志 / 截图
基础	泛型、Lambda、Record；涉及流式时需 Reactor Flux 入门

---

系列声明

• 技术栈：Spring AI 2.0.1 · LangGraph4j 1.8.25 · Spring Boot 4.x

• 官方：Spring AI Reference 2.0 · LangGraph4j 文档