Sentinel 无感接入架构（ByteBuddy 方案）

本文档详细阐述 ByteBuddy 自研 Agent 方案下 Sentinel 的无感接入架构，包括类加载隔离与桥接机制、各框架流控实现，以及与官方 Adapter 的差异点。

一、Sentinel Core 与 Adapter 类加载示意

1.1 ClassLoader 全景图

类的加载、隔离、桥接

1.2 Agent 目录布局

sentinel-agent/
├── sentinel-agent-core.jar                 # -javaagent 指向此文件（含 shaded Byte Buddy）
├── bootstrap/
│   └── sentinel-agent-bootstrap.jar        # 注入 BootstrapCL（SentinelClassBridge + SentinelAutoInjector）
├── lib/                                    # PluginClassLoader 的 classpath
│   ├── sentinel-core-1.8.6.jar
│   ├── sentinel-transport-common-1.8.6.jar
│   └── fastjson-xxx.jar ...
└── adapters/                               # 各框架 Adapter JAR（运行时 addURL 到 App CL）
    ├── sentinel-apache-dubbo-adapter-1.8.6.jar
    ├── sentinel-mybatis-adapter.jar
    ├── sentinel-adapter-spring-webmvc-1.8.6.jar
    ├── sentinel-apache-httpclient-adapter-1.8.6.jar
    ├── sentinel-okhttp-adapter-1.8.6.jar
    └── spring-cloud-starter-alibaba-sentinel-2022.0.0.0.jar  # Feign + RestTemplate

1.3 premain 启动流程

// SentinelAgent.premain()
public static void premain(String args, Instrumentation inst) {
    // 1. 注入 bootstrap JAR → BootstrapCL
    injectBootstrapJar(agentDir, inst);
    // 2. 创建隔离 PluginCL (parent=null)，加载 sentinel-core
    URLClassLoader pluginCl = createPluginClassLoader(agentDir);
    // 3. 初始化 ClassBridge —— 注册桥接前缀 "com.alibaba.csp.sentinel."
    initClassBridge(pluginCl);
    // 4. 设置 adapter JAR 路径为系统属性
    setAdapterPaths(agentDir);
    // 5. 预初始化 Sentinel SPI (TCCL 临时设为 PluginCL)
    preInitSentinel(pluginCl);
    // 6. 安装 Byte Buddy 字节码增强（10 个 Transformer）
    installTransformers(inst);
}

1.4 桥接机制 —— 类加载拦截与路由

Byte Buddy Advice 内联到 ClassLoader.loadClass(String, boolean) 方法入口：

// ClassLoaderLoadClassAdvice.java —— 内联到所有 ClassLoader 的 loadClass
@Advice.OnMethodEnter(skipOn = Advice.OnNonDefaultValue.class)
public static Class<?> onEnter(@Advice.This ClassLoader self,
                                @Advice.Argument(0) String name) {
    return SentinelClassBridge.loadClass(name, self);
}

@Advice.OnMethodExit
public static void onExit(@Advice.Enter Class<?> bridgedClass,
                           @Advice.Return(readOnly = false) Class<?> returnValue) {
    if (bridgedClass != null) {
        returnValue = bridgedClass;
    }
}

// SentinelClassBridge.java —— 在 BootstrapCL 中，全局可见
public static Class<?> loadClass(String name, ClassLoader caller) {
    if (name == null || pluginClassLoader == null) return null;
    if (name.startsWith("java.") || name.startsWith("sun.") || name.startsWith("jdk.")) return null;
    if (caller == pluginClassLoader) return null;  // 防递归
    for (String prefix : classPrefixes) {           // "com.alibaba.csp.sentinel."
        if (name.startsWith(prefix)) {
            try { return pluginClassLoader.loadClass(name); }
            catch (ClassNotFoundException e) { return null; }
        }
    }
    return null;
}

桥接流程四步：

1.5 Adapter "双头依赖" 解决路径

Adapter 类同时依赖 Sentinel Core 和 框架类（如 org.apache.dubbo.rpc.Filter），两者位于不同 ClassLoader。解决方案：

1. Adapter JAR 通过 addURL() 注入到 应用 ClassLoader
2. Adapter 类由 App CL 定义
3. 引用 Sentinel Core → App CL.loadClass("SphU") → Bridge 拦截 → PluginCL.loadClass → 找到 ✔
4. 引用框架类 → App CL.loadClass("Filter") → 直接找到 ✔

Adapter JAR 不在 PluginCL 的 lib/ 中，Bridge 尝试加载时 CNFE → fallback 给 App CL 继续加载，确保 Adapter 由 App CL 定义。

二、HTTP 服务端流控 —— Spring WebMVC

2.1 整体方案

Spring WebMVC的流控

2.2 官方接入方式

在 spring-cloud-starter-alibaba-sentinel 中，SentinelWebAutoConfiguration 自动注册：

// SentinelWebAutoConfiguration.java（官方 Spring Cloud Alibaba）
@Configuration
@ConditionalOnWebApplication(type = SERVLET)
@ConditionalOnClass(SentinelWebInterceptor.class)
public class SentinelWebAutoConfiguration {

    @Bean
    public SentinelWebInterceptor sentinelWebInterceptor(SentinelWebMvcConfig config) {
        return new SentinelWebInterceptor(config);  // ← 传入配置对象
    }

    @Bean
    public SentinelWebMvcConfig sentinelWebMvcConfig() {
        SentinelWebMvcConfig config = new SentinelWebMvcConfig();
        config.setHttpMethodSpecify(properties.getHttpMethodSpecify());
        config.setWebContextUnify(properties.getWebContextUnify());
        // UrlCleaner, BlockExceptionHandler, RequestOriginParser 等可自定义
        return config;
    }

    @Bean
    public SentinelWebMvcConfigurer sentinelWebMvcConfigurer() {
        // 通过 WebMvcConfigurer.addInterceptors() 注册
        // 可配置 order 和 urlPatterns
    }
}

官方 SentinelWebInterceptor 的流控核心（继承自 AbstractSentinelInterceptor）：

// AbstractSentinelInterceptor.preHandle()
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String resourceName = getResourceName(request);
    // 引用计数：防止 forward/include 重复流控
    if (increaseReference(request, requestRefName, 1) != 1) return true;
    String origin = parseOrigin(request);   // RequestOriginParser
    String contextName = getContextName(request);
    ContextUtil.enter(contextName, origin);
    Entry entry = SphU.entry(resourceName, ResourceTypeConstants.COMMON_WEB, EntryType.IN);
    request.setAttribute(requestAttributeName, entry);
    return true;
    // catch BlockException → blockExceptionHandler.handle(request, response, resourceName, e)
}

资源名提取（SentinelWebInterceptor）：

protected String getResourceName(HttpServletRequest request) {
    // 使用 HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE（如 /api/users/{id}）
    Object resourceNameObject = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
    String resourceName = (String) resourceNameObject;
    // 可选：UrlCleaner 清洗
    // 可选：httpMethodSpecify → "GET:/api/users/{id}"
    return resourceName;
}

2.3 无感接入方式

拦截点： InterceptorRegistry.getInterceptors() 方法返回后

// SpringWebMvcGetInterceptorsAdvice.java
public class SpringWebMvcGetInterceptorsAdvice {
    @Advice.OnMethodExit
    public static void onExit(@Advice.This Object interceptorRegistry,
                               @Advice.Return Object interceptors) {
        SentinelAutoInjector.afterGetInterceptors(interceptorRegistry, interceptors);
    }
}

注入逻辑：

// SentinelAutoInjector.afterGetInterceptors()
public static void afterGetInterceptors(Object interceptorRegistry, Object interceptors) {
    List<Object> interceptorList = (List<Object>) interceptors;

    // 1. 幂等检查：已存在 SentinelWebInterceptor 则跳过
    for (Object interceptor : interceptorList) {
        if (interceptor.getClass().getName().contains("SentinelWebInterceptor")) return;
    }

    // 2. addURL 注入 sentinel-spring-webmvc-adapter JAR 到 App CL
    injectSpringWebMvcAdapter(appCl);

    // 3. 反射创建 SentinelWebInterceptor（默认构造器）
    Class<?> interceptorClass = Class.forName(SENTINEL_WEB_INTERCEPTOR_CLASS, true, appCl);
    Object webInterceptor = interceptorClass.getDeclaredConstructor().newInstance();

    // 4. 插入到拦截器列表首位
    interceptorList.add(0, webInterceptor);
}

2.4 ⚠️ 与官方 Adapter 的差异

核心影响： 无感接入场景下 SentinelWebInterceptor 以默认配置运行，用户无法通过 application.yml 自定义 URL 清洗器、限流返回体、来源解析器等。如需精细配置，需额外实现配置注入逻辑。

三、HTTP 客户端流控

3.0 总览

3.1 RestTemplate 流控

RestTemplate_Adapter注入模式

3.1.1 官方接入方式

官方依赖 @SentinelRestTemplate 注解 + SentinelBeanPostProcessor 自动装配：

// 用户代码 —— 必须显式标注 @SentinelRestTemplate
@Bean
@SentinelRestTemplate(blockHandler = "handleBlock", blockHandlerClass = MyHandler.class,
                       fallback = "handleFallback", fallbackClass = MyHandler.class,
                       urlCleaner = "cleanUrl", urlCleanerClass = MyHandler.class)
public RestTemplate restTemplate() {
    return new RestTemplate();
}

SentinelBeanPostProcessor 在 postProcessAfterInitialization 中扫描带 @SentinelRestTemplate 注解的 Bean，将 SentinelProtectInterceptor 添加到其拦截器链。

SentinelProtectInterceptor 的双资源策略：

// SentinelProtectInterceptor.intercept()
// 资源 1（主机级）: GET:http://service-a:8080
Entry hostEntry = SphU.entry(hostResource, EntryType.OUT);
// 资源 2（路径级）: GET:http://service-a:8080/api/users
Entry hostWithPathEntry = SphU.entry(hostWithPathResource, EntryType.OUT);
// 执行实际请求
response = execution.execute(request, body);
// BlockException 处理: 熔断走 fallback，限流走 blockHandler，默认返回 SentinelClientHttpResponse

3.1.2 无感接入方式

拦截点： RestTemplate 所有构造器 + setInterceptors(List) 方法

// RestTemplateConstructorAdvice.java
@Advice.OnMethodExit
public static void onExit(@Advice.This Object restTemplate) {
    SentinelAutoInjector.ensureSentinelProtectInterceptorOnRestTemplate(restTemplate);
}

// RestTemplateSetInterceptorsAdvice.java
@Advice.OnMethodExit
public static void onExit(@Advice.This Object restTemplate) {
    SentinelAutoInjector.ensureSentinelProtectInterceptorOnRestTemplate(restTemplate);
}

注入逻辑核心：

// SentinelAutoInjector.ensureSentinelProtectInterceptorOnRestTemplate()
public static void ensureSentinelProtectInterceptorOnRestTemplate(Object restTemplate) {
    // 1. addURL 注入 spring-cloud-starter-alibaba-sentinel JAR
    injectRestTemplateAdapter(appCl);

    // 2. 通过 JDK 动态代理创建默认的 @SentinelRestTemplate 注解实例
    //    blockHandler=""、fallback=""、urlCleaner="" —— 全部为空
    Object annotation = createDefaultSentinelRestTemplateAnnotation(annotationClass, appCl);

    // 3. 反射创建 SentinelProtectInterceptor(annotation, restTemplate)
    Object interceptor = interceptorCtor.newInstance(annotation, restTemplate);

    // 4. 确保 SentinelProtectInterceptor 位于拦截器链首位
    interceptors.add(0, interceptor);
}

动态代理注解关键实现：

// 所有自定义属性返回空值 —— 不支持 blockHandler/fallback/urlCleaner
public Object invoke(Object proxy, Method method, Object[] args) {
    if ("blockHandler".equals(methodName) || "fallback".equals(methodName)
            || "urlCleaner".equals(methodName)) {
        return "";    // ← 空字符串，不会触发自定义处理
    }
    if ("blockHandlerClass".equals(methodName) || "fallbackClass".equals(methodName)
            || "urlCleanerClass".equals(methodName)) {
        return Void.TYPE;  // ← 无处理类
    }
    // ...
}

3.1.3 ⚠️ 与官方 Adapter 的差异

3.2 Apache HttpClient 流控

Apache HttpClient Adapter 注入模式

3.2.1 官方接入方式

官方要求用户替换 HttpClientBuilder 为 SentinelApacheHttpClientBuilder：

// 官方用法 —— 需要修改代码
CloseableHttpClient httpClient = new SentinelApacheHttpClientBuilder()
    .build();

SentinelApacheHttpClientBuilder 重写 decorateMainExec(ClientExecChain)，用匿名 ClientExecChain 包装原始链：

// SentinelApacheHttpClientBuilder.decorateMainExec()
@Override
protected ClientExecChain decorateMainExec(final ClientExecChain mainExec) {
    return new ClientExecChain() {
        public CloseableHttpResponse execute(HttpRoute route, HttpRequestWrapper request, ...) {
            String name = config.getExtractor().extractor(request);   // 默认: request.getRequestLine().getUri()
            if (!StringUtil.isEmpty(config.getPrefix())) {
                name = config.getPrefix() + name;                     // 默认前缀: "httpclient:"
            }
            Entry entry = SphU.entry(name, ResourceTypeConstants.COMMON_WEB, EntryType.OUT);
            return mainExec.execute(route, request, clientContext, execAware);
            // catch BlockException → config.getFallback().handle(request, e)
            // finally: entry.exit()
        }
    };
}

3.2.2 无感接入方式

拦截点： HttpClientBuilder.decorateMainExec(ClientExecChain) 返回后

// HttpClientDecorateMainExecAdvice.java
@Advice.OnMethodExit
public static void onExit(@Advice.This Object builder,
                           @Advice.Return(readOnly = false) Object returnValue) {
    returnValue = SentinelAutoInjector.wrapHttpClientExecChain(returnValue, builder);
}

注入逻辑：

// SentinelAutoInjector.wrapHttpClientExecChain()
public static Object wrapHttpClientExecChain(Object originalChain, Object builder) {
    // 1. 幂等检查：已经是 SentinelApacheHttpClientBuilder 则跳过
    if (builder.getClass().getName().contains("SentinelApacheHttpClientBuilder")) return originalChain;

    // 2. addURL 注入 sentinel-apache-httpclient-adapter JAR 到 App CL
    injectHttpClientAdapter(appCl);

    // 3. 反射创建 SentinelApacheHttpClientBuilder 实例
    // 4. 调用其 decorateMainExec(originalChain) 包装原始执行链
    Object wrappedChain = holder.decorateMainExecMethod.invoke(holder.sentinelBuilder, originalChain);
    return wrappedChain;
}

设计类比：

TTL Agent:       $1 = TtlTransformletHelper.doAutoWrap($1)   → 包装 Runnable 参数
HttpClient Agent: ret = wrapHttpClientExecChain(ret, builder) → 包装 ClientExecChain 返回值

3.2.3 ⚠️ 与官方 Adapter 的差异

3.3 OkHttp 流控

OkHttp_Adapter注入模式

3.3.1 官方接入方式

官方要求手动添加 Interceptor：

// 官方用法 —— 需要修改代码
OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new SentinelOkHttpInterceptor())  // ← 手动添加
    .build();

SentinelOkHttpInterceptor 作为 Application Interceptor，同时覆盖同步 execute() 和异步 enqueue()：

// SentinelOkHttpInterceptor.intercept()
public Response intercept(Chain chain) throws IOException {
    Request request = chain.request();
    String name = config.getResourceExtractor().extract(request, chain.connection());
    // 默认: request.method() + ":" + request.url().toString()
    if (StringUtil.isNotBlank(config.getResourcePrefix())) {
        name = config.getResourcePrefix() + name;   // 默认前缀: "okhttp:"
    }
    Entry entry = SphU.entry(name, ResourceTypeConstants.COMMON_WEB, EntryType.OUT);
    return chain.proceed(request);
    // catch BlockException → config.getFallback().handle(request, connection, e)
    // finally: entry.exit()
}

3.3.2 无感接入方式

拦截点： OkHttpClient.Builder.build() 方法入口

// OkHttpClientBuildAdvice.java
@Advice.OnMethodEnter
public static void onEnter(@Advice.This Object builder) {
    SentinelAutoInjector.beforeOkHttpClientBuild(builder);
}

注入逻辑：

// SentinelAutoInjector.beforeOkHttpClientBuild()
public static void beforeOkHttpClientBuild(Object builder) {
    // 1. addURL 注入 sentinel-okhttp-adapter JAR 到 App CL
    injectOkHttpAdapter(appCl);

    // 2. 幂等检查：反射读取 Builder.interceptors 列表，已存在 SentinelOkHttpInterceptor 则跳过
    List<Object> interceptors = (List<Object>) interceptorsField.get(builder);
    for (Object interceptor : interceptors) {
        if (interceptor.getClass().getName().equals(SENTINEL_OKHTTP_INTERCEPTOR_CLASS)) return;
    }

    // 3. 反射创建 SentinelOkHttpInterceptor（默认构造器）
    Object sentinelInterceptor = interceptorClass.getDeclaredConstructor().newInstance();

    // 4. 调用 builder.addInterceptor(sentinelInterceptor)
    addInterceptor.invoke(builder, sentinelInterceptor);
}

3.3.3 ⚠️ 与官方 Adapter 的差异

3.4 Feign 流控

Feign_Adapter注入模式

3.4.1 官方接入方式

官方通过 Spring Boot AutoConfiguration：

# application.yml
feign:
  sentinel:
    enabled: true   # ← 触发 SentinelFeignAutoConfiguration

// SentinelFeignAutoConfiguration.java
@Bean
@Scope("prototype")
@ConditionalOnProperty(name = "feign.sentinel.enabled")
public Feign.Builder feignSentinelBuilder() {
    return SentinelFeign.builder();  // 返回自定义的 Builder
}

SentinelFeign.Builder.build() 内部：

// SentinelFeign.Builder (官方)
super.invocationHandlerFactory(new InvocationHandlerFactory() {
    public InvocationHandler create(Target target, Map<Method, MethodHandler> dispatch) {
        // 获取 FallbackFactory（如果用户配置了的话）
        Object fallbackFactory = ...;
        return new SentinelInvocationHandler(target, dispatch, fallbackFactory);
    }
});
super.contract(new SentinelContractHolder(contract));

SentinelInvocationHandler.invoke() 流控逻辑：

// SentinelInvocationHandler.invoke()
ContextUtil.enter(resourceName);
Entry entry = SphU.entry(resourceName, EntryType.OUT, 1, args);
Object result = methodHandler.invoke(args);
// catch BlockException → 若有 fallbackFactory 走 fallback；否则直接抛
// finally: entry.exit(1, args); ContextUtil.exit();

资源名由 SentinelContractHolder 收集的 MethodMetadata 构建：METHOD: + hardCodedTarget.url() + methodMetadata.template().path()。

3.4.2 无感接入方式

拦截点： Feign.Builder.build() 方法入口

// FeignBuilderBuildAdvice.java
@Advice.OnMethodEnter
public static void onEnter(@Advice.This Object builder) {
    SentinelAutoInjector.beforeFeignBuild(builder);
}

注入逻辑：

// SentinelAutoInjector.beforeFeignBuild()
public static void beforeFeignBuild(Object builder) {
    // 幂等检查：已经是 SentinelFeign 则跳过
    if (builderClassName.contains("SentinelFeign")) return;

    // 1. addURL 注入 spring-cloud-starter-alibaba-sentinel JAR 到 App CL
    injectFeignAdapter(appCl);

    // 2. 用 SentinelContractHolder 包装原始 contract
    Object originalContract = contractField.get(builder);
    Object sentinelContract = contractHolderClass
        .getDeclaredConstructor(contractInterface).newInstance(originalContract);
    contractField.set(builder, sentinelContract);

    // 3. 准备双构造器：无 fallback + 有 fallback
    Constructor<?> handlerCtorNoFallback = sentinelHandlerClass
        .getDeclaredConstructor(targetClass, Map.class);
    Constructor<?> handlerCtorWithFallback = null;
    Class<?> sentinelFfClass = null;
    try {
        sentinelFfClass = Class.forName(
                "org.springframework.cloud.openfeign.FallbackFactory", true, appCl);
        handlerCtorWithFallback = sentinelHandlerClass
                .getDeclaredConstructor(targetClass, Map.class, sentinelFfClass);
    } catch (Throwable ignored) {}

    // 4. JDK 动态代理实现 InvocationHandlerFactory（支持 fallback 解析）
    Object sentinelFactory = Proxy.newProxyInstance(appCl,
        new Class[]{ invHandlerFactoryClass },
        (proxy, method, args) -> {
            if ("create".equals(method.getName())) {
                // 尝试从 @FeignClient 注解解析 fallbackFactory / fallback
                if (handlerCtorWithFallback != null) {
                    Object ff = resolveFeignFallbackFactory(
                            args[0]/*target*/, sentinelFfClass, appCl);
                    if (ff != null) {
                        return handlerCtorWithFallback.newInstance(args[0], args[1], ff);
                    }
                }
                return handlerCtorNoFallback.newInstance(args[0], args[1]);
            }
            // ...
        });
    factoryField.set(builder, sentinelFactory);
}

Fallback 解析机制： 在 InvocationHandlerFactory.create(target, dispatch) 时自动解析：

// resolveFeignFallbackFactory() — 从 @FeignClient 注解解析降级配置
private static Object resolveFeignFallbackFactory(Object target, Class<?> sentinelFfClass, ClassLoader appCl) {
    // 1. target.type() → @FeignClient 接口（兼容 OpenFeign + Netflix 两种包路径）
    // 2. 读取 fallbackFactory / fallback 属性
    // 3. 通过无参构造器直接实例化
    // 4. 适配为 org.springframework.cloud.openfeign.FallbackFactory
    //    （feign.hystrix.FallbackFactory → JDK 动态代理适配，方法签名兼容 create(Throwable)）
    // 5. 解析失败 → return null → 静默降级为无 fallback 模式
}

3.4.3 ⚠️ 与官方 Adapter 的差异

核心差异： Fallback 类通过无参构造器直接实例化，不经过 Spring 容器。对于仅使用 Logger 等静态资源的简单 fallback 类（如大部分业务 FallbackFactory 实现）可正常工作。依赖 @Autowired 注入的复杂 fallback 需业务配置 feign.sentinel.enabled=true 走官方链路。

3.5 JDK HttpURLConnection 流控

HttpURLConnection流控

3.5.1 概述

java.net.HttpURLConnection（实现类 sun.net.www.protocol.http.HttpURLConnection）是 JDK 内置 HTTP 客户端，Sentinel 官方没有提供对应 Adapter。无感接入采用直接流控模式——在 Advice 中直接反射调用 SphU.entry()/entry.exit()。

3.5.2 双拦截点模型

connect()        ──── 流控主入口：创建 Entry + 阻断检查（TCP 建连之前阻断）
                      Entry 存入 ThreadLocal
                      
getInputStream() ──── 响应阶段：关闭 Entry + 异常追踪
                      从 ThreadLocal 取出 Entry 并 exit

设计原因： HttpURLConnection 的 API 模型是 connect() → getInputStream()，流控 Entry 的生命周期需要跨越两次方法调用。使用 ThreadLocal 在两个拦截点之间传递 Entry。

3.5.3 connect() 拦截

// HttpURLConnectionConnectAdvice.java
@Advice.OnMethodEnter(skipOn = Advice.OnNonDefaultValue.class)
public static int onEnter(@Advice.This Object conn) {
    return SentinelAutoInjector.beforeUrlConnectionConnect(conn);
    // 返回 0 = 放行，1 = 被 Sentinel 阻断
}

@Advice.OnMethodExit(onThrowable = Throwable.class)
public static void onExit(@Advice.Enter int blocked, @Advice.Thrown(readOnly = false) Throwable thrown) {
    if (blocked != 0) {
        thrown = new java.io.IOException("Blocked by Sentinel (flow limiting)");
        SentinelAutoInjector.afterUrlConnectionConnect(thrown);
    } else if (thrown != null) {
        SentinelAutoInjector.afterUrlConnectionConnect(thrown);
    }
}

流控逻辑：

// SentinelAutoInjector.beforeUrlConnectionConnect()
public static int beforeUrlConnectionConnect(Object conn) {
    // 1. 防重入：ThreadLocal 已有 Entry 则跳过
    if (CURRENT_URLCONN_ENTRY.get() != null) return 0;

    // 2. 获取 ClassLoader：HttpURLConnection 由 BootstrapCL 加载，conn.getClass().getClassLoader() == null
    //    使用 TCCL 获取 App CL，TCCL 为 null 时回退 SentinelClassBridge.getPluginClassLoader()
    ClassLoader appCl = Thread.currentThread().getContextClassLoader();
    if (appCl == null) appCl = SentinelClassBridge.getPluginClassLoader();

    // 3. 构建资源名: HttpURLConnection_{METHOD}_{path}
    String resourceName = buildUrlConnectionResourceName(method, urlStr);

    // 4. 反射调用 SphU.entry(resourceName, EntryType.OUT)
    Object entry = sentinelEntry(appCl, resourceName, 0);
    CURRENT_URLCONN_ENTRY.set(entry);
    return 0;
    // catch: 若 BlockException → return 1 (阻断)
}

3.5.4 getInputStream() 拦截

// HttpURLConnectionGetInputStreamAdvice.java
@Advice.OnMethodExit(onThrowable = Throwable.class)
public static void onExit(@Advice.Thrown Throwable thrown) {
    SentinelAutoInjector.afterUrlConnectionGetInputStream(thrown);
}

// SentinelAutoInjector.afterUrlConnectionGetInputStream()
public static void afterUrlConnectionGetInputStream(Throwable error) {
    Object entry = CURRENT_URLCONN_ENTRY.get();
    if (entry == null) return;
    CURRENT_URLCONN_ENTRY.remove();
    if (error != null) traceException(entry, error);
    exitEntry(entry);
}

3.5.5 BootstrapCL 类加载问题

sun.net.www.protocol.http.HttpURLConnection 由 BootstrapClassLoader 加载。Advice 内联代码引用的 SentinelAutoInjector 必须对 BootstrapCL 可见。

ByteBuddy 方案的天然优势： SentinelAutoInjector 打包在 agent-bootstrap.jar 中，已通过 inst.appendToBootstrapClassLoaderSearch() 注入 BootstrapCL，无需额外 Spy 桥接层。

独立 AgentBuilder 的必要性：AgentBuilder.Default() 默认 ignore Bootstrap 类。HttpURLConnection 使用独立 AgentBuilder 并覆盖 ignore 规则：

new AgentBuilder.Default()
    .ignore(nameStartsWith("net.bytebuddy."))  // 仅 ignore ByteBuddy 自身
    .type(named("sun.net.www.protocol.http.HttpURLConnection"))
    .transform(...)
    .installOn(inst);

3.5.6 资源名构建

private static String buildUrlConnectionResourceName(String method, String urlStr) {
    String path = new URL(urlStr).getPath();   // 提取 path 部分
    if (path == null || path.isEmpty()) path = "/";
    return "HttpURLConnection_" + method + "_" + path;
    // 示例: HttpURLConnection_POST_/api/submit
}

3.5.7 特殊场景

四、MyBatis 流控

4.1 概述

Sentinel 官方不提供 MyBatis Adapter。 无感接入方案自研了 sentinel-mybatis-adapter，基于 MyBatis Interceptor 机制实现 SQL 级别流控。

4.2 Adapter 实现

4.2.1 SentinelMyBatisMapperInterceptor

// SentinelMyBatisMapperInterceptor.java
@Intercepts({
    @Signature(type = Executor.class, method = "query",
        args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}),
    @Signature(type = Executor.class, method = "update",
        args = {MappedStatement.class, Object.class})
})
public class SentinelMyBatisMapperInterceptor implements Interceptor {

    public static final String MYBATIS_PREFIX = "mybatis:";

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
        String mapperId = ms.getId();   // 如: com.example.mapper.UserMapper.selectById

        Entry entry = null;
        try {
            entry = SphU.entry(MYBATIS_PREFIX + mapperId,
                ResourceTypeConstants.COMMON_DB_SQL, EntryType.OUT);
            return invocation.proceed();
        } catch (BlockException ex) {
            throw new MyBatisSentinelBlockException(ex);
        } catch (Throwable t) {
            Tracer.traceEntry(t, entry);
            throw t;
        } finally {
            if (entry != null) entry.exit();
        }
    }
}

资源名格式： mybatis:com.example.mapper.UserMapper.selectById

资源类型： ResourceTypeConstants.COMMON_DB_SQL

EntryType： OUT（作为下游资源）

4.2.2 MyBatisSentinelBlockException

public class MyBatisSentinelBlockException extends RuntimeException {
    private final BlockException blockException;

    public MyBatisSentinelBlockException(BlockException cause) {
        super(cause);
        this.blockException = cause;
    }

    public BlockException getBlockException() {
        return blockException;
    }
}

4.3 注入方式

拦截点： org.apache.ibatis.plugin.InterceptorChain.pluginAll(Object)

// MyBatisPluginAllAdvice.java
@Advice.OnMethodEnter
public static void onEnter(@Advice.This Object interceptorChain) {
    SentinelAutoInjector.beforeMyBatisPluginAll(interceptorChain);
}

注入逻辑：

// SentinelAutoInjector.beforeMyBatisPluginAll()
public static void beforeMyBatisPluginAll(Object interceptorChain) {
    // 1. addURL 注入 sentinel-mybatis-adapter JAR 到 App CL
    File adapterJar = findMyBatisAdapterJar();
    tryAddUrl(appCl, adapterJar.toURI().toURL());

    // 2. 幂等检查：检查 InterceptorChain 中是否已有 SentinelMyBatisMapperInterceptor
    if (hasInterceptor(interceptorChain, interceptorClazz.getName())) return;

    // 3. 反射创建 SentinelMyBatisMapperInterceptor 实例
    Object interceptor = interceptorClazz.getDeclaredConstructor().newInstance();

    // 4. 反射调用 InterceptorChain.addInterceptor(Interceptor) 注入
    Method addInterceptor = interceptorChain.getClass().getMethod("addInterceptor", interceptorType);
    addInterceptor.invoke(interceptorChain, interceptor);
}

时序： 在 MyBatis 初始化 Configuration.newExecutor() → InterceptorChain.pluginAll(executor) 调用前注入拦截器，确保后续所有 Executor 实例都经过 Sentinel 流控包装。

4.4 流控效果

4.5 注意事项

• 官方无对标 Adapter：此为完全自研实现，资源名格式 mybatis:{mapperId} 无官方先例
• 粒度较细：每个 Mapper 方法一个资源，大型项目可能产生大量资源条目
• BlockException 包装：MyBatis 的 Interceptor.intercept() 签名为 throws Throwable，但 BlockException 是受检异常。为避免上层调用方（如 Spring 事务管理器）误处理，将其包装为 MyBatisSentinelBlockException（RuntimeException）

五、Sentinel API 反射缓存机制

所有直接流控模式（HttpURLConnection）和 Adapter 创建逻辑均依赖反射调用 Sentinel API。为避免重复反射查找，使用 SentinelApiHolder 按 ClassLoader 缓存：

private static class SentinelApiHolder {
    final Method entryMethod;      // SphU.entry(String, EntryType)
    final Object entryTypeIn;      // EntryType.IN
    final Object entryTypeOut;     // EntryType.OUT
    final Method exitMethod;       // Entry.exit()
    final Method traceMethod;      // Tracer.trace(Throwable)

    SentinelApiHolder(ClassLoader appCl) throws Throwable {
        // 通过 appCl 加载 → ClassBridge 路由到 PluginCL
        Class<?> sphUClass = Class.forName("com.alibaba.csp.sentinel.SphU", true, appCl);
        // ...
    }
}

private static final Map<ClassLoader, SentinelApiHolder> API_CACHE =
    Collections.synchronizedMap(new WeakHashMap<>());

WeakHashMap 设计：key 为 ClassLoader，当 ClassLoader 被 GC 回收时（如 WAR 热部署），缓存条目自动清除，防止内存泄漏。

六、与官方差异汇总

6.1 注入官方 Adapter JAR 的框架

6.2 通用差异模式

6.3 自研 Adapter（无官方对标）

七、Byte Buddy Transformer 注册清单