读Spring AI源码的方法——不是硬啃，是带着问题去翻

很多人觉得读源码是一件很"高大上"的事。我以前也这么觉得------看到别人说"我读过Spring源码"，就觉得这个人好厉害。

但后来我发现，读源码跟"厉害"没什么关系，它就是一个工程技能。就像debug一样，有人擅长有人不擅长，但本质上是方法论的问题。

这篇文章不是教你读Spring AI源码------我没那个本事通读。而是分享我的方法：怎么"带着问题"去翻源码，用最小的成本解决实际问题。

为什么要读源码？

先说个具体的事。

前阵子用Spring AI 1.0的Function Calling，碰到一个诡异的问题：同一个function，有时能正常调用，有时大模型返回的参数JSON是空的，导致function调用失败。

查了半天文档没找到原因。Stack Overflow上有人问了类似的问题，但没有答案。Spring AI的GitHub Issues里翻到了一两个相关的，但都标记为"won't fix"或"duplicate"。

这种时候，只剩一条路------翻源码。

我的方法：问题驱动的源码阅读

我不会坐下来从头到尾读一个框架的源码。那是文档作者干的事，不是开发者干的事。我读源码的方式是"外科手术式"的------只切我要看的那一刀，看完就走。

Step 1：把问题缩小到一行代码

首先得搞清楚：问题出在哪？

我的问题是"Function Calling的参数有时为空"。那参数是在哪一步生成的？

bash 复制代码

用户消息 → ChatClient → 构建请求 → 发给大模型API → 大模型返回 → 解析响应 → 提取function参数 → 调用function

参数为空，要么是大模型返回的JSON里就没有参数，要么是解析的时候丢了。

Step 2：找到入口

Spring AI的代码结构其实挺清晰的。我先用IDEA的全局搜索，找Function Calling相关的类：

javascript 复制代码

搜索关键词："FunctionCallback"（这是Function Calling的核心接口）

找到核心类：FunctionCallback、FunctionCallbackContext、OpenAiChatModel。

Step 3：跟着调用链走

在OpenAiChatModel里找到处理大模型响应的代码。这里是解析大模型返回的function call的地方：

java 复制代码

// OpenAiChatModel.java（简化版）
private Response<ChatResponse> internalCall(ChatRequest request, ...) {
    // 发请求给大模型
    var apiResponse = openAiApi.chatCompletion(request);
    
    // 处理响应
    var toolCalls = response.choices().get(0).message().toolCalls();
    
    if (toolCalls != null && !toolCalls.isEmpty()) {
        for (var toolCall : toolCalls) {
            // 关键：这里解析function参数
            var function = toolCall.function();
            var functionName = function.name();
            var argumentsJson = function.arguments();  // ← 问题可能在这里
            
            // 调用function
            var result = functionCallbackContext.execute(functionName, argumentsJson);
        }
    }
}

argumentsJson就是大模型返回的function参数JSON。我在这里打了个断点（在本地debug模式下），复现问题。

Step 4：断点调试

debug模式下复现问题后，发现：

ini 复制代码

正常情况下：
  argumentsJson = "{\"orderId\": \"DD20260720001\"}"

异常情况下：
  argumentsJson = ""   ← 空字符串！

大模型返回的arguments确实是空的。那问题出在大模型那边？不一定------可能是我们发给大模型的prompt/tool描述有问题，导致大模型"不知道"该传什么参数。

Step 5：往上看------请求是怎么构建的

回到构建请求的代码，看tool定义是怎么传给大模型的：

java 复制代码

// 构建发给大模型的tool定义
var tools = new ArrayList<Tool>();
for (var callback : functionCallbacks) {
    tools.add(Tool.builder()
        .function(Function.builder()
            .name(callback.getName())
            .description(callback.getDescription())
            .parameters(callback.getInputSchema())  // ← 参数schema
            .build())
        .build());
}

getInputSchema()返回的是function参数的JSON Schema。我打印了一下这个schema：

json 复制代码

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "description": "订单ID"
    }
  },
  "required": ["orderId"]
}

看起来没问题。但等等------getDescription()返回的是什么？

java 复制代码

// 我的function定义
@Bean
@Description("根据订单号查询订单状态")
public Function<OrderQuery, OrderInfo> queryOrder(OrderService service) {
    return query -> service.queryOrderInfo(query.orderNo());
}

public record OrderQuery(String orderNo) {}

注意到了吗？@Description注解说的是"订单号"，但OrderQueryrecord的字段名是orderNo。而schema里的参数名是orderNo，description是"订单ID"。

大模型看到的描述是："根据订单号查询订单状态"，参数名是orderNo，参数描述是"订单ID"。

这三个描述不一致------"订单号"、"订单ID"、orderNo。大模型可能在某些情况下搞混了，以为不需要传参数。

Step 6：验证假设

我把@Description改得更明确：

java 复制代码

@Bean
@Description("查询订单状态。传入orderNo参数（订单编号），返回订单的状态、物流和预计到达时间。")
public Function<OrderQuery, OrderInfo> queryOrder(OrderService service) {
    return query -> service.queryOrderInfo(query.orderNo());
}

改完后，function参数为空的问题消失了。

这个过程教会我什么

回头看，这个问题的根因其实很简单------description写得不够清楚。但如果不翻源码，我永远不知道大模型看到的是什么样的tool定义，只能靠猜。

读源码的核心价值不是"学会框架的实现"，而是"理解框架的行为"。 当框架的行为不符合预期时，源码是唯一能告诉你"为什么"的东西。

我读源码的几个原则

原则1：别从第一行开始读

有人打开源码项目，从main方法或者第一个类开始读，像读小说一样从头到尾。这是最差的方式。

框架源码不是小说，是工具。你不需要理解每一行代码，你只需要理解"和你的问题相关的那部分代码"。

带着问题进去，找到答案就出来。

原则2：善用IDEA的快捷键

读源码效率的高低，80%取决于你对IDEA快捷键的熟练度：

css 复制代码

Ctrl+B          跳转到定义（看这个方法/类在哪定义的）
Ctrl+Alt+B     跳转到实现（接口 → 实现类）
Ctrl+Shift+F   全局搜索（找某个关键词在哪些文件里出现）
Alt+F7          查看引用（看这个方法被谁调用了）
Ctrl+H          查看类继承结构

我读源码的典型流程：

全局搜索一个关键词（比如"toolCalls"）
找到处理这个关键词的类和方法
Ctrl+B跳到定义
Alt+F7看谁调用了它
顺着调用链往上或往下走

原则3：在关键位置打断点

光看代码有时候看不出问题------逻辑太复杂，或者有多层抽象。在关键位置打断点，跑一遍流程，看变量的实际值，比纯看代码高效十倍。

bash 复制代码

# Spring AI源码的debug技巧：
# 1. git clone Spring AI源码
git clone https://github.com/spring-projects/spring-ai.git

# 2. 本地编译安装
cd spring-ai && ./mvnw install -DskipTests

# 3. 你的项目里把Spring AI依赖改成SNAPSHOT版本
#    这样你就可以在源码里打断点了

原则4：看测试用例

好的开源项目，测试用例就是最好的文档。

Spring AI的测试用例在src/test/java目录下。如果你想理解一个功能怎么用，不要先看文档（文档可能过时），先看测试用例：

java 复制代码

// Spring AI源码里的测试用例
class FunctionCallbackTests {
    
    @Test
    void testFunctionCallWithArguments() {
        var callback = FunctionCallback.builder()
            .function("queryOrder", queryOrderFunction)
            .description("查询订单状态")
            .inputType(OrderQuery.class)
            .build();
        
        // 看测试怎么用的，你就怎么用
        var result = callback.call("{\"orderNo\": \"DD20260720001\"}");
        assertNotNull(result);
    }
}

测试用例是"官方的正确用法示例"，比任何第三方教程都靠谱。

原则5：看commit history

有时候你看一段代码觉得"为什么这么写"，看commit message可能就明白了：

bash 复制代码

# 看某个文件的修改历史
git log --oneline -- path/to/File.java

# 看某次修改的具体内容
git show <commit-hash>

Spring AI的commit message质量挺高的，经常会在message里解释"为什么这么改"。

我不建议的读源码方式

不建议1："我要把Spring源码从头到尾读一遍"

Spring框架的源码有上百万行代码。即使你一天读1000行，也要读好几年。而且大部分代码和你日常开发毫无关系。

读源码要功利一点。 哪个模块你现在在用、碰到了问题、想深入理解，就读哪个模块。其他的不管。

不建议2："我要搞懂每个设计模式"

有些源码分析文章喜欢讲"这里用了策略模式""这里用了观察者模式"。这些知识对你解决实际问题帮助不大。设计模式是手段不是目的，你不需要给每段代码贴一个模式标签。

不建议3：读别人的源码解读文章而不是源码本身

网上有很多"Spring源码深度解析"之类的文章。这些文章的问题在于------它们是别人的理解，不是你的。而且文章可能和当前版本对不上。

一手信息永远比二手信息可靠。 源码就在那，打开IDEA直接看。

最后

我见过很多开发者对读源码有一种"畏惧感"------觉得源码很高深、很难懂、需要很牛才能读。

这完全是误解。源码就是代码，和你每天写的代码一样，只是多了些抽象和设计。你不需要理解每一行，你只需要找到和你的问题相关的那几行。

下次遇到框架的诡异行为，别搜Stack Overflow了------打开源码看一眼。 你会发现答案往往就在那里，而且比任何博客文章都准确。