前言

欢迎来到《Spring AI 零基础到实战》的第 21 节！

在前面两节的实战中，我们通过配置和一系列诸如 @McpTool、@McpSampling 的注解，见证了大模型与Spring Boot 应用跨越网络完成的“双向通信”。

但作为一名有追求的后端开发者，如果只停留在“会配 YAML、会写注解”的框架搬运工阶段，在真实的工程环境中是十分危险的。 请试想一个生产危机：当网络波动导致 MCP 连接异常、或者异构语言的 Server 返回了非标准的 JSON-RPC 数据包导致系统抛出反序列化异常时，如果我们对底层的通信流转机制一无所知，排查过程将如同在黑夜中盲人摸象。依赖乱改配置去试错，无异于在生产环境埋下隐患。

今天，我们将直接切入 Spring AI MCP 的源码脉络。从源码级别，透视一个普通的 Java 方法调用，是如何被包装成标准的 JSON-RPC 协议，并跨越网络流精准触发对端逻辑的。

本节课的源码剖析，基于上一节课我们配置的 streamable 模式。Spring AI 同样支持 SSE 以及微服务架构下的 Stateless (无状态) 模式，它们的底层调度器与责任链设计高度一致，理解了 streamable，其他模式即可触类旁通。

本节章节目标

1. 源码透视：深入剖析 Server 端响应式路由机制，看懂 WebFlux 是如何充当流量分发中枢的。
2. 握手解密：穿透 Client 启动源码，解析大模型与外部系统“交换外交国书”（Initialize）的底层细节。
3. 闭环追踪：从客户端的一行 callTool 出发，完整追踪 JSON-RPC 数据包在服务端的逆向拆解与反射调用。

MCP 源码流转全景图

在深入代码之前，我们先来看看下面这张图，描述了 Spring AI 底层源码是如何接管并流转 MCP 数据包的：

接下来，我们将分三个阶段，带你领略这段顶级框架的源码之美。

Server 端源码解析 —— 响应式分配中枢的诞生

在传统的 Web 开发中，为了处理各种类型的请求，我们往往会堆砌大量带有 @RequestMapping 的 Controller 和冗长的 if-else 分支。 但深入 MCP Server 的底层源码，你会发现它借助 WebFlux 响应式编程，构建了一个极其干净的流量分发中枢。

第一步：初始化底层传输通道

当我们在 YAML 中声明 protocol: streamable 时，Spring Boot 的自动装配机制会构建一个基于响应式长连接的传输提供者。

// 源码位置：org.springframework.ai.mcp.server.autoconfigure.McpServerStreamableHttpWebFluxAutoConfiguration
@Bean
public WebFluxStreamableServerTransportProvider webFluxStreamableServerTransportProvider(...){
// 1. 构建 WebFlux Streamable 服务端传输的底层 Bean
return WebFluxStreamableServerTransportProvider.builder()...build();
}

第二步：RouterFunction —— 统一的流量入口

在 WebFluxStreamableServerTransportProvider 的内部构造中，它放弃了传统的 Controller 映射，转而使用函数式路由（RouterFunction）接管特定的端点。

// 源码位置：io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider
privateWebFluxStreamableServerTransportProvider(....){
// 1. 链式路由注册，统一接管端点的流量
// 无论是 GET, POST 还是 DELETE，只要打在配置的 MCP Endpoint 上，统统由对应的handle方法拦截。
this.routerFunction = RouterFunctions.route()
            .GET(this.mcpEndpoint, this::handleGet)
            .POST(this.mcpEndpoint, this::handlePost)
            .DELETE(this.mcpEndpoint, this::handleDelete)
            .build();
}

【底层细节剖析】： this::handleXxx就是整个 MCP 协议处理的咽喉要道。客户端发来的任何 JSON-RPC 请求体，都会首先进入这个方法进行基础的反序列化与类型鉴别。

第三步：门面模式与策略分发

基础设施建立后，核心业务逻辑交由服务层处理。Spring AI 在这里采用了经典的门面模式（Facade Pattern）。对外暴露的是 McpSyncServer（同步外壳），而内部包裹的其实是一个高并发的 McpAsyncServer（异步核心）。

让我们看看它是如何优雅地处理繁杂的协议命令的：

// 源码位置：io.modelcontextprotocol.server.McpAsyncServer#prepareRequestHandlers
private Map<String, McpRequestHandler<?>> prepareRequestHandlers() {
// 1. 准备一个注册表，装载所有协议定义的处理能力
    Map<String, McpRequestHandler<?>> requestHandlers = new HashMap<>();

// 2. 如果当前服务端声明了支持 Tools（工具）能力
if (this.serverCapabilities.tools() != null) {
// 3. 将协议的方法名与具体的执行逻辑绑定
        requestHandlers.put("tools/list", this.toolsListRequestHandler());
        requestHandlers.put("tools/call", this.toolsCallRequestHandler());
    }
// ...同样处理 Resources, Prompts 等
return requestHandlers;
}

【底层细节剖析】： 这里展现了高度解耦的策略模式。框架没有使用臃肿的逻辑分支来判断当前请求是查表还是调用，而是将 JSON-RPC 的 method 字段（如 tools/call）作为 Key，直接映射到对应的处理器上。这种设计保证了 MCP 协议未来横向扩展时，核心调度逻辑无需做任何侵入式修改。

阶段二：Client 源码解析 —— 跨域外交的“递交国书”

视线回到客户端。当我们在 YAML 中配置了远端的 Server 节点后，Spring Boot 在启动时是如何自动寻址并建立双向通道的？

第一步：按需装配客户端集合

// 源码位置：org.springframework.ai.mcp.client.common.autoconfigure.McpClientAutoConfiguration
public List<McpSyncClient> mcpSyncClients(...){
// 1. 遍历配置文件中声明的所有远端连接
for(NamedClientMcpTransport namedTransport : namedTransports) {
// 2. 基于传输层配置构建 Client 规范约束
        McpClient.SyncSpec spec = McpClient.sync(namedTransport.transport()).clientInfo(clientInfo);
        McpSyncClient client = spec.build();

// 3. 核心节点：触发连接握手初始化！
        client.initialize(); 
        mcpSyncClients.add(client);
    }
return mcpSyncClients;
}

第二步：执行 Initialize 握手协定

进入 client.initialize() 的底层链路，会调用到 LifecycleInitializer。它在建立实际业务通信前，完成了一项类似于“交换外交国书”的标准动作

// 源码位置：io.modelcontextprotocol.client.LifecycleInitializer
private Mono<McpSchema.InitializeResult> doInitialize(...) {
// 1. 构建“外交国书”：告诉 Server，我是谁，我支持哪些 MCP 版本，我具备哪些客户端能力（如支持进度条、支持回调等）
    McpSchema.InitializeRequest initializeRequest = 
new McpSchema.InitializeRequest(latestVersion, this.clientCapabilities, this.clientInfo);

// 2. 开启底层的长连接会话，向网络另一端发射 "initialize" 方法请求！
    Mono<McpSchema.InitializeResult> result = 
        mcpClientSession.sendRequest("initialize", initializeRequest, McpAsyncClient.INITIALIZE_RESULT_TYPE_REF);
}

【底层细节剖析】： 当这封 initialize 数据包抵达 Server 时，前面的路由函数 handlePost 会拦截它，并调用 this.sessionFactory.startSession(initializeRequest)。Server 验证通过后，将该 Session 加入活跃会话池（this.sessions.put(...)）。

至此，基于 MCP 标准的双向通信桥梁宣告建立完成。

Tool 调用的闭环追踪 —— 从请求到执行

基建与连接均已就绪。最后，我们完整追踪一次 @McpTool 从发出请求到物理执行的闭环。

第一步：客户端的数据封装

在业务代码中，我们通过 Client 发起了一次调用：

McpSchema.CallToolRequest toolRequest = McpSchema.CallToolRequest.builder()
         .name("tool")
         .arguments(Map.of("input", "test input"))
         .build();
mcpClient.callTool(toolRequest);

它的底层调用实际上被委托给了 McpAsyncClient 进行协议格式化：

// 源码位置：io.modelcontextprotocol.client.McpAsyncClient (源码简化版)
public Mono<McpSchema.CallToolResult> callTool(McpSchema.CallToolRequest callToolRequest) {
// 1. 将标准的 Request 对象，封装为 JSON-RPC 请求，并打上 "tools/call" 的方法路由标签
returnthis.initializer.withInitialization("calling tool", 
        (init) -> init.mcpSession().sendRequest("tools/call", callToolRequest, CALL_TOOL_RESULT_TYPE_REF));
}

第二步：服务端精准提取与反射执行

数据包到达服务端的 handlePost 后，被分拣至 responseStream 进行具体的业务处理。

// 源码位置：io.modelcontextprotocol.server.McpAsyncServer
public Mono<Void> responseStream(McpSchema.JSONRPCRequest jsonrpcRequest){

// 1. 核心调度：通过客户端传来的 "tools/call" 标识，从注册表中精准提取对应的处理器
    McpRequestHandler<?> requestHandler = this.requestHandlers.get(jsonrpcRequest.method());

// 2. 执行业务逻辑
// 内部通过参数解析与反射机制，触发开发者编写的、带有 @McpTool 注解的物理方法
return requestHandler.handle(jsonrpcRequest);
}

【流转结果】：requestHandler.handle() 执行完毕后，产生的返回值会被重新包装进 JSON-RPC 的 Result 结构中，沿着原路返回至客户端。最终，在客户端的线程上下文中，我们便可以成功拿到结构化结果。

总结

在本节课中，我们不再局限于充当框架的被动使用者，而是将视线深入到了 Spring AI MCP 的底层执行流转中。

通过剖析源码，我们看到了框架设计的严谨与克制：

• 它利用 WebFlux 打造了高性能的异步调度引擎，从容应对底层长连接的数据分发。
• 它拒绝了面条式的逻辑判断，采用 HashMap 策略模式 将庞杂的 JSON-RPC 协议进行了解耦。
• 它通过 LifecycleInitializer 实现了规范、有序的生命周期与会话状态管理。

当我们看懂了这些底层代码的呼应与流转，所谓的“黑盒”便不再神秘。未来无论面对网络断层、协议不配还是复杂的排错场景，我们都能在架构层面拥有十足的掌控感。

下节预告

【第 22 节：Spring AI 个人知识库实战（一）】。

经过连续 21 节课程的技术拆解，Spring AI 的核心武器库（ChatClient 对话机制、RAG 向量检索、Advisors 记忆网络、Function Calling 以及 MCP 协议规范）我们已经尽数掌握。 但技术如果不落地到真实业务，永远只是一堆零散的 Demo。

接下来，我们将进入项目实战阶段。 我们将整合上述所有的技术碎片，从零开始，开发一个“AI 个人知识库”！