Java 架构师的 AI 工程笔记——不学 Python，用 Spring Boot 搞 AI Agent
10 年 Java 后端，经历过从单体到微服务的架构迁移。去年开始带团队做第二次技术转型——把 AI 能力嵌入现有业务系统。
转型过程中发现一个尴尬的现实：大部分 AI 教程是 Python 的。LangChain、LlamaIndex、CrewAI……全是 Python 生态。Java 团队想搞 AI，难道要全员转 Python？
在项目里比较了 LangChain4j 和 Spring AI Alibaba 之后，我选了后者。原因很简单：Spring AI Alibaba 把 AI 开发搬到了 Spring 生态里——ChatClient 像 JdbcTemplate 一样顺手，Function Calling 像 Controller 路由一样自然，配置方式还是熟悉的 application.yml。
不用换语言，不用换框架，用你最熟的工具栈做 AI 开发。
这个系列是我在实际项目中验证过的方案。每一篇的代码都能跑，每一个架构决策都有 trade-off 分析。踩过的坑写在这里，省得你再踩一遍。
先看一眼全局地图
在正式开始之前，先花 1 分钟扫一遍整个系列的知识结构。
这张图涵盖了从基础概念到企业实战的全部内容。后面每学完一章，可以回来看看自己在地图上走到了哪里。
五层系统架构——贯穿全系列
整个系列围绕一个核心架构展开。每一章讲的不是孤立的技术点，而是在这个架构上逐层搭建能力：
┌─────────────────────────────────────────┐
│ 接入层 API Gateway / 前端 / 多租户 │ → ch01, ch20
├─────────────────────────────────────────┤
│ 编排层 Graph / Workflow / MultiAgent │ → ch10, ch11
├─────────────────────────────────────────┤
│ 决策层 Agent / ReAct / Context / HITL │ → ch08, ch09
├─────────────────────────────────────────┤
│ 能力层 Tool / Prompt / RAG / Memory │ → ch02-07
├─────────────────────────────────────────┤
│ 基础设施层 安全/成本/测试/可观测/部署 │ → ch14-19
└─────────────────────────────────────────┘
用 Java 架构师的眼光看，这就是一个典型的分层架构——跟你做微服务时画的架构图一个思路。能力层提供零件，决策层负责思考，编排层组织流程，基础设施层保障生产运行。
遇到问题 X，用方案 A 还是 B？
做 AI 系统最头疼的不是"怎么实现"，而是"该不该用"。这棵决策树覆盖了最常见的选型问题，全系列会反复引用：
遇到的问题 推荐方案 对应章节
─────────────────────────────────────────────────────────────
需要外部知识？ → RAG → ch06
需要多步推理？ → Agent（ReAct） → ch08
需要结构化流程控制？ → Graph → ch10
需要多角色协作？ → MultiAgent → ch11
需要外部工具？ → Tool / MCP → ch03, ch12
以上都需要？ → 组合架构 → ch13 完整实战
每一章开头都会回到这棵树，说清楚"什么时候该用这个技术，什么时候不该用"。
这个系列会做哪些项目
光看文档不写东西，学不会。整个系列围绕 1 个主线项目 + 3 个企业实战项目，覆盖四个不同业务场景。
主线项目：「票小蜜」机票比价 Agent
贯穿第 1-13 章，从零开始一步步搭建。第 14-20 章做生产化升级。
用户说"帮我查明天北京到上海最便宜的机票"，它能自动查多个平台、比价、给推荐、等你确认后下单。
用户提问 → 意图理解 → 多平台并行查询 → 比价排序 → 推荐 → 人工确认 → 下单
选这个项目是因为它够"全"——工具调用、对话记忆、知识库检索、多 Agent 协同、人机协作、安全护栏、可观测性，生产级 Agent 该有的能力全都练到。
企业实战项目一：智能客服 Agent（第 23 章）
做过 Java 后端的应该都被客服系统折磨过。这个项目做一个真正能用的智能客服：
- 意图识别：区分 FAQ 咨询、订单查询、投诉、转人工
- 知识库问答：接入企业文档和 FAQ，基于 RAG 回答
- 自动转人工：识别到情绪激动或超出能力范围时，无缝转给人工坐席
- 多租户隔离：不同企业用同一套系统，数据完全隔离
企业实战项目二：Text2SQL 数据分析 Agent（第 24 章）
产品经理找你跑数据，你是不是很烦？这个项目让他们自己来：
- 用自然语言问"上个月华东区 GMV 是多少"，Agent 自动生成 SQL、执行查询、用人话解读结果
- 支持多表关联、复杂聚合
- 带 SQL 注入防护和权限控制
- Reflexion 自我纠错：SQL 执行报错了，Agent 自己改
企业实战项目三：AIOps 智能运维 Agent（第 25 章）
半夜被告警电话吵醒是什么体验？这个项目的目标是让 Agent 先替你看一眼：
- 日志分析：对接 ELK，从海量日志里找关键异常
- 告警分类：自动去重、分级，不是每条告警都值得叫你起来
- 根因分析：不只是告诉你"挂了"，还能分析为什么挂
- 自动修复：简单问题直接执行修复脚本，复杂问题给你建议
四个项目的关系
阶段一 1-7 章 能力层基础 ────────────────────────┐
阶段二 8-13 章 决策层 + 编排层 ─────────────────┐ │
第 13 章 票小蜜 V1（完整落地）◄──┘ │
阶段三 14-20 章 基础设施层 → 票小蜜 V2 ◄──────────┘
│
├── 第 23 章 智能客服 Agent（侧重 RAG + 多轮对话）
├── 第 24 章 Text2SQL Agent（侧重工具调用 + 自我纠错）
└── 第 25 章 AIOps Agent（侧重日志分析 + 自动修复）
主线项目打基础，三个企业项目练场景。可以只做感兴趣的，也可以全做。
学习路径与章节结构
整个系列分成五个阶段。每个阶段结束都有一个能跑的系统，不是那种"学完了但啥也没做出来"的感觉。
阶段一：能力层（第 1-7 章）—— "AI 系统的零件"
从环境搭建开始，逐个掌握 AI 系统的基础组件：ChatClient、工具调用、Prompt 工程、对话记忆、RAG、多模型接入。学完这 7 章，能写一个带记忆和知识库的对话机器人。
| 章节 | 架构层 | 解决什么问题 |
|---|---|---|
| 01 基础概念与环境搭建 | 接入层 | 如何连接 LLM |
| 02 ChatClient 与 Advisor 链 | 能力层 | 如何优雅地调用 LLM |
| 03 Function Calling 与 ToolContext | 能力层 | 如何让 LLM 调用外部工具 |
| 04 Prompt 工程与结构化输出 | 能力层 | 如何控制 LLM 的输入输出 |
| 05 Memory 对话记忆与 Checkpoint | 能力层 | 如何让 LLM 记住上下文 |
| 06 RAG 三种架构 | 能力层 | 如何让 LLM 基于私有数据回答 |
| 07 多模型接入与切换 | 能力层 | 如何管理多个 LLM 提供者 |
阶段二：决策层 + 编排层（第 8-13 章）—— "AI 系统的大脑和指挥"
核心阶段。从 Agent 的设计原则开始，学 ReAct 模式、Context Engineering、Graph 编排、多 Agent 协同、MCP/A2A 协议，最后把前面所有能力组装起来，做出「票小蜜」V1 版。
| 章节 | 架构层 | 解决什么问题 |
|---|---|---|
| 08 Agent 设计原则与 ReactAgent | 决策层 | 如何让 LLM 自主决策和行动 |
| 09 Context Engineering 与 HITL | 决策层 | 如何管理 Agent 的知识和权限 |
| 10 Graph 图编排引擎 | 编排层 | 如何编排复杂多步骤流程 |
| 11 MultiAgent 与 AgentAsTool | 编排层 | 如何让多个 Agent 协作 |
| 12 MCP 与 A2A 协议 | 编排层 | 如何跨系统连接工具和 Agent |
| 13 核心实战：机票比价 Agent | 全栈 | 五层架构完整落地 |
阶段三：基础设施层（第 14-20 章）—— "AI 系统的生产护航"
Agent 能跑和能上线是两回事。加安全护栏、优化 RAG 检索、做语义缓存、建测试体系、接可观测性、搞服务化与平台架构。
| 章节 | 架构层 | 解决什么问题 |
|---|---|---|
| 14 Guardrails 安全护栏体系 | 安全 | 如何防护 LLM 的安全风险 |
| 15 RAG 数据工程与检索优化 | 数据 | 如何让检索又准又快 |
| 16 语义缓存与成本工程 | 成本 | 如何控制 Token 成本 |
| 17 Prompt 运营与版本管理 | 运营 | 如何管理和迭代 Prompt |
| 18 AI 应用测试与评估体系 | 质量 | 如何评估 AI 输出质量 |
| 19 可观测性 | 可观测 | 如何监控 AI 系统运行 |
| 20 性能优化、服务化与平台架构 | 平台 | 如何从系统走向平台 |
阶段四：高级篇（第 21-22 章）
Agent 架构范式进阶和高级认知与容错。有余力再看。
阶段五：企业实战（第 23-25 章）
三个独立的企业级项目，五层架构的完整落地。
| 阶段 | 章节 | 学完能做什么 |
|---|---|---|
| 能力层 | 1-7 章 | 一个带记忆和知识库的对话机器人 |
| 决策层 + 编排层 | 8-13 章 | 「票小蜜」机票比价 Agent V1 |
| 基础设施层 | 14-20 章 | 有护栏、可监控、可服务化的 Agent V2 |
| 高级篇 | 21-22 章 | Agent 架构选型与容错设计 |
| 企业实战 | 23-25 章 | 智能客服 / Text2SQL / AIOps Agent |
每篇文章的结构
每章分成两个部分：
理论篇——搞清楚"是什么"和"为什么"。我会用 Java 世界的东西来类比——ChatClient 就像 JdbcTemplate，Memory 就像 HttpSession，Function Calling 就像 Controller 路由。看不懂 AI 论文没关系，你能看懂 Spring 源码就行。图表优先——架构、流程、时序能用图就不用文字。
实战篇——动手写代码。每段代码都是完整可运行的，复制到项目里就能跑。每个编码环节后都有"验证一下"步骤，不攒到最后才测试。另外每章末尾有 FAQ 和踩坑记录，包含方案选型的 trade-off 分析。
如果时间紧，理论篇扫一遍（15 分钟），实战篇一定要跟着做（1-2 小时）。光看不练等于没学。
技术栈
| 组件 | 版本 | 说明 |
|---|---|---|
| Java | 21 | LTS，用到 record、pattern matching |
| Spring Boot | 3.5.11 | 父 POM 统一管理 |
| Spring AI Alibaba | 1.1.2.2 | BOM 统一管理 |
| LLM | 通义千问 qwen-plus | 默认模型，后面会讲怎么切换 |
| 构建工具 | Maven | 每章一个子模块，互不干扰 |
| IDE | IntelliJ IDEA | 社区版就够 |
开始之前你需要准备
4 件事：
- JDK 21 + Maven 3.9+（你应该已经有了）
- IntelliJ IDEA（社区版就行）
- 通义千问 API Key——去阿里云百炼平台注册，有免费额度，够学完整个系列
- Git——把课程代码仓库拉下来
项目结构
spring-ai-alibaba-course/
├── pom.xml ← 父 POM，统一管理版本
├── docs/ ← 你正在读的系列文章
├── xmind/ ← 课程脑图（XMind 源文件）
├── quick-start/ ← 第 1 章代码
├── chat-client/ ← 第 2 章代码
├── function-calling/ ← 第 3 章代码
├── prompt-engineering/ ← 第 4 章代码
├── memory/ ← 第 5 章代码
├── rag/ ← 第 6 章代码
├── ... ← 每章一个 Maven 子模块
├── flight-agent/ ← 第 13 章：票小蜜完整版
├── smart-cs/ ← 第 23 章：智能客服
├── text2sql/ ← 第 24 章：数据分析
└── aiops/ ← 第 25 章：智能运维
每个模块都能独立运行，学到哪章跑哪章就行。
关于作者
10 年 Java 后端，经历过从单体到微服务的架构迁移，现在正在带团队做第二次技术转型——把 AI 能力嵌入现有业务系统。
这个系列不是翻译文档，是我在实际项目中验证过的方案。每一篇的代码都能跑，每一个架构决策都有 trade-off 分析。踩过的坑写在这里，省得你再踩一遍。
第 1 章见。
本系列代码仓库：GitHub - spring-ai-alibaba-course（持续更新中）
如果这篇文章对你有帮助，欢迎点赞收藏。有问题欢迎评论区交流。
