动态代理 ⭐⭐⭐

/**
 * 抽象主题接口 —— 用户服务
 * Client 面向此接口编程，不关心背后是真实对象还是代理
 */
public interface UserService {
 
    // 根据 ID 查询用户名
    String findUserById(int id);
 
    // 保存用户信息
    void saveUser(String name);
}

/**
 * 真实主题 —— 用户服务的具体实现
 * 包含核心业务逻辑，不掺杂任何日志、监控等横切关注点
 */
public class UserServiceImpl implements UserService {
 
    @Override
    public String findUserById(int id) {
        // 模拟数据库查询操作
        System.out.println("[DB] 正在查询用户, id = " + id);
        // 返回模拟结果
        return "User_" + id;
    }
 
    @Override
    public void saveUser(String name) {
        // 模拟数据库写入操作
        System.out.println("[DB] 正在保存用户, name = " + name);
    }
}

/**
 * 静态代理类 —— 为 UserService 提供日志 + 耗时统计的增强
 * 它与 UserServiceImpl 实现同一个接口，对外表现一致
 */
public class UserServiceProxy implements UserService {
 
    // 持有真实对象的引用（组合关系）
    private final UserService target;
 
    // 通过构造器注入真实对象
    public UserServiceProxy(UserService target) {
        this.target = target;
    }
 
    @Override
    public String findUserById(int id) {
        // ===== 前置增强：记录日志 =====
        System.out.println("[LOG] 调用 findUserById, 参数: id=" + id);
        // 记录方法开始时间
        long start = System.currentTimeMillis();
 
        // ===== 委托给真实对象执行核心逻辑 =====
        String result = target.findUserById(id);
 
        // ===== 后置增强：统计耗时 =====
        long cost = System.currentTimeMillis() - start;
        System.out.println("[LOG] findUserById 执行完毕, 耗时: " + cost + "ms");
 
        // 将真实对象的返回值原样返回
        return result;
    }
 
    @Override
    public void saveUser(String name) {
        // ===== 前置增强 =====
        System.out.println("[LOG] 调用 saveUser, 参数: name=" + name);
        long start = System.currentTimeMillis();
 
        // ===== 委托调用 =====
        target.saveUser(name);
 
        // ===== 后置增强 =====
        long cost = System.currentTimeMillis() - start;
        System.out.println("[LOG] saveUser 执行完毕, 耗时: " + cost + "ms");
    }
}

public class Client {
    public static void main(String[] args) {
        // 1. 创建真实对象
        UserService realService = new UserServiceImpl();
 
        // 2. 用代理包装真实对象
        UserService proxy = new UserServiceProxy(realService);
 
        // 3. 客户端通过代理调用，完全感知不到代理的存在
        String user = proxy.findUserById(42);
        System.out.println("查询结果: " + user);
 
        System.out.println("---");
 
        proxy.saveUser("Alice");
    }
}

[LOG] 调用 findUserById, 参数: id=42
[DB] 正在查询用户, id = 42
[LOG] findUserById 执行完毕, 耗时: 0ms
查询结果: User_42
---
[LOG] 调用 saveUser, 参数: name=Alice
[DB] 正在保存用户, name = Alice
[LOG] saveUser 执行完毕, 耗时: 0ms

// 每个服务接口...
public interface UserService { ... }      // 用户服务
public interface OrderService { ... }     // 订单服务
public interface PaymentService { ... }   // 支付服务
public interface ProductService { ... }   // 商品服务
public interface LogisticsService { ... } // 物流服务

UserServiceProxy.java
OrderServiceProxy.java
PaymentServiceProxy.java
ProductServiceProxy.java
LogisticsServiceProxy.java

public interface UserService {
    String findUserById(int id);
    void saveUser(String name);
    void deleteUser(int id);  // 新增方法
}

public static Object newProxyInstance(
    ClassLoader loader,        // 1. 类加载器：用哪个 ClassLoader 来加载生成的代理类
    Class<?>[] interfaces,     // 2. 接口数组：代理类需要实现哪些接口
    InvocationHandler h        // 3. 调用处理器：方法被调用时，具体执行什么逻辑
)

// 最常见的写法：拿到目标接口的类加载器
ClassLoader loader = UserService.class.getClassLoader();

// 可以同时代理多个接口
Class<?>[] interfaces = new Class<?>[]{ UserService.class, Serializable.class };

// 定义业务接口
public interface UserService {
    // 根据 ID 查询用户名
    String findUserById(int id);
    // 保存用户，返回是否成功
    boolean saveUser(String name);
}

// 真实业务实现类
public class UserServiceImpl implements UserService {
    @Override
    public String findUserById(int id) {
        // 模拟数据库查询
        System.out.println("执行数据库查询, id = " + id);
        return "User-" + id;
    }
 
    @Override
    public boolean saveUser(String name) {
        // 模拟数据库写入
        System.out.println("执行数据库写入, name = " + name);
        return true;
    }
}

public class ProxyDemo {
    public static void main(String[] args) {
        // 1. 创建真实对象（被代理的目标）
        UserService realService = new UserServiceImpl();
 
        // 2. 通过 Proxy.newProxyInstance 创建代理对象
        UserService proxy = (UserService) Proxy.newProxyInstance(
            UserService.class.getClassLoader(),          // 类加载器
            new Class<?>[]{ UserService.class },         // 要代理的接口
            new SimpleInvocationHandler(realService)     // 调用处理器（下一节实现）
        );
 
        // 3. 通过代理对象调用方法 —— 实际会走 InvocationHandler.invoke()
        String user = proxy.findUserById(42);
        System.out.println("返回结果: " + user);
    }
}

public interface InvocationHandler {
    /**
     * 当代理对象的任意方法被调用时，都会转发到这里
     *
     * @param proxy  代理对象本身（注意：不是被代理的真实对象！）
     * @param method 被调用的方法的 Method 反射对象
     * @param args   方法参数数组，无参方法时为 null
     * @return       方法的返回值，会被返回给调用方
     * @throws Throwable 可以抛出任何异常
     */
    Object invoke(Object proxy, Method method, Object[] args) throws Throwable;
}

// ❌ 错误示范：在 invoke 中调用 proxy 的方法
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    // proxy.toString() 会再次触发 invoke()，形成无限递归，最终 StackOverflowError
    System.out.println("代理对象: " + proxy.toString()); // 💥 死循环！
    return method.invoke(target, args);
}

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
 
public class LoggingHandler implements InvocationHandler {
 
    // 持有真实对象的引用，invoke 中通过它调用真正的业务逻辑
    private final Object target;
 
    // 构造时传入被代理的真实对象
    public LoggingHandler(Object target) {
        this.target = target;
    }
 
    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        // ========== 前置增强（Before Advice）==========
        // 获取方法名，用于日志输出
        String methodName = method.getName();
        // 打印方法调用信息，包含参数
        System.out.println("[LOG] 方法调用开始: " + methodName);
        // 记录方法开始执行的时间戳
        long startTime = System.currentTimeMillis();
 
        // ========== 调用真实对象的方法 ==========
        Object result;
        try {
            // 通过反射调用 target（真实对象）的对应方法
            // method.invoke(target, args) 等价于 target.methodName(args)
            result = method.invoke(target, args);
        } catch (Exception e) {
            // ========== 异常增强（After Throwing Advice）==========
            // 捕获异常后记录日志，然后重新抛出，不吞掉异常
            System.out.println("[LOG] 方法异常: " + methodName + ", 异常: " + e.getCause());
            throw e;
        }
 
        // ========== 后置增强（After Returning Advice）==========
        // 计算方法执行耗时
        long cost = System.currentTimeMillis() - startTime;
        // 打印返回值和耗时
        System.out.println("[LOG] 方法调用结束: " + methodName
                + ", 返回值: " + result
                + ", 耗时: " + cost + "ms");
 
        // 将真实对象的返回值原样返回给调用方
        return result;
    }
}

public class ProxyDemo {
    public static void main(String[] args) {
        // 创建真实业务对象
        UserService realService = new UserServiceImpl();
 
        // 创建代理对象，注入 LoggingHandler
        UserService proxy = (UserService) Proxy.newProxyInstance(
            UserService.class.getClassLoader(),      // 接口的类加载器
            new Class<?>[]{ UserService.class },     // 代理的接口列表
            new LoggingHandler(realService)           // 调用处理器
        );
 
        // 调用代理对象的方法
        String user = proxy.findUserById(42);
        System.out.println("最终结果: " + user);
 
        System.out.println("---分割线---");
 
        boolean saved = proxy.saveUser("Alice");
        System.out.println("保存结果: " + saved);
    }
}

@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
 
    // 技巧1：跳过 Object 类自带的方法（toString, hashCode, equals）
    // 这些方法通常不需要走代理逻辑
    if (method.getDeclaringClass() == Object.class) {
        // 直接调用真实对象的对应方法，不做任何增强
        return method.invoke(target, args);
    }
 
    // 技巧2：根据方法名做条件拦截
    // 比如只对 "find" 开头的查询方法做缓存
    if (method.getName().startsWith("find")) {
        // 先查缓存
        String cacheKey = method.getName() + Arrays.toString(args);
        Object cached = cache.get(cacheKey);
        if (cached != null) {
            System.out.println("[CACHE HIT] " + cacheKey);
            return cached; // 命中缓存，直接返回，不调用真实对象
        }
        // 未命中，调用真实方法并缓存结果
        Object result = method.invoke(target, args);
        cache.put(cacheKey, result);
        return result;
    }
 
    // 技巧3：根据注解做拦截
    // 检查方法上是否标注了自定义注解
    if (method.isAnnotationPresent(RequiresAuth.class)) {
        // 执行权限校验逻辑
        if (!SecurityContext.isAuthenticated()) {
            throw new SecurityException("未登录，无权访问: " + method.getName());
        }
    }
 
    // 默认：直接转发给真实对象
    return method.invoke(target, args);
}

// 情况1：方法返回 void
// method.invoke() 返回 null，你也应该返回 null
// 如果返回了非 null 值，JVM 会忽略它（因为调用方不接收返回值）
 
// 情况2：方法返回基本类型（int, boolean 等）
// method.invoke() 返回的是包装类型（Integer, Boolean）
// 你必须返回正确的包装类型，不能返回 null！
// 返回 null 会导致拆箱时 NullPointerException
 
// ❌ 危险：如果真实方法返回 int，这里返回 null 会 NPE
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    if (someCondition) {
        return null; // 💥 如果方法签名是 int findCount()，调用方拆箱时 NPE
    }
    return method.invoke(target, args);
}

// 使用 Lambda 表达式直接创建代理，适合简单的增强逻辑
UserService proxy = (UserService) Proxy.newProxyInstance(
    UserService.class.getClassLoader(),
    new Class<?>[]{ UserService.class },
    // Lambda 实现 InvocationHandler
    (proxyObj, method, methodArgs) -> {
        // 前置：打印方法名
        System.out.println("调用: " + method.getName());
        // 转发给真实对象
        Object result = method.invoke(realService, methodArgs);
        // 后置：打印结果
        System.out.println("结果: " + result);
        // 返回真实结果
        return result;
    }
);

public class ProxyFactory {
 
    /**
     * 创建动态代理的通用工厂方法
     *
     * @param target 被代理的真实对象
     * @param handler 调用处理器
     * @param <T> 接口类型
     * @return 代理对象，类型安全
     */
    @SuppressWarnings("unchecked")
    public static <T> T createProxy(T target, InvocationHandler handler) {
        // 获取目标对象实现的所有接口
        Class<?>[] interfaces = target.getClass().getInterfaces();
        // 使用目标对象的类加载器
        ClassLoader loader = target.getClass().getClassLoader();
        // 创建并返回代理对象，强转为接口类型 T
        return (T) Proxy.newProxyInstance(loader, interfaces, handler);
    }
}

// 使用工厂方法，一行搞定
UserService proxy = ProxyFactory.createProxy(
    new UserServiceImpl(),
    new LoggingHandler(new UserServiceImpl())
);

// 在 main 方法最开头加上这行，JVM 就会把生成的 $Proxy0.class 写到磁盘
// JDK 8 及以前使用此属性
System.getProperties().put("sun.misc.ProxyGenerator.saveGeneratedFiles", "true");
 
// JDK 11+ 改为此属性（包名变了）
// System.getProperties().put("jdk.proxy.ProxyGenerator.saveGeneratedFiles", "true");

import sun.misc.ProxyGenerator; // JDK 8
import java.io.FileOutputStream;
 
public class ProxyClassDumper {
    public static void main(String[] args) throws Exception {
        // 手动生成代理类的字节码，参数1是类名，参数2是要代理的接口数组
        byte[] classBytes = ProxyGenerator.generateProxyClass(
                "$Proxy0",                          // 生成的代理类名
                new Class[]{UserService.class}      // 要代理的接口列表
        );
 
        // 将字节码写入 .class 文件
        try (FileOutputStream fos = new FileOutputStream("$Proxy0.class")) {
            fos.write(classBytes); // 写入磁盘后可用 javap 或 IDEA 反编译查看
        }
 
        System.out.println("代理类字节码已保存，大小: " + classBytes.length + " bytes");
    }
}

// 被代理的接口
public interface UserService {
    void addUser(String name);    // 添加用户
    String findUser(int id);      // 根据ID查找用户
}

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.lang.reflect.UndeclaredThrowableException;
 
// 关键点1: 继承了 Proxy 类（这是 JDK 动态代理的基石）
// 关键点2: 实现了我们指定的 UserService 接口
public final class $Proxy0 extends Proxy implements UserService {
 
    // ========== 静态字段：缓存所有需要拦截的 Method 对象 ==========
    private static Method m0; // hashCode 方法的 Method 对象
    private static Method m1; // equals 方法的 Method 对象
    private static Method m2; // toString 方法的 Method 对象
    private static Method m3; // addUser 方法的 Method 对象（业务方法）
    private static Method m4; // findUser 方法的 Method 对象（业务方法）
 
    // ========== 构造方法 ==========
    // 接收一个 InvocationHandler，传给父类 Proxy 保存
    public $Proxy0(InvocationHandler h) {
        super(h); // Proxy 类中有一个 protected InvocationHandler h 字段
    }
 
    // ========== 业务方法: addUser ==========
    @Override
    public final void addUser(String name) {
        try {
            // 核心: 把调用全部委托给 InvocationHandler.invoke()
            // 参数1: this —— 代理对象本身
            // 参数2: m3 —— addUser 对应的 Method 对象
            // 参数3: new Object[]{name} —— 方法参数打包成数组
            super.h.invoke(this, m3, new Object[]{name});
        } catch (RuntimeException | Error e) {
            throw e;                          // 运行时异常直接抛出
        } catch (Throwable t) {
            throw new UndeclaredThrowableException(t); // 受检异常包装后抛出
        }
    }
 
    // ========== 业务方法: findUser ==========
    @Override
    public final String findUser(int id) {
        try {
            // 同样委托给 handler，注意基本类型 int 会被自动装箱为 Integer
            return (String) super.h.invoke(this, m4, new Object[]{Integer.valueOf(id)});
        } catch (RuntimeException | Error e) {
            throw e;
        } catch (Throwable t) {
            throw new UndeclaredThrowableException(t);
        }
    }
 
    // ========== Object 方法: hashCode ==========
    @Override
    public final int hashCode() {
        try {
            // 连 hashCode 也走 handler，这意味着你可以拦截它
            return (Integer) super.h.invoke(this, m0, null);
        } catch (RuntimeException | Error e) {
            throw e;
        } catch (Throwable t) {
            throw new UndeclaredThrowableException(t);
        }
    }
 
    // ========== Object 方法: equals ==========
    @Override
    public final boolean equals(Object obj) {
        try {
            return (Boolean) super.h.invoke(this, m1, new Object[]{obj});
        } catch (RuntimeException | Error e) {
            throw e;
        } catch (Throwable t) {
            throw new UndeclaredThrowableException(t);
        }
    }
 
    // ========== Object 方法: toString ==========
    @Override
    public final String toString() {
        try {
            return (String) super.h.invoke(this, m2, null);
        } catch (RuntimeException | Error e) {
            throw e;
        } catch (Throwable t) {
            throw new UndeclaredThrowableException(t);
        }
    }
 
    // ========== 静态初始化块：通过反射获取所有 Method 对象并缓存 ==========
    static {
        try {
            // 从 Object.class 获取三个基础方法
            m0 = Class.forName("java.lang.Object").getMethod("hashCode");
            m1 = Class.forName("java.lang.Object").getMethod("equals", Class.forName("java.lang.Object"));
            m2 = Class.forName("java.lang.Object").getMethod("toString");
 
            // 从 UserService 接口获取业务方法
            m3 = Class.forName("UserService").getMethod("addUser", Class.forName("java.lang.String"));
            m4 = Class.forName("UserService").getMethod("findUser", Integer.TYPE);
        } catch (NoSuchMethodException e) {
            throw new NoSuchMethodError(e.getMessage());  // 方法不存在
        } catch (ClassNotFoundException e) {
            throw new NoClassDefFoundError(e.getMessage()); // 类不存在
        }
    }
}

public final void addUser(String name) { ... }  // final!
public final int hashCode() { ... }              // final!

// findUser(int id) 中，int 被装箱为 Integer 传入 invoke
super.h.invoke(this, m4, new Object[]{Integer.valueOf(id)});
 
// invoke 返回 Object，$Proxy0 负责强转回 String
return (String) super.h.invoke(this, m4, ...);
 
// 如果返回值是 int，则会拆箱
// return ((Integer) super.h.invoke(this, m, args)).intValue();

try {
    super.h.invoke(this, m3, args);
} catch (RuntimeException | Error e) {
    throw e;                              // 非受检异常：直接抛，不包装
} catch (Throwable t) {
    throw new UndeclaredThrowableException(t); // 受检异常：包装后抛
}

// ============ $Proxy0 对象在堆内存中的布局 ============
//
//  $Proxy0 实例 (堆内存)
//  ┌─────────────────────────────────────────────┐
//  │  [对象头]  Mark Word + Klass Pointer         │
//  ├─────────────────────────────────────────────┤
//  │  继承自 Proxy 的实例字段:                      │
//  │    h ──────────────────┐                     │
//  │  (InvocationHandler)   │                     │
//  └────────────────────────┼────────────────────┘
//                           │
//                           ▼
//  ┌─────────────────────────────────────────────┐
//  │  MyInvocationHandler 实例                     │
//  ├─────────────────────────────────────────────┤
//  │    target ─────────────┐                     │
//  │  (Object, 真实对象引用)  │                     │
//  └────────────────────────┼────────────────────┘
//                           │
//                           ▼
//  ┌─────────────────────────────────────────────┐
//  │  UserServiceImpl 实例 (真实业务对象)            │
//  ├─────────────────────────────────────────────┤
//  │    实际的业务字段和方法实现                      │
//  └─────────────────────────────────────────────┘
//
//  $Proxy0.class (方法区/元空间)
//  ┌─────────────────────────────────────────────┐
//  │  static Method m0 → Object.hashCode()        │
//  │  static Method m1 → Object.equals()          │
//  │  static Method m2 → Object.toString()        │
//  │  static Method m3 → UserService.addUser()    │
//  │  static Method m4 → UserService.findUser()   │
//  └─────────────────────────────────────────────┘

public final class $Proxy0 extends Proxy implements UserService { ... }

public class UserServiceImpl {
    public void addUser(String name) {
        System.out.println("添加用户: " + name);
    }
}
 
public class FailDemo {
    public static void main(String[] args) {
        UserServiceImpl target = new UserServiceImpl();
 
        // 尝试用 JDK 动态代理代理一个类（而非接口）
        Object proxy = Proxy.newProxyInstance(
                target.getClass().getClassLoader(),
                new Class[]{UserServiceImpl.class},   // 传入的是类，不是接口！
                (p, method, a) -> method.invoke(target, a)
        );
        // 运行结果: 抛出 IllegalArgumentException
        // "UserServiceImpl is not an interface"
    }
}

// Proxy.java 源码片段（简化）
for (Class<?> intf : interfaces) {
    // 校验: 必须是接口类型
    if (!intf.isInterface()) {
        throw new IllegalArgumentException(intf.getName() + " is not an interface");
    }
}

// 第一步: 提取接口
public interface UserService {
    void addUser(String name);   // 把需要代理的方法抽到接口中
    String findUser(int id);
}
 
// 第二步: 让实现类实现该接口
public class UserServiceImpl implements UserService {
    @Override
    public void addUser(String name) {
        System.out.println("添加用户: " + name); // 真实业务逻辑
    }
 
    @Override
    public String findUser(int id) {
        return "User-" + id; // 真实业务逻辑
    }
}
 
// 第三步: 现在可以用 JDK 动态代理了
public class ProxyDemo {
    public static void main(String[] args) {
        UserService target = new UserServiceImpl(); // 真实对象
 
        // 代理的是 UserService 接口，不是 UserServiceImpl 类
        UserService proxy = (UserService) Proxy.newProxyInstance(
                target.getClass().getClassLoader(),
                new Class[]{UserService.class},       // 传入接口
                (p, method, a) -> {
                    System.out.println("[前置] " + method.getName());
                    Object result = method.invoke(target, a); // 反射调用真实对象
                    System.out.println("[后置] " + method.getName());
                    return result;
                }
        );
 
        proxy.addUser("Tom");     // 走代理
        proxy.findUser(1);        // 走代理
    }
}

// 定义两个接口
public interface Readable {
    String read();   // 读取操作
}
 
public interface Writable {
    void write(String data); // 写入操作
}
 
// 同时代理两个接口
public class MultiInterfaceDemo {
    public static void main(String[] args) {
        Object proxy = Proxy.newProxyInstance(
                MultiInterfaceDemo.class.getClassLoader(),
                new Class[]{Readable.class, Writable.class}, // 传入两个接口
                (p, method, a) -> {
                    System.out.println("拦截方法: " + method.getName());
                    if (method.getReturnType() == String.class) {
                        return "代理返回值";  // 为有返回值的方法提供默认值
                    }
                    return null;
                }
        );
 
        // 生成的代理类: $Proxy0 extends Proxy implements Readable, Writable
        // 可以同时转型为两个接口
        Readable reader = (Readable) proxy;
        Writable writer = (Writable) proxy;
 
        reader.read();            // 拦截方法: read
        writer.write("hello");    // 拦截方法: write
 
        // 验证代理类信息
        System.out.println("代理类名: " + proxy.getClass().getName());
        // 输出: com.sun.proxy.$Proxy0
 
        // 验证实现的接口
        for (Class<?> iface : proxy.getClass().getInterfaces()) {
            System.out.println("实现接口: " + iface.getName());
        }
        // 输出: Readable
        // 输出: Writable
    }
}

UserService proxy = (UserService) Proxy.newProxyInstance(...);
 
// 正确: 转型为接口
UserService service = proxy;  // OK
 
// 错误: 转型为实现类 —— ClassCastException!
UserServiceImpl impl = (UserServiceImpl) proxy;
// 因为 $Proxy0 和 UserServiceImpl 没有任何继承关系
// $Proxy0 extends Proxy implements UserService
// UserServiceImpl implements UserService
// 它们是"兄弟"关系，不是父子关系

//              UserService (接口)
//               /          \
//              /            \
//     $Proxy0                UserServiceImpl
//   (extends Proxy)          (业务实现类)
//
//  $Proxy0 和 UserServiceImpl 是"兄弟"，不能互相转型！
//  它们唯一的共同点是都实现了 UserService 接口

// 注意：这个类没有实现任何接口
// 这正是 JDK 动态代理无法处理的场景
public class UserService {
 
    // 一个普通的业务方法
    public String findUser(String userId) {
        System.out.println("执行真实查询: userId=" + userId);
        return "User-" + userId;
    }
 
    // 另一个业务方法
    public void saveUser(String name) {
        System.out.println("保存用户: " + name);
    }
}

import net.sf.cglib.proxy.MethodInterceptor;
import net.sf.cglib.proxy.MethodProxy;
import java.lang.reflect.Method;
 
// MethodInterceptor 是 CGLIB 的核心回调接口
// 类比 JDK 动态代理中的 InvocationHandler
public class LogInterceptor implements MethodInterceptor {
 
    /**
     * 所有被代理方法的调用都会进入这个 intercept 方法
     *
     * @param obj       代理对象本身（即生成的子类实例）
     * @param method    被拦截的原始 Method 对象（反射）
     * @param args      方法参数数组
     * @param proxy     MethodProxy 对象，用于调用父类的原始方法
     * @return          方法的返回值
     */
    @Override
    public Object intercept(Object obj, Method method, Object[] args,
                            MethodProxy proxy) throws Throwable {
 
        // ===== 前置增强 =====
        System.out.println("[CGLIB 前置] 方法: " + method.getName()
                + ", 参数: " + java.util.Arrays.toString(args));
 
        // 记录方法开始时间
        long startTime = System.currentTimeMillis();
 
        // ===== 调用目标类的原始方法 =====
        // 注意这里用的是 proxy.invokeSuper(obj, args)
        // 而不是 method.invoke(target, args)
        // invokeSuper 直接调用父类方法，不经过反射，性能更好
        Object result = proxy.invokeSuper(obj, args);
 
        // ===== 后置增强 =====
        long cost = System.currentTimeMillis() - startTime;
        System.out.println("[CGLIB 后置] 方法: " + method.getName()
                + ", 返回: " + result + ", 耗时: " + cost + "ms");
 
        // 返回原始方法的返回值
        return result;
    }
}

import net.sf.cglib.proxy.Enhancer;
 
public class CglibDemo {
 
    public static void main(String[] args) {
 
        // 1. 创建 Enhancer 实例（类比 JDK 的 Proxy 类）
        Enhancer enhancer = new Enhancer();
 
        // 2. 设置父类（即要代理的目标类）
        //    CGLIB 会生成这个类的子类作为代理
        enhancer.setSuperclass(UserService.class);
 
        // 3. 设置回调拦截器（类比 JDK 的 InvocationHandler）
        enhancer.setCallback(new LogInterceptor());
 
        // 4. 创建代理对象（实际类型是 UserService 的子类）
        //    内部流程：ASM 生成子类字节码 -> 加载到 JVM -> 实例化
        UserService proxy = (UserService) enhancer.create();
 
        // 5. 调用代理对象的方法
        //    实际执行的是子类重写后的方法 -> 进入 intercept()
        String user = proxy.findUser("1001");
        System.out.println("最终结果: " + user);
 
        System.out.println("---分割线---");
 
        proxy.saveUser("张三");
 
        // 验证代理对象的真实类型
        System.out.println("代理类名: " + proxy.getClass().getName());
        // 输出类似: UserService$$EnhancerByCGLIB$$a1b2c3d4
    }
}

[CGLIB 前置] 方法: findUser, 参数: [1001]
执行真实查询: userId=1001
[CGLIB 后置] 方法: findUser, 返回: User-1001, 耗时: 1ms
最终结果: User-1001
---分割线---
[CGLIB 前置] 方法: saveUser, 参数: [张三]
保存用户: 张三
[CGLIB 后置] 方法: saveUser, 返回: null, 耗时: 0ms
代理类名: UserService$$EnhancerByCGLIB$$a1b2c3d4

// CGLIB 动态生成的子类（简化还原）
// 类名格式: 目标类名$$EnhancerByCGLIB$$哈希值
public class UserService$$EnhancerByCGLIB$$a1b2c3d4
        extends UserService {  // 继承目标类
 
    // CGLIB 注入的拦截器引用
    private MethodInterceptor callback;
 
    // CGLIB 为每个方法生成对应的 MethodProxy（用于 FastClass 快速调用）
    private static final MethodProxy FIND_USER_PROXY;
    private static final MethodProxy SAVE_USER_PROXY;
 
    // 静态初始化块中创建 MethodProxy
    static {
        // MethodProxy.create 会同时生成两个 FastClass：
        // 一个用于目标类，一个用于代理类
        FIND_USER_PROXY = MethodProxy.create(
            UserService.class,                              // 父类
            UserService$$EnhancerByCGLIB$$a1b2c3d4.class,  // 代理类
            "(Ljava/lang/String;)Ljava/lang/String;",       // 方法签名
            "findUser",                                     // 父类方法名
            "CGLIB$findUser$0"                              // 代理类中的 super 调用桥接方法名
        );
        // saveUser 的 MethodProxy 同理...
    }
 
    // ===== 重写父类方法 =====
    @Override
    public String findUser(String userId) {
        // 如果设置了拦截器，走拦截逻辑
        if (this.callback != null) {
            // 调用拦截器的 intercept 方法
            return (String) this.callback.intercept(
                this,                    // 代理对象自身
                findUserMethod,          // 原始 Method 对象
                new Object[]{userId},    // 参数数组
                FIND_USER_PROXY          // MethodProxy
            );
        }
        // 没有拦截器则直接调用父类原始实现
        return super.findUser(userId);
    }
 
    // ===== CGLIB 生成的桥接方法 =====
    // invokeSuper 最终调用的就是这个方法
    // 它直接调用 super，绕过了重写的 findUser，避免无限递归
    final String CGLIB$findUser$0(String userId) {
        return super.findUser(userId);
    }
 
    // saveUser 的重写和桥接方法同理...
}

// FastClass 的核心原理（简化还原）
// CGLIB 为目标类自动生成的 FastClass
public class UserService$$FastClassByCGLIB$$xxxx extends FastClass {
 
    // 根据方法签名返回索引号
    @Override
    public int getIndex(String methodName, Class[] paramTypes) {
        // "findUser" + [String.class] -> 索引 0
        // "saveUser" + [String.class] -> 索引 1
        // ...
        if ("findUser".equals(methodName)) return 0;
        if ("saveUser".equals(methodName)) return 1;
        return -1;
    }
 
    // 根据索引直接调用对应方法，无需反射
    @Override
    public Object invoke(int index, Object obj, Object[] args) {
        UserService target = (UserService) obj;
        switch (index) {
            case 0:
                // 直接方法调用，不是反射！
                return target.findUser((String) args[0]);
            case 1:
                target.saveUser((String) args[0]);
                return null;
            default:
                throw new IllegalArgumentException("No such method index: " + index);
        }
    }
}

// ===== 限制 1: 无法代理 final 类 =====
// final 类不能被继承，CGLIB 无法生成子类
public final class FinalService {
    public void doSomething() { }
}
// enhancer.setSuperclass(FinalService.class);
// 运行时抛出: java.lang.IllegalArgumentException:
// Cannot subclass final class FinalService
 
// ===== 限制 2: 无法代理 final 方法 =====
public class SomeService {
    // final 方法不能被子类重写
    // CGLIB 不会报错，但这个方法不会被拦截
    // 调用时直接执行原始逻辑，拦截器不生效
    public final String getConfig() {
        return "original config";
    }
 
    // 普通方法可以正常被代理
    public String getData() {
        return "data";
    }
}
 
// ===== 限制 3: 无法代理 private 方法 =====
// private 方法对子类不可见，无法重写
// 同样不会报错，但拦截器不会生效
 
// ===== 限制 4: 构造函数会被调用 =====
// CGLIB 生成子类实例时，会调用父类的构造函数
// 如果构造函数中有重量级初始化逻辑，需要注意
public class HeavyService {
    public HeavyService() {
        // 这段代码在创建代理时也会执行！
        System.out.println("执行了重量级初始化...");
        // 比如建立数据库连接、加载大量配置等
    }
}

// Spring 的代理选择逻辑（伪代码还原）
public class DefaultAopProxyFactory implements AopProxyFactory {
 
    @Override
    public AopProxy createAopProxy(AdvisedSupport config) {
 
        // 条件判断：什么时候用 CGLIB？
        if (config.isOptimize()                    // 开启了优化
            || config.isProxyTargetClass()          // 显式配置了 proxyTargetClass=true
            || hasNoUserSuppliedProxyInterfaces(config)) {  // 目标类没有实现接口
 
            Class<?> targetClass = config.getTargetClass();
 
            // 即使配置了用 CGLIB，如果目标本身是接口，还是用 JDK
            if (targetClass.isInterface()
                || Proxy.isProxyClass(targetClass)) {
                return new JdkDynamicAopProxy(config);
            }
 
            // 使用 CGLIB 代理
            return new ObjenesisCglibAopProxy(config);
        }
 
        // 默认：使用 JDK 动态代理
        return new JdkDynamicAopProxy(config);
    }
}

// application.properties
// spring.aop.proxy-target-class=false
 
// 或者在配置类上
// @EnableAspectJAutoProxy(proxyTargetClass = false)

// ❌ 传统方式：日志代码与业务代码严重耦合
public class OrderService {
 
    // 创建订单
    public void createOrder(Order order) {
        long start = System.currentTimeMillis();           // 性能监控代码
        logger.info("开始创建订单: " + order.getId());      // 日志代码
        checkPermission();                                  // 权限校验代码
        beginTransaction();                                 // 事务代码
 
        // ====== 真正的业务逻辑只有这几行 ======
        orderDao.insert(order);
        inventoryService.deduct(order.getItems());
        // ====================================
 
        commitTransaction();                                // 事务代码
        logger.info("订单创建完成，耗时: "
            + (System.currentTimeMillis() - start) + "ms"); // 日志 + 性能监控
    }
 
    // 取消订单 —— 又要重复写一遍同样的"横切"代码
    public void cancelOrder(String orderId) {
        long start = System.currentTimeMillis();            // 又来了...
        logger.info("开始取消订单: " + orderId);
        checkPermission();
        beginTransaction();
 
        // ====== 业务逻辑 ======
        orderDao.updateStatus(orderId, CANCELLED);
        // =====================
 
        commitTransaction();
        logger.info("订单取消完成，耗时: "
            + (System.currentTimeMillis() - start) + "ms");
    }
}

// Spring AOP 中五种通知类型的注解形式
@Aspect  // 声明这是一个切面类
public class LogAspect {
 
    // 1. 前置通知：目标方法执行之前触发
    @Before("execution(* com.example.service.*.*(..))")
    public void beforeAdvice(JoinPoint jp) {
        // jp.getSignature() 获取被拦截方法的签名信息
        System.out.println("[Before] 即将执行: " + jp.getSignature().getName());
    }
 
    // 2. 后置通知（返回通知）：目标方法正常返回之后触发
    @AfterReturning(
        pointcut = "execution(* com.example.service.*.*(..))",
        returning = "result"  // 绑定返回值到参数 result
    )
    public void afterReturningAdvice(JoinPoint jp, Object result) {
        System.out.println("[AfterReturning] 方法返回: " + result);
    }
 
    // 3. 异常通知：目标方法抛出异常时触发
    @AfterThrowing(
        pointcut = "execution(* com.example.service.*.*(..))",
        throwing = "ex"  // 绑定异常对象到参数 ex
    )
    public void afterThrowingAdvice(JoinPoint jp, Exception ex) {
        System.out.println("[AfterThrowing] 方法异常: " + ex.getMessage());
    }
 
    // 4. 最终通知：无论正常返回还是异常，都会触发（类似 finally）
    @After("execution(* com.example.service.*.*(..))")
    public void afterAdvice(JoinPoint jp) {
        System.out.println("[After] 方法执行结束（finally）");
    }
 
    // 5. 环绕通知：最强大的通知类型，完全包裹目标方法
    @Around("execution(* com.example.service.*.*(..))")
    public Object aroundAdvice(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();              // 前置逻辑
        System.out.println("[Around] 方法开始: " + pjp.getSignature().getName());
 
        Object result = pjp.proceed();                        // 调用目标方法（关键！）
 
        long elapsed = System.currentTimeMillis() - start;    // 后置逻辑
        System.out.println("[Around] 方法结束，耗时: " + elapsed + "ms");
        return result;                                         // 必须返回结果
    }
}

// 业务接口
public interface UserService {
    void addUser(String username);    // 添加用户
    String findUser(String userId);   // 查找用户
}
 
// 业务实现类（目标对象）
public class UserServiceImpl implements UserService {
 
    @Override
    public void addUser(String username) {
        // 纯粹的业务逻辑，没有任何日志、事务等横切代码
        System.out.println("执行业务逻辑：添加用户 [" + username + "] 到数据库");
    }
 
    @Override
    public String findUser(String userId) {
        System.out.println("执行业务逻辑：根据ID [" + userId + "] 查询用户");
        return "User_" + userId;  // 模拟返回用户信息
    }
}

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
 
/**
 * AOP 代理处理器 —— 这就是"切面"的运行时载体
 * 它将横切逻辑（日志、性能监控）与目标对象的调用编织在一起
 */
public class AopInvocationHandler implements InvocationHandler {
 
    // 持有目标对象的引用（即被代理的真实业务对象）
    private final Object target;
 
    // 通过构造器注入目标对象
    public AopInvocationHandler(Object target) {
        this.target = target;
    }
 
    /**
     * 所有对代理对象的方法调用都会被路由到这里
     * 这个方法就是"织入点"，我们在这里编排通知的执行顺序
     *
     * @param proxy  生成的代理对象实例（一般不直接使用）
     * @param method 被调用的目标方法的反射对象
     * @param args   方法调用时传入的参数数组
     * @return       目标方法的返回值（可被修改）
     */
    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
 
        // ========== @Before 前置通知 ==========
        String methodName = method.getName();                          // 获取方法名
        System.out.println("[LOG-Before] 准备执行方法: " + methodName); // 日志记录
        long startTime = System.currentTimeMillis();                   // 记录开始时间
 
        Object result = null;  // 用于保存目标方法的返回值
 
        try {
            // ========== 调用目标方法（相当于 proceed()）==========
            result = method.invoke(target, args);
            // method.invoke() 通过反射调用目标对象的真实方法
            // target 是真实的业务对象，args 是原始参数
 
            // ========== @AfterReturning 返回通知 ==========
            System.out.println("[LOG-AfterReturning] 方法正常返回: " + result);
 
        } catch (Exception e) {
            // ========== @AfterThrowing 异常通知 ==========
            System.out.println("[LOG-AfterThrowing] 方法抛出异常: " + e.getCause());
            throw e;  // 重新抛出，不吞掉异常
 
        } finally {
            // ========== @After 最终通知 ==========
            long elapsed = System.currentTimeMillis() - startTime;     // 计算耗时
            System.out.println("[LOG-After] 方法 " + methodName
                + " 执行完毕，耗时: " + elapsed + "ms");
        }
 
        return result;  // 将目标方法的返回值传递回调用方
    }
 
    /**
     * 工厂方法：创建代理对象
     * 这个方法封装了 Proxy.newProxyInstance 的调用细节
     *
     * @param target 需要被代理的目标对象
     * @return       代理对象（类型为目标对象实现的接口）
     */
    @SuppressWarnings("unchecked")
    public static <T> T createProxy(T target) {
        return (T) Proxy.newProxyInstance(
            target.getClass().getClassLoader(),     // 使用目标对象的类加载器
            target.getClass().getInterfaces(),      // 获取目标对象实现的所有接口
            new AopInvocationHandler(target)        // 传入我们的 AOP 处理器
        );
    }
}

public class AopDemo {
    public static void main(String[] args) {
        // 1. 创建目标对象（真实的业务对象）
        UserService realService = new UserServiceImpl();
 
        // 2. 通过 AOP 工厂方法创建代理对象
        //    此时 proxyService 的类型是 $Proxy0，不是 UserServiceImpl
        UserService proxyService = AopInvocationHandler.createProxy(realService);
 
        // 3. 通过代理对象调用业务方法
        //    调用方完全不知道日志、性能监控等逻辑的存在
        System.out.println("===== 调用 addUser =====");
        proxyService.addUser("张三");
 
        System.out.println();
 
        System.out.println("===== 调用 findUser =====");
        String user = proxyService.findUser("1001");
        System.out.println("查询结果: " + user);
    }
}

// 模拟 Spring 内部的拦截器链执行机制
public class InterceptorChainDemo {
 
    // 拦截器接口（简化版的 MethodInterceptor）
    interface MethodInterceptor {
        Object invoke(MethodInvocation invocation) throws Throwable;
    }
 
    // 方法调用链（简化版的 ReflectiveMethodInvocation）
    static class MethodInvocation {
        private final Object target;                          // 目标对象
        private final List<MethodInterceptor> interceptors;   // 拦截器列表
        private int currentIndex = -1;                        // 当前执行到第几个拦截器
 
        MethodInvocation(Object target, List<MethodInterceptor> interceptors) {
            this.target = target;
            this.interceptors = interceptors;
        }
 
        // 推进到下一个拦截器，或者调用目标方法
        public Object proceed() throws Throwable {
            currentIndex++;  // 指针后移
 
            // 如果所有拦截器都执行完了，调用目标方法
            if (currentIndex == interceptors.size()) {
                System.out.println("  >>> 执行目标方法 <<<");
                return "目标方法返回值";
            }
 
            // 否则，执行当前拦截器，并把自身（链）传递进去
            // 拦截器内部会在适当时机再次调用 proceed() 推进链条
            return interceptors.get(currentIndex).invoke(this);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        // 构建拦截器链：日志切面 -> 事务切面 -> 目标方法
        List<MethodInterceptor> chain = List.of(
            // 第一层：日志拦截器（@Order(1)，最外层）
            invocation -> {
                System.out.println("[日志切面] Before - 进入");
                Object result = invocation.proceed();          // 推进到下一个拦截器
                System.out.println("[日志切面] After  - 退出");
                return result;
            },
            // 第二层：事务拦截器（@Order(2)，内层）
            invocation -> {
                System.out.println("  [事务切面] Before - 开启事务");
                Object result = invocation.proceed();          // 推进到目标方法
                System.out.println("  [事务切面] After  - 提交事务");
                return result;
            }
        );
 
        // 执行拦截器链
        MethodInvocation invocation = new MethodInvocation(new Object(), chain);
        Object result = invocation.proceed();  // 启动链条
        System.out.println("最终结果: " + result);
    }
}

@Service
public class OrderService {
 
    // 这个方法上配置了事务切面
    @Transactional
    public void createOrder(Order order) {
        orderDao.insert(order);
        // 内部调用同类的另一个方法
        // ⚠️ 这里的 this 是原始对象，不是代理对象！
        this.sendNotification(order);
    }
 
    // 这个方法上也配置了事务切面（比如要求新事务 REQUIRES_NEW）
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void sendNotification(Order order) {
        // 期望在新事务中执行，但实际上事务注解不会生效！
        notificationDao.insert(new Notification(order));
    }
}

// 内存引用关系示意
 
// Spring 容器中注册的是代理对象
// IoC Container
// ┌─────────────────────────────────────────────────┐
// │  "orderService" -> [Proxy$OrderService]         │
// │                        │                        │
// │                        │ 持有引用               │
// │                        ▼                        │
// │                   [OrderService 真实对象]        │
// └─────────────────────────────────────────────────┘
//
// 外部调用链路（AOP 生效 ✅）：
//   Client -> Proxy.createOrder() -> 拦截器链 -> target.createOrder()
//
// 内部调用链路（AOP 失效 ❌）：
//   target.createOrder() 内部执行 this.sendNotification()
//   此时 this = target（真实对象），不经过 Proxy，拦截器链被绕过

// 方案一：注入自身代理（推荐）
@Service
public class OrderService {
 
    @Autowired
    private OrderService self;  // Spring 注入的是代理对象，不是 this
 
    @Transactional
    public void createOrder(Order order) {
        orderDao.insert(order);
        // 通过代理对象调用，AOP 生效 ✅
        self.sendNotification(order);
    }
 
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void sendNotification(Order order) {
        notificationDao.insert(new Notification(order));
    }
}
 
// 方案二：从 ApplicationContext 中获取代理
@Service
public class OrderService implements ApplicationContextAware {
 
    private ApplicationContext ctx;  // 持有容器引用
 
    @Override
    public void setApplicationContext(ApplicationContext ctx) {
        this.ctx = ctx;              // Spring 回调注入容器
    }
 
    @Transactional
    public void createOrder(Order order) {
        orderDao.insert(order);
        // 从容器中取出的是代理对象
        OrderService proxy = ctx.getBean(OrderService.class);
        proxy.sendNotification(order);  // AOP 生效 ✅
    }
}
 
// 方案三：使用 AopContext（需开启 exposeProxy）
// 配置：@EnableAspectJAutoProxy(exposeProxy = true)
@Transactional
public void createOrder(Order order) {
    orderDao.insert(order);
    // 从 ThreadLocal 中获取当前代理对象
    OrderService proxy = (OrderService) AopContext.currentProxy();
    proxy.sendNotification(order);  // AOP 生效 ✅
}

// ① 定义一个纯接口，用注解描述 HTTP 请求
public interface GitHubService {
 
    // GET 请求，路径为 /users/{user}/repos
    // {user} 是路径参数，由 @Path 注解绑定
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
 
    // POST 请求，@Body 注解表示将参数序列化为请求体
    @POST("users/new")
    Call<User> createUser(@Body User user);
}

// ② 构建 Retrofit 实例
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")       // 设置基础 URL
    .addConverterFactory(GsonConverterFactory.create()) // JSON 转换器
    .build();
 
// ③ 创建接口的实现——这一步就是动态代理！
GitHubService service = retrofit.create(GitHubService.class);
 
// ④ 调用方法，就像调用普通 Java 方法一样
Call<List<Repo>> call = service.listRepos("octocat");

// Retrofit.java 核心源码（简化版）
public <T> T create(final Class<T> service) {
 
    // 校验：传入的必须是一个接口（JDK 动态代理的硬性要求）
    validateServiceInterface(service);
 
    // 核心：使用 JDK 动态代理生成接口的实现
    return (T) Proxy.newProxyInstance(
        service.getClassLoader(),           // 类加载器
        new Class<?>[] { service },         // 要代理的接口数组
        new InvocationHandler() {           // 调用处理器——所有魔法在这里
            @Override
            public Object invoke(Object proxy, Method method, Object[] args)
                    throws Throwable {
 
                // 如果调用的是 Object 类的方法（如 toString），直接执行
                if (method.getDeclaringClass() == Object.class) {
                    return method.invoke(this, args);
                }
 
                // 核心逻辑：将 Method 对象解析为一个 ServiceMethod
                // ServiceMethod 封装了注解信息、参数处理、请求构建等全部逻辑
                ServiceMethod<Object, Object> serviceMethod =
                    (ServiceMethod<Object, Object>) loadServiceMethod(method);
 
                // 用 ServiceMethod + 实际参数 创建一个 OkHttpCall
                OkHttpCall<Object> okHttpCall =
                    new OkHttpCall<>(serviceMethod, args);
 
                // 通过 CallAdapter 适配返回类型（如 Call, Observable 等）
                return serviceMethod.adapt(okHttpCall);
            }
        });
}

// loadServiceMethod 的核心逻辑（简化）
ServiceMethod<?> loadServiceMethod(Method method) {
 
    // 先从缓存中查找，避免重复解析（性能优化的关键）
    ServiceMethod<?> result = serviceMethodCache.get(method);
    if (result != null) return result;
 
    synchronized (serviceMethodCache) {
        result = serviceMethodCache.get(method);
        if (result == null) {
            // 缓存未命中，开始解析
            result = ServiceMethod.parseAnnotations(this, method);
            // 解析完成后放入缓存
            serviceMethodCache.put(method, result);
        }
    }
    return result;
}

// 注解解析过程的伪代码展示
public static ServiceMethod parseAnnotations(Retrofit retrofit, Method method) {
 
    // 1. 获取方法上的所有注解
    Annotation[] methodAnnotations = method.getAnnotations();
 
    // 2. 遍历注解，提取 HTTP 方法和相对路径
    for (Annotation annotation : methodAnnotations) {
        if (annotation instanceof GET) {
            httpMethod = "GET";                    // HTTP 方法
            relativeUrl = ((GET) annotation).value(); // 相对路径: "users/{user}/repos"
        } else if (annotation instanceof POST) {
            httpMethod = "POST";
            relativeUrl = ((POST) annotation).value();
        }
        // ... 其他 HTTP 方法注解
    }
 
    // 3. 获取参数上的注解
    Annotation[][] paramAnnotations = method.getParameterAnnotations();
 
    // 4. 遍历每个参数的注解
    for (int i = 0; i < paramAnnotations.length; i++) {
        for (Annotation annotation : paramAnnotations[i]) {
            if (annotation instanceof Path) {
                // @Path("user") -> 记录：第 i 个参数替换 URL 中的 {user}
                String pathName = ((Path) annotation).value();
                parameterHandlers[i] = new ParameterHandler.Path<>(pathName);
            } else if (annotation instanceof Body) {
                // @Body -> 记录：第 i 个参数序列化为请求体
                parameterHandlers[i] = new ParameterHandler.Body<>(converter);
            } else if (annotation instanceof Query) {
                // @Query("page") -> 记录：第 i 个参数作为查询参数
                String queryName = ((Query) annotation).value();
                parameterHandlers[i] = new ParameterHandler.Query<>(queryName);
            }
        }
    }
 
    // 5. 将所有解析结果封装为 ServiceMethod 返回
    return new ServiceMethod<>(httpMethod, baseUrl, relativeUrl,
                               parameterHandlers, responseConverter);
}