为什么要写这个系列
做Java后端十年，我接触过不少企业的核心系统。
金融、电商、政务——行业不同，但底层的现状惊人地相似：生产系统还在Java 8，框架停在Spring Boot 2.x甚至更早，代码跑了很多年，没人敢轻易动。
去年开始，几乎每个项目都在谈接AI。
但真正动手的时候，团队就卡住了。
不是因为不懂大模型，而是老系统本身接不住。JDK版本不够，Spring AI引不进来；依赖树牵一发动全身，升级一个包怕带崩一片；生产流量压着，不敢拿主流程赌一个AI试点。
更危险的是硬塞。我见过团队在老系统的Service层直接new一个HttpClient调模型API，Prompt拼在业务代码里，超时没配、降级没有。模型响应慢的时候，老系统的订单查询线程池被占满，主流程跟着卡住。还有团队把用户手机号、身份证原样送进Prompt，过了两个月才被安全审计发现。
这种事见多了，我就开始想一个问题：老系统不具备直接接入AI的条件，这是不是大多数企业的常态？
答案是肯定的。而且这不应该成为接不了AI的理由。
核心思路其实就三条：
老系统少改 —— 不升级 JDK，不引入 Spring AI 依赖
AI 能力旁路 —— 独立部署，老系统通过 HTTP 或 MQ 调用
企业边界先行 —— 脱敏、审计、降级、幂等比模型调用更重要
这个系列就是把这三条线展开成10讲。
从AI Gateway到MCP工具中心，从SQL Agent到RAG知识库，从工单Agent到多Agent研发团队——每一讲都围绕同一个前提：
你的老系统还在跑Java 8，你不能为了AI去赌它的稳定性。
每讲配套一个可运行的Maven Lab，不讲空架构，不写Hello World。你跑得通Demo，看得到边界，拿得到代码。
这就是我做这个系列的原因。
这个系列帮你建立企业 AI 接入的架构意识。每个 Demo 都可独立运行，每讲都配有边界设计和企业避坑。
但意识不等于系统。当你真正要在自己的项目里落地时，会发现：
- 10 个独立 Lab 的组件需要整合成一个完整的 AI 能力中心
- Stub 模型需要替换成真实模型调用
- 权限、审计、脱敏需要从 Demo 级别升级到生产级别
先把架构意识打好，落地时才能走得更稳。
Java 8老系统旁路接入AI Gateway：不升级JDK也能用AI
很多企业接AI的真实起点，不是从0写一个新应用。
更常见的情况是：
生产系统还在 Java 8
框架还是 Spring Boot 2.x 甚至更老
代码跑了很多年，不敢轻易升级
业务已经开始要求接 AI
这时候最危险的做法，是把Spring AI或大模型SDK直接塞进老系统。
不是因为Spring AI不好，而是老系统本身承担着生产流量、历史业务和稳定性风险。为了一个AI能力去升级JDK、升级Spring Boot、调整依赖树，很容易把"AI试点"变成"老系统改造项目"。
所以第一讲先回答一个更朴素的问题：
Java 8老系统不升级，怎么接入AI？
我的答案是：旁路接入。
先别急着接模型
很多人一听"老系统接AI"，脑子里会先出现模型API：
拿 API Key
拼 Prompt
调用模型
解析结果
但对老系统来说，第一步不是模型，而是接入边界。
你要先想清楚4个问题：
老系统要不要升级？
AI 调用失败会不会影响主流程？
敏感数据能不能直接进模型？
AI 输出能不能直接改业务状态？
如果这些问题没想清楚，模型调通也只是一个脆弱Demo。
本讲的代码就是围绕这4个问题设计的。
本讲能学到什么
本讲配套代码是一个Maven可运行的基础Lab。
代码目录：
code/spring-ai-enterprise-lab/labs/chapter01-ai-gateway
运行：
.\\compile-and-run.ps1
运行后会看到4个场景：
最重要的是：AI只生成处理建议，不自动修改老系统订单状态。
推荐的接入方式
第1讲采用的是旁路架构：
Java 8 老订单系统
↓
AiGatewayClient
↓
AI Gateway
↓
模型调用、脱敏、审计、降级等能力
在Demo里，AiGatewayClient为了方便演示，直接Java调用OrderSummaryService。
在真实项目里，它应该变成HTTP调用：
老系统
↓ HTTP
AI 能力中心
这里的重点不是"HTTP代码怎么写"，而是依赖方向：
老系统依赖一个稳定的 Gateway 接口
老系统不直接依赖 Spring AI
老系统不感知模型供应商
这样以后模型从A换到B，或者AI能力中心从单模型变成多模型路由，老系统都不需要跟着改。
旁路失败时怎么办
旁路不是把风险丢给另一个服务。
老系统接AI时，要先定义失败策略。
本讲建议的同步调用策略是：
连接超时：短，比如 3-5 秒
读取超时：可稍长，比如 10-30 秒
老系统侧不做多次重试
AI Gateway 侧负责重试、熔断和降级
老系统拿不到 AI 结果时，继续走人工处理流程
也就是说，AI Gateway是增强能力，不是老系统主流程的单点依赖。
在本讲Demo中，模型不可用时会返回：
{
"fallback": true,
"summary": "AI 模型服务暂时不可用，请稍后重试。"
}
老系统依旧能拿到一个固定建议，而不是直接抛异常把页面或业务流程打断。
如果是更高风险的业务，比如支付、审批、退款，就不建议同步等待AI结果。
更稳的方式是异步：
老系统写入业务结果
↓
发送事件
↓
AI 能力中心异步分析
↓
生成建议或待办
↓
人工确认后处理
本讲先讲同步旁路，因为它最容易理解；后面的工单、工作流、多Agent会继续扩展异步和人工确认。
端到端走一遍
现在把整条链路串起来看。
老系统收到一个订单处理请求：
订单 O202606050001 延迟发货
客户希望今天给处理方案
文本中包含手机号、身份证、邮箱
第一步，老系统调用自己的业务服务：
legacyOrderService.assistOrder(orderId, orderText);
第二步，LegacyOrderService组装一个请求对象：
new OrderSummaryRequest(
"demo",
"u1001",
orderId,
orderText
);
这里的tenantId和operatorId很重要。
企业系统里的AI调用不能只有一段文本，还要知道：
哪个租户
哪个操作人
哪个业务对象
哪一次请求
第三步，老系统通过AiGatewayClient调用AI Gateway：
public OrderSummaryResult summarizeOrder(OrderSummaryRequest request) {
return orderSummaryService.summarize(request);
}
当前是Demo直接调用，生产环境可以替换成HTTP Client。
第四步，AI Gateway执行治理流程：
校验请求
检查重复请求
检查调用频率
脱敏订单文本
记录请求审计
判断模型是否可用
调用模型或返回降级
整理结构化响应
记录响应审计
第五步，老系统拿到结构化建议：
{
"summary": "客户反馈订单延迟发货，需要尽快给出处理方案。",
"riskLevel": "MEDIUM",
"suggestedActions": [
"查询物流状态",
"联系仓库确认发货时间",
"向客户同步预计处理时间"
]
}
注意，这里只是建议。
Demo里还会输出：
legacyOrderStatusBefore=DELAYED, legacyOrderStatusAfter=DELAYED
boundary=AI 只生成处理建议，不自动修改老系统订单状态。
这就是老系统接AI的第一条底线：
AI可以辅助判断，但不能默认替你改业务状态。
代码应该看哪些类
这篇文章不需要你一次看完所有Filter。
第一讲真正建议先看的类只有5个：
legacy/LegacyOrderService.java
legacy/AiGatewayClient.java
common/OrderSummaryRequest.java
common/OrderSummaryResult.java
gateway/OrderSummaryService.java
它们对应的是老系统接入AI的主线：
老系统业务服务
↓
AI Gateway 客户端
↓
请求/响应 DTO
↓
AI Gateway 总入口
理解这条线以后，再去看Gateway内部治理。
Gateway内部不要平铺理解
本讲代码里有一条Pipeline，但不要把9个Filter当成同等重要的知识点硬背。
可以分成三层：
第一层：接入必需
ValidationFilter
MaskingFilter
AuditRequestFilter
ModelCallFilter
AuditResponseFilter
这一层解决的是：
请求是否合法
敏感数据有没有进模型
谁调用了 AI
模型结果怎么回来
响应有没有审计
如果只做最小可用AI Gateway，至少要有这一层。
第二层：企业稳态
IdempotencyFilter
RateLimitFilter
CircuitBreakerFilter
这一层解决的是：
重复请求怎么办
调用太频繁怎么办
模型不可用怎么办
这些不是炫技，而是老系统接外部能力时经常会遇到的问题。
第三层：输出整理
ParseResponseFilter
FallbackAnswerFactory
这一层解决的是：
模型结果怎么变成业务系统能理解的结构
失败时怎么给出固定可控结果
这样分层以后，Pipeline就不再是一串吓人的类名，而是一套接入思路。
脱敏要看输入和输出
正常请求里包含：
手机号 13800000000
身份证 110101199001011234
邮箱 vip@example.com
审计日志会记录：
maskedFields=[idCard, mobile, email]
返回结果里也会带上：
{
"maskedFields": ["idCard", "mobile", "email"]
}
这让读者能直接把输入和输出对应起来：
原始订单文本里有敏感信息
↓
Gateway 脱敏
↓
审计记录脱敏字段
↓
响应告诉老系统处理过哪些字段
企业里做AI接入，不是"相信我们已经脱敏了"，而是要让脱敏行为可观察。
为什么要做幂等
很多AI Demo不讲幂等。
但在企业里，重复请求很常见：
用户重复点击
网关超时重试
MQ 重复投递
前端刷新页面
如果每次都重新调用模型，就会带来两个问题：
- 重复成本。
- 重复处理风险。
本讲里相同订单重复请求会命中幂等缓存，不再穿透后续AI调用链路。
这不是复杂功能，但很贴近企业真实需求。
企业避坑
这篇文章的避坑点，其实可以归成4句话。
第一，老系统不要为了接AI贸然升级。
先旁路接入，降低试点风险。
第二，AI调用失败不能拖垮老系统。
同步调用要有超时和降级，高风险业务优先考虑异步。
第三，敏感数据不要裸奔进模型。
手机号、身份证、邮箱至少要先脱敏，而且脱敏行为要可观察。
第四，AI输出默认只是建议。
除非经过明确审批和授权，否则不要让AI自动修改订单、退款、审批、支付等业务状态。
从 Demo 到落地，还差什么
本讲帮你跑通了旁路接入 AI 的核心链路，但从一个可运行 Demo 到真正在企业落地，还差几步：
模型替换：当前 Demo 用 Stub 模拟模型调用。真实项目需要接入大模型 API、管理 Prompt 模板、处理模型返回格式的稳定性。
多模型路由：企业不会只用一个模型。不同场景需要按成本、精度、速度选择不同模型，还要支持模型切换时老系统无感知。
运维可观测：生产环境需要调用看板——调用量、延迟分布、降级触发次数、各 Filter 耗时。Demo 里没有这些。
动态配置：限流阈值、熔断参数、脱敏规则不能写死在代码里。生产级 Gateway 需要配置中心，按租户动态调整。
如果你正在推进企业 AI 接入落地，后续会有一个完整的 AI 能力中心工程把这些组件整合起来，届时会单独介绍。
和后续9讲的关系
第1讲是整个公开系列的总纲。
后面的内容都会复用这条主线：
老系统少改
↓
AI 能力旁路
↓
企业边界先行
第2讲会讲MCP Tool Center：老系统能力如何包装成受控工具。
第3讲会讲SQL Agent：AI查库为什么必须只读、白名单和LIMIT。
第6讲会讲RAG：企业知识库为什么必须有权限和引用。
第9、10讲会把AI放进工作流和多Agent研发流程。
小结
Java 8老系统接AI，不应该从"怎么调大模型API"开始。
更稳的第一步是：
老系统不升级
AI Gateway 旁路部署
同步调用有超时和降级
敏感数据先脱敏
调用过程可审计
AI 只给建议，不直接改业务状态
这篇文章真正想讲的不是一个Gateway Demo，而是一种思维方式：
先保护老系统，再引入AI能力。
