MCP 落地前 Java 后端必须自建的 6 件事:鉴权、多租户、审计、计费、幂等与错误码语义
MCP 落地前 Java 后端必须自建的 6 件事:鉴权、多租户、审计、计费、幂等与错误码语义
一、问题变了:从"调通大模型接口"到"把模型能力收进 Java 系统"
2026 年的后端 AI 集成,难点已经不在"能不能调通一个大模型接口",而在"怎么把模型能力稳定地收进现有 Java 系统" [1]。这两句话听起来接近,实际对应的工程量差了一个数量级:前者是一个 HTTP 客户端加一段 JSON 解析,后者是把一次不确定的、有成本的、可能产生副作用的调用,纳入既有的身份体系、租户隔离体系、审计体系、成本核算体系和故障处置体系。
1.1 集成问题的三个阶段
可以把集成成熟度粗分为三段:
| 阶段 | 目标 | 典型产物 | 仍需自建的工程 |
|---|---|---|---|
| 能调通 | 打通一次调用 | Demo、PoC、一个能返回结果的接口 | 几乎全部 |
| 能复用 | 多场景复用工具与模型 | 工具注册表、统一客户端封装、Prompt 管理 | 鉴权、多租户、错误契约 |
| 能治理 | 可控、可追、可计费、可演进 | 网关化接入、审计流、配额、版本治理 | 全部企业级控制面 |
绝大多数团队在第一阶段就宣布"落地完成",然后在第二、三阶段被线上问题反复教育。原因很简单:大模型调用与传统 RPC 有三个本质差异——结果不确定(同样的输入可能不同输出)、成本非线性(token 计费、重试与多轮循环会放大开销)、副作用不可忽略(Agent 触发的工具调用会写库、发消息、改配置)。传统后端的三件套(接口、事务、日志)不足以覆盖这三类差异。
1.2 三个技术变量分别解决什么
社区讨论最密集的三个变量是 Spring AI、MCP(Model Context Protocol)与 Agent 内嵌 [1][2][3]。它们的分工需要先说清楚:
| 变量 | 解决的问题 | 本质 | 不解决的问题 |
|---|---|---|---|
| Spring AI | 多厂商调用、工具声明、RAG 链路的编程模型统一 | 能力层抽象 | 身份、隔离、计费、审计 |
| MCP | 工具与资源的跨模型、跨框架复用与调用契约 | 协议层标准化 | 企业级控制面(见第二节) |
| Agent 内嵌 | 多步工具编排在业务进程内运行 | 运行时内嵌 | 成本收敛、可预测性、责任边界 |
一句话概括:它们解决"调用与工具发现问题",不解决"治理问题"。协议给骨架,系统给血肉。
1.3 证据口径声明
在进入正题前必须交代材料性质,这直接影响后文所有"未标准化"表述的强度:
本文缺口清单的"未标准化"判断来自中文技术社区二手文章的自述 [2],采集记录中的热度指标全部缺失(均为 0),且相关三篇文章出自同一作者系列 [1][2][3],属同源讨论,不能当作多份独立佐证。因此本文只谈"社区讨论密度",不做热度排名。另外,"Spring AI 2.0"这一版本表述来自社区文章,其正式版本状态、MCP 当前规范修订号、具体 API 与方法签名,均需以官方文档与 release notes 为准 [3];本文代码仅给出 Spring 生态通用能力骨架,不给出未经核实的类名与方法签名。
二、先划清边界:MCP 现在给了什么,没给什么
这是全文事实风险最高的一节,也是决定"自建范围"的关键。社区文章称 MCP 尚未标准化鉴权与多租户、审计与合规、配额计费、幂等语义、错误码语义与版本兼容策略 [2]。这个说法作为"工程缺口清单"是成立的,但作为"协议完全空白"的表述则不准确,需要分层修正。
2.1 协议已提供的部分
MCP 建立在 JSON-RPC 风格的请求/响应模型之上,提供了工具与资源的发现机制、调用契约、传输层抽象,以及协议版本与能力(capability)协商机制。也就是说,"客户端如何知道有哪些工具、如何调用工具、如何声明自己支持什么"这一层,协议是有约定的。
2.2 边界模糊区:鉴权
MCP 规范针对 HTTP 传输设有授权相关章节,取向是 OAuth 2.1 一类的标准授权框架。这意味着"如何把 token 带到 MCP Server"并非完全空白。但要注意三点:
- 传输覆盖不均:授权框架主要面向 HTTP 传输,stdio 等本地传输的信任模型完全不同,需要另行设计。
- 规范给的是接入方式,不是身份治理:token 怎么签发、怎么映射到企业 IAM、用户身份如何穿透到下游工具、机器身份与用户身份如何区分,这些都不在协议范围内。
- 实现差异大:具体支持哪些授权流、是否支持 token exchange(代表用户调用下游),取决于所用 SDK 与网关版本,务必查官方文档。
值得注意的是,AI 工具链的"每用户身份"治理在基础设施侧确实有动作:GitHub Copilot 的 BYOK 场景已支持基于 OAuth 的按用户认证,Microsoft 365 Copilot 提供按用户的 OAuth token exchange [10]。这从侧面说明:按用户身份穿透是企业级 AI 工具的真实需求,但它是由具体产品与 SDK 实现的,不是协议自动送上门的能力。
2.3 明确的实现自决区
| 能力 | 协议覆盖情况 | 自建程度 | 对应章节 |
|---|---|---|---|
| 鉴权 | HTTP 传输有授权框架,其他传输与企业 IAM 对接需自建 | 半自建 | 四 |
| 多租户隔离 | 无统一约定 | 完全自建 | 五 |
| 审计与合规 | 无统一约定 | 完全自建 | 六 |
| 配额与计费 | 无统一约定 | 完全自建 | 七 |
| 幂等语义 | 请求标识存在,但"重复调用是否产生重复副作用"无约定 | 完全自建 | 八 |
| 错误码语义与版本兼容 | 协议层有错误返回与版本协商,业务/工具级语义无约定 | 半自建 | 九 |
因此更准确的表述是:MCP 把"能调用"标准化了,把"如何安全、可控、可计费地调用"留给了实现方。 对 Java 企业后端团队来说,这不是坏消息——恰恰是把已有的 Spring Security、审计、配额、幂等资产复用到 AI 调用链上的机会。

三、缺口总览:一张表决定投入顺序
以一个贯穿案例说明:某企业内部"AI 工具网关",员工通过 Agent 调用内部知识库检索工具与外部模型,后端为 Spring Boot 3.x 微服务,已接 OAuth2/JWT 与统一网关。
| 缺口 | 不做的后果 | 事故形态(推演,非真实案例) | 实施成本 | 可否后补 |
|---|---|---|---|---|
| 鉴权 | 谁调用的说不清,越权无从阻断 | 用服务账号调用外部模型,离职员工 token 仍有效 | 中 | 否,试点前置 |
| 多租户 | 跨租户数据泄漏 | A 部门检索命中 B 部门向量库切片 | 中 | 否,试点前置 |
| 审计合规 | 出事无法自证,无法回答"模型依据什么做了这个动作" | 合规检查时只能给出原始日志片段 | 中 | 部分可后补 |
| 配额计费 | 成本失控,无法归属 | Agent 循环导致单日 token 费用异常放大 | 中 | 可后补,但越晚越贵 |
| 幂等 | 重试产生重复副作用 | 超时重试导致同一工单被创建两次 | 中 | 写操作场景不可后补 |
| 错误码语义 | 调用方只能"全量重试"或"全量放弃" | 网络抖动与业务拒绝被同等处理,重试放大故障 | 低 | 可后补,但代价高 |
排序逻辑是:安全与隔离 > 可追溯 > 可计费 > 可恢复 > 可演进。原因很直接:前两项决定"能不能上线",中间两项决定"能不能规模化",最后一项决定"能不能长期演进"。
试点期的最小可行内控(Minimum Viable Control,MVC)只有三件:鉴权、租户上下文、最小审计。这三项缺失时上线,等于把一个身份不明、隔离无效、无法追溯的执行器放进生产环境。
四、缺口 1:鉴权——谁在调用,凭什么是他
4.1 身份模型二选一
机器身份(client credentials):Agent 以服务身份调用,适合系统级任务(如定时生成报表摘要)。优点是简单、凭证管理集中;缺点是丢失终端用户信息,审计只能追到"某个 Agent",配额也只能算到服务头上。
用户身份透传(token exchange / on-behalf-of):员工的 token 经授权后换取面向下游的受限 token。优点是审计、配额、数据权限都能归到人;缺点是链路长、依赖授权服务器支持 token exchange,且要在每个跳点阻止身份被"洗掉"。
企业内部工具网关几乎总是需要后者作为主路径、前者作为补充。单一服务账号代表所有用户,是审计与计费体系的共同灾难源。
4.2 在 Spring 中的落点
鉴权分三步:验证 token → 建立调用上下文 → 向下游注入受限凭证。第一步用 Spring Security 的 Resource Server 能力完成,第二步用 Filter/Interceptor 或参数解析器建立上下文,第三步是拦截器在出站调用时注入凭证。下面只给结构示意:
/**
* 结构示意:将已认证的调用方身份固化为不可变调用上下文。
* 具体 SecurityContext 获取 API、token 解析配置以所用 Spring Boot / Spring Security 版本文档为准。
*/
public record CallerContext(String subject, // 用户主体或服务主体
String tenantId, // 租户
String clientId, // 调用应用
String authLevel // 例如 password / m2m / delegated
) {}
@Component
public class CallerContextFilter implements Filter {
private static final ThreadLocal<CallerContext> CTX = new ThreadLocal<>();
public static CallerContext current() {
CallerContext c = CTX.get();
if (c == null) throw new IllegalStateException("调用上下文缺失,拒绝执行");
return c;
}
@Override
public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
throws IOException, ServletException {
try {
// 1. 从 SecurityContext 取出已校验的认证信息
// 2. 映射 tenantId 与 authLevel(映射规则来自 IAM 声明或本地配置)
CTX.set(new CallerContext("subject", "tenant", "client", "delegated"));
chain.doFilter(req, res);
} finally {
CTX.remove(); // 必须清理,避免线程复用导致的身份串号
}
}
}
关键取舍在第三步:下游凭证注入。如果下游系统支持 OAuth2,优先用 token exchange 换取"该用户 + 该工具 + 该有效期"的受限 token;如果下游只支持 API Key,则应在网关持有 Key,并在审计中记录"以网关身份代用户执行",同时用租户维度限制 Key 的可用范围。绝不要把长期 API Key 下发到 Agent 配置文件里。
4.3 网关鉴权 vs 服务内鉴权
| 落点 | 优点 | 缺点 | 适用 |
|---|---|---|---|
| 网关统一鉴权 | 策略集中、接入统一、易做限流 | 服务间直连绕过网关即失效 | 有强网关的单体/少集群 |
| 服务内自鉴权 | 无单点、纵深防御 | 策略分散、升级成本高 | 多集群、零信任要求高 |
| 混合(网关 + 服务内关键路径二次校验) | 兼顾效率与安全 | 实现复杂度最高 | 有写副作用的工具必须二次校验 |
对 Agent 工具调用,建议采用混合模式:网关做 token 校验与基础策略,任何有写副作用的工具在执行前再校验一次"该主体对该资源是否有权限"。因为 Agent 会把用户输入变成工具参数,参数层面的越权风险比普通接口更高。
五、缺口 2:多租户——一次调用不能看见别人的世界
5.1 租户上下文的传播链
租户上下文来源通常是身份凭证中的租户声明(不信任裸 Header),建立后需要穿越:HTTP 线程 → 线程池/@Async → 消息生产与消费 → 出站连接(数据库、缓存、向量库)。
Java 侧的典型陷阱是上下文在跳点丢失。ThreadLocal 方案要注意 try/finally 清理与线程池复用污染;虚拟线程场景下 ThreadLocal 数量大时的内存开销与传播语义也需验证;Java 21 起以预览形式出现的 ScopedValue 提供了更安全的不可变上下文方案,但其在不同 JDK 版本中的状态有变化,以所用 JDK 文档为准。@Async、响应式链路、消息消费者必须显式传递上下文,不能假设"自动继承"。
5.2 隔离维度清单
隔离不是只给数据库加一个 tenant_id 就结束,需要逐项盘点:
- 数据层:行级
tenant_id、Schema 隔离或实例隔离 - 缓存:key 前缀或命名空间是否含租户维度
- 向量库:collection / namespace / partition 是否按租户切分,检索结果是否强制带租户过滤
- 工具授权:租户可调用的工具白名单与参数约束
- 文件与对象存储:路径前缀与访问策略
- 日志与审计:不同租户管理员的可见范围
向量库这一项最容易被忽略:检索类工具的泄漏往往不是"查到了别人的数据",而是"向量检索的召回结果没有租户过滤条件"。具体组件的 namespace/ACL 能力因产品而异,务必按所用版本的官方文档核验,不要默认它有隔离能力。
5.3 隔离级别的取舍
| 方案 | 隔离强度 | 成本 | 运维复杂度 | 适用 |
|---|---|---|---|---|
行级 tenant_id + 查询强制过滤 | 中(依赖代码正确性) | 低 | 低 | 中小租户、低敏感数据 |
| Schema 隔离 | 较高 | 中 | 中 | 中大型租户、合规要求中等 |
| 独立实例/独立部署 | 高 | 高 | 高 | 金融、医疗等强合规租户 |
实现骨架上,行级方案的关键是把过滤条件做成不可绕过的默认行为,而不是靠每个 DAO 自觉加条件:
/**
* 思路示意:在数据访问层拦截器中注入租户过滤条件。
* MyBatis 拦截器 / JPA Hibernate Filter / Spring Data 规格均可实现,
* 以所用 ORM 版本能力为准。核心原则:不允许业务代码显式关闭该过滤。
*/
public class TenantStatementInterceptor /* extends 拦截器基类 */ {
// 1. 从 TenantContext 取得 tenantId,为空则抛异常拒绝执行
// 2. 对查询类语句自动追加 tenant_id = ? 条件,参数绑定 tenantId
// 3. 对写入类语句强制写入 tenant_id 字段
// 4. 提供仅限系统任务使用的受限旁路,旁路必须打审计标记
}
一个可执行的验收标准:在集成测试中构造"租户 A 的上下文 + 租户 B 的资源 ID",断言一律返回 404 或 403,且审计中留下越权尝试记录。 如果做不到这一条,多租户隔离就只是字段设计,不是安全边界。
六、缺口 3:审计与合规——出事之后,拿什么自证
Agent 调用的审计要求比普通接口更高,因为需要回答两个额外问题:“模型依据什么做出了这个动作"和"这个动作影响了谁”。
6.1 审计事件最小字段集
| 字段 | 用途 | 敏感性 | 脱敏策略 |
|---|---|---|---|
| trace_id / span_id | 关联全链路日志与 APM | 低 | 不脱敏 |
| caller_subject / client_id | 定位调用方 | 中 | 内部可见 |
| tenant_id | 归属与隔离 | 中 | 不脱敏 |
| tool_name / tool_version | 定位被调用能力 | 低 | 不脱敏 |
| args_digest(参数哈希) | 证明调用内容,避免明文留存 | 高 | 存哈希,必要时加密留存原文 |
| result_status / error_code | 判定结果 | 低 | 不脱敏 |
| usage(token 数、时长) | 计费对账 | 低 | 不脱敏 |
| decision_basis(工具选择/参数来源摘要) | 复现决策依据 | 高 | 按策略截断或哈希 |
| policy_decision(授权判定结果) | 证明已做权限检查 | 低 | 不脱敏 |
提示词与模型输出是否留存、留存多久、谁有权查阅,属于合规策略问题,必须按所在行业规范与公司数据制度确定,本文不替代合规判断。工程上应做到三件事:留存策略可配置、访问有审计、导出有审批。
6.2 采集方式取舍
- AOP 切面:侵入小、覆盖统一,适合工具调用这类"形状一致"的入口;缺点是参数语义提取有限,复杂场景需要业务补充。
- 显式埋点:表达力强,能记录决策依据;缺点是依赖开发者自觉。
- 网关记录:覆盖所有调用,包括被拒绝的请求;缺点是看不到执行细节。
建议组合:网关记录"是否到达",切面记录"调用了什么",业务在关键决策点显式补充"为什么"。
6.3 存储与"审计不丢"
审计写入不能成为主链路的单点,也不能因为异步而丢失。常见做法是 Outbox:业务事务内写业务表 + 审计事件表,事务提交后异步投递到审计服务或消息系统。这一步与幂等设计共享同一套表结构(见第八节),可以合并实现。
/**
* 示意:业务事务内同步落审计事件(Outbox),异步投递。
* 结构基于 Spring 通用事务与 AOP 能力,不依赖特定 AI 框架 API。
*/
@Aspect
@Component
@RequiredArgsConstructor
public class ToolAuditAspect {
private final AuditOutboxRepository outbox;
@Around("@annotation(toolCall)") // 拦截自定义工具调用注解
public Object record(ProceedingJoinPoint pjp, ToolCall toolCall) throws Throwable {
long start = System.nanoTime();
AuditEvent event = AuditEvent.builder()
.traceId(Tracing.currentTraceId())
.caller(CallerContext.current().subject())
.tenantId(CallerContext.current().tenantId())
.tool(toolCall.name())
.argsDigest(Digests.sha256(Jsons.canonical(pjp.getArgs())))
.build();
try {
Object result = pjp.proceed();
event.success(Elapsed.millisSince(start));
return result;
} catch (Throwable t) {
event.failure(t.getClass().getSimpleName(), Elapsed.millisSince(start));
throw t;
} finally {
outbox.append(event); // 与业务同事务写入,保证不丢
}
}
}
可观测性不是可选项。有团队在一次微服务排障中,七八个人对着各自日志核对时间点近两小时,最终定位到是某个下游服务数据库连接池耗尽 [6]。Agent 调用链路比这更长、更不确定,没有 trace_id 贯穿的审计与 APM,故障复盘基本无法完成。实践上可采用 Java Agent 方式接入 APM(如 SkyWalking 一类工具,Java 生态覆盖较全、接入成本低 [6]),并把 tenant_id、tool_name 作为低基数标签打到指标上。
七、缺口 4:配额与计费——模型调用是有成本的读写
7.1 计量维度
只统计调用次数是不够的。至少要计量:输入/输出 token 数、工具调用次数、模型档位(不同档位单价差异大)、耗时、重试次数。重试与 Agent 多轮循环是成本放大器:一次用户请求可能触发 N 轮模型调用与 M 次工具调用,如果只在最外层计一次,成本归属会严重失真。
7.2 归属与记账
建议采用租户 / 应用 / 用户三级归属:租户用于账单结算,应用用于预算控制,用户用于行为分析与滥用检测。数据流是:
调用点采集用量 → 发出计量事件 → 聚合(分钟/小时级)→ 配额检查与账单生成 → 超限处置。
用量数据的字段名与统计口径各家模型/网关不同,重试与流式响应下的统计规则也未必一致,必须以所用厂商文档为准,不要凭经验假设"返回了 token 数就一定计了这些费"。稳妥做法是以厂商账单为准做月度对账,系统内计量用于实时控制而非最终结算。
7.3 控制手段
| 策略 | 优点 | 缺点 | 适用 |
|---|---|---|---|
| 预扣(先扣额度再调用) | 成本上界可控 | 需处理回滚与释放 | 内部结算、强预算场景 |
| 后付(先调用后记账) | 实现简单、无回滚 | 极端情况会超支 | 试点期、内部团队 |
| 硬限(超限直接拒绝) | 边界清晰 | 影响体验 | 生产必须有 |
| 软限(超限降级到低价模型/降频) | 体验平滑 | 实现复杂 | 面向员工的自助场景 |
推荐组合:软限 + 硬限双层。达到软限阈值时告警并切换到低价模型档位或降频,达到硬限时拒绝并返回明确的配额类错误码(见第九节)。
7.4 骨架示意
/**
* 示意:在调用装饰器中采集用量并做预算拦截。
* 用量字段以所用模型/网关返回的实际元数据为准。
*/
public class MeteredModelClient implements ModelClient {
private final ModelClient delegate;
private final UsageMeter meter;
private final BudgetGuard guard;
@Override
public ModelResponse call(ModelRequest request) {
CallerContext caller = CallerContext.current();
guard.assertBudget(caller); // 预算硬检查
ModelResponse resp = delegate.call(request);
meter.record(UsageEvent.builder()
.tenant(caller.tenantId())
.app(caller.clientId())
.user(caller.subject())
.model(resp.modelId())
.inputTokens(resp.usage().inputTokens())
.outputTokens(resp.usage().outputTokens())
.build());
return resp;
}
}
流式响应下计量时点要特别处理:以最终累计用量为准,不要按每个 chunk 累加计费,否则极易重复计数。计费数据的写入同样走 Outbox,保证与审计同一可靠性标准。
八、缺口 5:幂等语义——Agent 重试不能等于重复扣款
8.1 先给操作分类
| 操作类型 | 例子 | 天然幂等 | 策略 |
|---|---|---|---|
| 只读检索 | 知识库检索、查询工单 | 是 | 可自由重试,注意结果缓存时效 |
| 生成类(弱副作用) | 生成摘要、翻译 | 近似幂等(结果可能不同) | 以幂等键去重,允许重复但只记一次账 |
| 写操作类(强副作用) | 创建工单、发通知、扣减额度 | 否 | 必须幂等键 + 状态机 + 补偿 |
8.2 幂等键设计
优先级是:协议/客户端提供的请求标识 > 服务端派生键。派生键的常见构造是 tenant + caller + tool + payload_digest。注意 payload digest 必须做规范化序列化(字段排序、去除易变字段如时间戳),否则同样的业务请求会产生不同的键,去重失效。
MCP 请求层面存在请求标识,但"重复调用是否产生重复副作用"没有协议约定,因此键的有效性必须由工具实现方保证,不能指望协议层替你去重。
8.3 实现取舍
- 数据库唯一约束:最可靠、可审计、天然支持状态机;高并发下有锁竞争,但工具调用的 QPS 通常远低于普通接口,可接受。
- Redis SETNX / 去重表:快,适合高并发短周期去重;缺点是持久性与可追溯性弱于数据库,且 Redis 故障时的降级策略要提前定。
- 消息队列 + 消费端去重:适合异步链路;消费端必须做唯一标识校验或唯一索引,这在实践中是标准做法 [9]。Redis Stream 支持消费者组、ACK 与 Pending-List,可用于至少一次投递语义 [7],但"至少一次"本身就意味着消费端必须幂等 [8]。
8.4 状态机与不确定态
超时是最难处理的情形:调用超时时结果未知,此时不能盲目重试写操作。正确做法是进入"不确定"状态,先查询执行结果(若工具支持查询),再决定补偿、重试或人工介入。
-- 示意表结构:幂等记录与执行状态
CREATE TABLE tool_invocation (
idempotency_key VARCHAR(128) NOT NULL PRIMARY KEY,
tenant_id VARCHAR(64) NOT NULL,
caller VARCHAR(128) NOT NULL,
tool_name VARCHAR(128) NOT NULL,
payload_digest VARCHAR(64) NOT NULL,
status VARCHAR(16) NOT NULL, -- ACCEPTED / RUNNING / SUCCEEDED / FAILED / UNKNOWN
result_ref VARCHAR(256),
error_code VARCHAR(64),
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
UNIQUE KEY uk_tenant_tool_digest (tenant_id, tool_name, payload_digest)
);
Agent 循环与幂等的关系:Agent 的自动重试必须受幂等层约束。框架层的"失败自动重试"在只读检索上是合理的,在写操作上是危险的。建议按工具声明的幂等属性决定重试策略,而不是给整个 Agent 一个全局重试配置。
九、缺口 6:错误码语义与版本兼容——让调用方知道该重试还是该改代码
9.1 错误分层
一次 MCP 调用失败可能发生在四层,语义完全不同:
| 层级 | 示例类别 | 可重试 | 调用方动作 |
|---|---|---|---|
| 传输层 | 连接超时、断流、网络不可达 | 是(带退避) | 重试并上报连接质量 |
| 协议层 | 请求格式错误、能力不支持、版本不兼容 | 否 | 修正调用或升级客户端 |
| 工具实现层 | 下游超时、依赖不可用、限流 | 部分 | 按错误码判断,必要时降级 |
| 业务语义层 | 权限不足、参数非法、配额超限、冲突 | 否 | 提示用户或走人工流程 |
MCP 与 JSON-RPC 层面已有错误返回结构,但业务语义与"可重试性"没有统一约定,这正是需要自建的部分。
9.2 统一错误契约
建议基于 ProblemDetail 一类的结构化错误表达(RFC 7807 思路;Spring 各层支持范围随版本不同,MVC 与 WebFlux、客户端侧能力需查所用版本文档),核心字段四件套:稳定错误码 + 可重试标记 + 人类可读信息 + trace_id。
/**
* 示意:业务错误码枚举 + 全局异常映射。
* 错误码一旦发布即视为契约,只增不改,废弃需走公告期。
*/
public enum AiErrorCode {
AUTH_REQUIRED ("AIA-1001", false, "缺少或无效凭证"),
TENANT_MISMATCH ("AIA-1002", false, "租户上下文与资源不匹配"),
QUOTA_EXCEEDED ("AIA-2001", false, "配额已用尽"),
BUDGET_SOFT_LIMIT ("AIA-2002", true, "预算接近上限,已降级处理"),
IDEMPOTENCY_CONFLICT("AIA-3001", false, "相同幂等键存在不同请求内容"),
TOOL_TIMEOUT ("AIA-4001", true, "工具执行超时"),
TOOL_UNAVAILABLE ("AIA-4002", true, "工具暂不可用"),
INVALID_ARGUMENT ("AIA-5001", false, "参数非法"),
INTERNAL_ERROR ("AIA-9000", true, "内部错误,可重试");
private final String code;
private final boolean retryable;
private final String message;
// 构造器与 getter 省略
}
/**
* 异常 → ProblemDetail 映射的结构示意。
*/
// @RestControllerAdvice
// public class AiExceptionHandler {
// @ExceptionHandler(AiException.class)
// ProblemDetail handle(AiException e) {
// ProblemDetail p = ProblemDetail.forStatus(e.httpStatus());
// p.setProperty("code", e.errorCode().code());
// p.setProperty("retryable", e.errorCode().isRetryable());
// p.setProperty("traceId", Tracing.currentTraceId());
// p.setDetail(e.errorCode().message());
// return p;
// }
// }
三条硬规则:
- 禁止把上游模型的原始异常字符串直接抛给调用方。它既不稳定也可能是注入面,必须在网关处归一化。
- retryable 必须是契约的一部分,不能让调用方靠猜字符串决定重试。
- 错误码与重试策略联动:只有
retryable=true且属于传输/工具层的错误才允许自动重试,且必须有指数退避与最大次数限制。
9.3 版本兼容策略
协议层的版本与能力协商解决了"能不能通信",但工具层面的演进仍需自己治理:
- 能力声明:工具元数据中标明版本、参数 schema 版本、支持的语义。
- 只增不改:字段只增不删不改义;删除与改义走新版本字段。
- 废弃窗口:旧字段保留至少一个发布周期,期间打废弃告警指标,确认无调用方后再移除。
- 契约测试:核心工具的请求/响应结构纳入 CI 契约测试,防止"顺手改个字段名"打断 Agent。
反模式是"工具随便改,反正调用方是模型"。模型对参数 schema 的适应能力并不能替代契约治理——一旦工具返回结构变化导致解析失败,故障会被 Agent 循环放大。
十、"三驾马车"甄别:事件驱动、虚拟线程、Agent 内嵌,哪些是真需求
社区把事件驱动、虚拟线程、Agent 内嵌并称为后端架构的"三驾马车" [3],也有人明确提出质疑:哪些是真需求 [2]。甄别标准只有一条:当前瓶颈是否真实存在,而不是"架构是否够新"。
| 能力 | 解决的真实瓶颈 | 引入成本 | 新增风险 | 该引入的信号 | 不该用的场景 |
|---|---|---|---|---|---|
| 虚拟线程 | 高并发 IO 等待导致线程池耗尽 | 低(开关级) | 上下文传播、pinning、ThreadLocal 开销 | 线程池排队、IO 等待占比高、调用链为阻塞式 | CPU 密集推理、已有成熟响应式栈、无并发瓶颈 |
| 事件驱动 | 削峰、跨服务解耦、审计/计量天然异步 | 中 | 重复消费、顺序性、排障复杂度上升 | 流量峰谷明显、多下游订阅同一事件 | 只为"架构好看"、低流量、强一致要求 |
| Agent 内嵌 | 多步工具编排需在鉴权/事务/审计边界内 | 高 | 成本放大、不可预测、责任边界模糊 | 确实需要多步规划与工具组合 | 单次工具调用即可完成的任务 |
虚拟线程是三项中性价比最高的一项,但它不是免费的:MDC、ThreadLocal、事务上下文、租户上下文的传播语义需要验证,某些阻塞场景可能触发 pinning,具体支持开关与限制以所用 Java 与 Spring Boot 版本文档为准。它能缓解 IO 等待造成的线程压力,不会让 CPU 密集的推理变快,也不会自动解决上下文传播问题。
事件驱动在 AI 场景中的真实价值主要是两处:审计与计量的异步落库、长耗时任务的削峰与解耦。但每引入一条消息链路,就必须回答"重复消费怎么办"——这直接回到幂等问题。Redis Stream 一类方案提供了 ACK 与消费者组机制 [7],Kafka 场景下消费端做唯一标识校验是常见实践 [9],但消息可靠性永远是"至少一次 + 消费端幂等"的组合,不是 MQ 单方面保证的 [8]。如果引入 MQ 只是为了"异步化看起来更现代",那么它带来的重复消费与排障成本会超过收益。
Agent 内嵌是最需要冷静的一项。真需求信号是:任务确实需要多步规划、工具选择与结果反馈,且必须在企业的鉴权、审计、事务边界内运行。伪需求信号是:一次工具调用就能完成的任务被强行 Agent 化。后者的代价是三重放大——调用轮数放大成本(第七节)、循环重试放大副作用(第八节)、中间步骤放大不可预测性(第九节)。
推演示例(非真实案例):一个"查询工单状态"的简单接口被改造成 Agent 任务后,一次请求平均触发 3 轮模型调用与 2 次工具调用,成本上升约数倍,响应时间方差显著增大,而用户得到的仍是同一个答案。凡是能用一次确定性工具调用解决的,就不要用 Agent。
组合风险尤其要注意:Agent 循环 × 事件驱动 = 重试风暴(消息重投触发新一轮循环);Agent 循环 × 虚拟线程 = 上下文与配额失控(大量并发循环同时消耗预算,且上下文传播一旦出错就是批量串号)。任何一项引入前,先确认第七、八节的配额与幂等机制已经就位。

十一、落地路线图:从试点到规模化
11.1 分阶段安排
| 阶段 | 交付物 | 退出标准 | 主要负责角色 |
|---|---|---|---|
| 阶段 0(试点前) | 鉴权接入、租户上下文、最小审计 | 身份可追溯到人/应用;跨租户用例全部拒绝;每次调用有审计记录 | 架构 + 安全 |
| 阶段 1(小流量) | 幂等层、统一错误契约 | 写操作具备幂等键与状态机;错误码表发布并被调用方采用 | 后端 + 平台 |
| 阶段 2(多团队) | 配额计费、审计留存合规 | 账单可对账(误差在约定阈值内);留存策略经合规确认 | 平台 + 财务 + 合规 |
| 阶段 3(规模化) | 版本治理、契约测试、Agent 引入评估 | 核心工具契约测试入 CI;Agent 引入有成本与风险评估记录 | 平台 + 业务 |
顺序不可颠倒的原因:没有鉴权与隔离,审计记录里连"谁"都不可信;没有幂等,配额计量会被重试污染;没有错误契约,调用方的重试策略无从谈起。
11.2 上线前自检清单
## AI 调用接入上线检查清单
### 身份与隔离
- [ ] 每次调用可追溯到具体用户或服务主体,服务账号不得代表全部用户
- [ ] 下游凭证不下发到 Agent 配置,出站调用有凭证注入点
- [ ] 租户上下文来自可信凭证声明,非裸 Header
- [ ] 向量库/缓存/文件存储均已按租户隔离或过滤
- [ ] "租户 A 上下文 + 租户 B 资源"用例返回 403/404 并留下审计记录
### 审计与合规
- [ ] 每次工具调用有审计事件,含 trace_id、主体、租户、参数摘要、结果
- [ ] 审计与业务同事务写入(Outbox),异步投递有失败告警
- [ ] 提示词与输出的留存周期、访问权限经合规确认
### 成本与幂等
- [ ] 用量按租户/应用/用户三级归属,重试与多轮循环单独计数
- [ ] 软限(降级/降频)与硬限(拒绝)双层策略已配置
- [ ] 写操作工具具备幂等键、唯一约束与状态机
- [ ] 超时进入"不确定"态,有查询补偿或人工介入路径
- [ ] Agent 自动重试受幂等层约束,写操作不做无脑重试
### 错误契约与演进
- [ ] 错误返回含稳定错误码、retryable、trace_id
- [ ] 上游模型原始异常不出网关
- [ ] 工具字段变更走"只增不改 + 废弃窗口"
- [ ] 核心工具契约测试纳入 CI

十二、结语:协议给骨架,系统给血肉
MCP 与 Spring AI 把"调用与工具发现"这一层标准化了,这是实实在在的进步。但企业级的控制面——谁在调用(鉴权)、能看见什么(多租户)、做过什么(审计)、花了多少钱(配额计费)、重复调用会发生什么(幂等)、失败了该怎么办(错误码与版本兼容)——不会随协议自动获得。这六件事没有一件是新问题,Java 后端在传统业务里都解决过一遍;它们的新颖之处在于,AI 调用的不确定性、成本非线性与副作用复杂度,让这些老问题的难度上了一个台阶。
社区讨论密度提示我们:AI 原生架构的三个变量正在被大量讨论 [1][2][3][4][5],但讨论密度不等于真实需求。虚拟线程大概率值得上,事件驱动要按场景上,Agent 内嵌要谨慎上。判断标准永远是瓶颈是否真实存在,而不是概念是否完整。
本周就能做的一件事:盘点现有 AI 调用的身份透传链路,回答三个问题——现在的调用以谁的身份发出?下游凭证存在哪里?出问题时能否从日志中还原"谁、何时、调了什么"。如果这三个问题答不清楚,先做鉴权和审计,其余五项都不急。
参考资料
[1] 《2026 后端 AI 集成实战:Spring AI 2.0、MCP 协议与 Agent 内嵌的三条落地路径》,CSDN,https://blog.csdn.net/m0_74899094/article/details/166905088
[2] 《AI 原生后端架构的"三驾马车"落地实况:事件驱动、虚拟线程、Agent 内嵌,哪些是真需求?》,CSDN,https://blog.csdn.net/m0_74899094/article/details/166945887
[3] 《2026 后端架构进入 AI 原生阶段:事件驱动 + 虚拟线程 + Agent 内嵌三驾马车怎么落地》,CSDN,https://blog.csdn.net/m0_74899094/article/details/166991079
[4] 《2026 年后端开发进化:告别 CRUD 内卷,拥抱 AI 原生架构与服务编排新时代》,掘金,https://juejin.cn/post/7691917465479446591
[5] 《DeepSeek 突然开源推理框架!AI 圈又炸了,后端开发这次真的要变天了?》,掘金,https://juejin.cn/post/7699307133640687659
[6] 《Skywalking 9.4 实战:SpringBoot 微服务链路追踪与 APM 落地指南》,CSDN,https://blog.csdn.net/weixin_35829279/article/details/167524543
[7] 《Redis 消息队列》,CSDN,https://blog.csdn.net/2301_80821045/article/details/159586837
[8] 《Redis 与消息队列面试核心考点:从原理到实战的深度拆解》,CSDN,https://blog.csdn.net/weixin_31528001/article/details/167903919
[9] 《Spring Boot + Kafka + Redis + OAuth2:互联网大厂 Java 面试实录》,CSDN,https://blog.csdn.net/Cdasdas/article/details/164185970
[10] 《AI Infrastructure Digest 2026-10-09 · agents-radar #3696》,GitHub,https://github.com/duanyytop/agents-radar/issues/3696
[11] 《Spring Boot 微服务架构设计与实战指南》(Resilience4j 限流实践部分),CSDN,https://blog.csdn.net/weixin_33585822/article/details/167854332
说明:上述 [1][2][3] 三篇为同一作者系列文章,属同源材料,文中已按"社区讨论密度"而非"热度"使用;其中关于 MCP"未标准化"的判断与规范现状可能存在出入,正文第二节已按"协议已覆盖部分 / 实现自决部分"重新分层表述。MCP 规范原文、Spring AI 与 Spring Boot/Spring Security 各版本支持范围、模型厂商用量统计口径等官方文档链接未包含在本次采集资料中,故未列入本节;相关结论均以正文中的"以所用版本官方文档为准"限定语覆盖。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/m0_74899094/article/details/169253812




