Spring AI Alibaba 项目源码学习（十）-Interceptor

本文分析了Spring AI Alibaba Agent Framework中的拦截器机制，包括ModelInterceptor和ToolInterceptor接口设计及其链式调用实现。Interceptor是所有拦截器的基接口，ModelInterceptor负责模型调用拦截（如修改请求、处理响应），ToolInterceptor则处理工具调用。InterceptorChain采用责任链模式，通

wasp520

374人浏览 · 2025-11-16 14:19:23

wasp520 · 2025-11-16 14:19:23 发布

Interceptor 机制分析

请关注微信公众号：阿呆-bot

概述

本文档分析 Spring AI Alibaba Agent Framework 中的 Interceptor（拦截器）机制，包括 ModelInterceptor 和 ToolInterceptor 的设计、实现原理、链式调用机制以及具体实现类。

入口类说明

Interceptor - 拦截器接口

Interceptor 是所有拦截器的基接口，定义了拦截器的基本能力。

关键代码：

public interface Interceptor {
	String getName();
}

ModelInterceptor - 模型调用拦截器

ModelInterceptor 用于拦截和修改模型调用请求和响应。

核心职责：

拦截模型调用请求
修改请求参数
处理响应结果
实现重试、降级等功能

关键代码：

public abstract class ModelInterceptor implements Interceptor {

	/**
	 * Wrap a model call with custom logic.
	 *
	 * Implementations can:
	 * - Modify the request before calling the handler
	 * - Call the handler multiple times (retry logic)
	 * - Modify the response after handler returns
	 * - Handle exceptions and provide fallbacks
	 *
	 * @param request The model request
	 * @param handler The next handler in the chain (or base handler)
	 * @return The model response
	 */
	public abstract ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler);

	/**
	 * Get tools provided by this interceptor.
	 * Interceptors can provide built-in tools that will be automatically added to the agent.
	 *
	 * @return List of tools provided by this interceptor, empty list by default
	 */
	public List<ToolCallback> getTools() {
		return Collections.emptyList();
	}
}

ToolInterceptor - 工具调用拦截器

ToolInterceptor 用于拦截和修改工具调用请求和响应。

核心职责：

拦截工具调用请求
修改工具参数
处理工具响应
实现重试、错误处理等功能

关键代码：

public abstract class ToolInterceptor implements Interceptor {

	/**
	 * Wrap a tool call with custom logic.
	 *
	 * Implementations can:
	 * - Modify the request before calling the handler
	 * - Call the handler multiple times (retry logic)
	 * - Modify the response after handler returns
	 * - Add caching, logging, monitoring, etc.
	 *
	 * @param request The tool call request
	 * @param handler The next handler in the chain (or base handler)
	 * @return The tool call response
	 */
	public abstract ToolCallResponse interceptToolCall(ToolCallRequest request, ToolCallHandler handler);
}

InterceptorChain - 拦截器链

InterceptorChain 实现了责任链模式，将多个拦截器串联起来。

关键代码：

public class InterceptorChain {

	/**
	 * Chain multiple ModelInterceptors into a single handler.
	 *
	 * The first interceptor wraps all others, creating a nested structure:
	 * interceptors[0] -> interceptors[1] -> ... -> base handler
	 *
	 * @param interceptors List of ModelInterceptors to chain
	 * @param baseHandler The base handler that executes the actual model call
	 * @return A composed handler, or the base handler if no interceptors
	 */
	public static ModelCallHandler chainModelInterceptors(
			List<ModelInterceptor> interceptors,
			ModelCallHandler baseHandler) {

		if (interceptors == null || interceptors.isEmpty()) {
			return baseHandler;
		}

		// Start with the base handler
		ModelCallHandler current = baseHandler;

		// Wrap from last to first (right-to-left composition)
		// This ensures first interceptor is outermost
		for (int i = interceptors.size() - 1; i >= 0; i--) {
			ModelInterceptor interceptor = interceptors.get(i);
			ModelCallHandler nextHandler = current;

			// Create a wrapper that calls the interceptor's wrap method
			current = request -> interceptor.interceptModel(request, nextHandler);
		}

		return current;
	}

	/**
	 * Chain multiple ToolInterceptors into a single handler.
	 *
	 * The first interceptor wraps all others, creating a nested structure:
	 * interceptors[0] -> interceptors[1] -> ... -> base handler
	 *
	 * @param interceptors List of ToolInterceptors to chain
	 * @param baseHandler The base handler that executes the actual tool call
	 * @return A composed handler, or the base handler if no interceptors
	 */
	public static ToolCallHandler chainToolInterceptors(
			List<ToolInterceptor> interceptors,
			ToolCallHandler baseHandler) {

		if (interceptors == null || interceptors.isEmpty()) {
			return baseHandler;
		}

		// Start with the base handler
		ToolCallHandler current = baseHandler;

		// Wrap from last to first (right-to-left composition)
		// This ensures first interceptor is outermost
		for (int i = interceptors.size() - 1; i >= 0; i--) {
			ToolInterceptor interceptor = interceptors.get(i);
			ToolCallHandler nextHandler = current;

			// Create a wrapper that calls the interceptor's wrap method
			current = request -> interceptor.interceptToolCall(request, nextHandler);
		}

		return current;
	}

链式调用机制：