java如何使用注解实现自定义拦截器 java注解拦截器实现的基础入门教程

蓮花仙者

发布时间：2025-08-01 21:22:01

1015人浏览过

来源于php中文网

原创

定义注解：创建一个运行时保留、作用于方法的自定义注解（如@loggable），用于标记需要拦截的方法；2. 编写切面：通过@aspect和@component定义切面类，使用@pointcut指定匹配规则，结合@around等通知类型实现环绕拦截逻辑，利用反射获取方法信息并执行前置、后置及异常处理操作；3. 配置与使用：在spring boot中引入aop依赖后自动启用代理，无需显式配置@enableaspectjautoproxy，直接在目标方法上添加自定义注解即可生效；4. 优势分析：注解方式具有声明式、非侵入性特点，避免了传统xml配置或接口实现带来的代码污染，提升业务逻辑纯净度与可维护性；5. 常见问题：包括内部方法调用不触发拦截（因代理失效）、多切面执行顺序需用@order控制、性能开销在高并发场景下需评估、以及过度使用导致代码隐式性增强增加调试难度；6. 扩展应用：除日志外，还可用于权限校验（如@requirespermission）、参数验证、性能监控、幂等控制、数据脱敏、接口限流和缓存管理等横切关注点，显著提升系统模块化程度与开发效率。

java如何使用注解实现自定义拦截器 java注解拦截器实现的基础入门教程

在Java中，利用注解实现自定义拦截器，本质上是运用了面向切面编程（AOP）的思想，通过定义一套声明式的规则，让程序在特定执行点（比如方法调用前后）自动插入预设的逻辑。这提供了一种极其优雅且非侵入性的方式来处理横切关注点，比如日志记录、权限校验、性能监控或事务管理，使得核心业务逻辑保持高度纯净，极大提升了代码的可读性、可维护性和模块化程度。

解决方案

要构建一个基于注解的自定义拦截器，我们通常会经历以下几个核心步骤：定义注解、编写切面（即拦截器逻辑）、以及配置（在Spring Boot等框架下通常是自动配置）。

首先，我们需要一个自定义注解来标记那些我们希望被拦截的方法或类。这个注解需要指定其作用范围（方法、类等）和生命周期。

立即学习“Java免费学习笔记（深入）”；

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 自定义日志注解，用于标记需要记录方法执行日志的方法
 */
@Target(ElementType.METHOD) // 作用于方法
@Retention(RetentionPolicy.RUNTIME) // 运行时有效，以便通过反射读取
public @interface Loggable {
    String value() default ""; // 可以带一个参数，比如日志描述
}

接着，就是编写实际的拦截逻辑了。这通常通过一个切面（Aspect）来完成，我们会在其中定义“切点”（Pointcut）来匹配带有我们自定义注解的方法，并定义“通知”（Advice）来指定在切点执行前、后或环绕执行的逻辑。这里以Spring AOP为例：

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.stereotype.Component;

import java.lang.reflect.Method;
import java.util.Arrays;

/**
 * 日志拦截切面
 */
@Aspect // 声明这是一个切面
@Component // 注册为Spring组件
public class LoggableAspect {

    // 定义切点，匹配所有带有 @Loggable 注解的方法
    @Pointcut("@annotation(com.example.demo.annotation.Loggable)")
    public void loggablePointcut() {
    }

    /**
     * 环绕通知：在方法执行前、后都执行逻辑
     * @param joinPoint 连接点，包含了被拦截方法的信息
     * @return 方法执行结果
     * @throws Throwable 异常
     */
    @Around("loggablePointcut()")
    public Object logMethodExecution(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        String methodName = method.getName();
        String className = method.getDeclaringClass().getSimpleName();
        Object[] args = joinPoint.getArgs();

        // 获取注解上的值
        Loggable loggable = method.getAnnotation(Loggable.class);
        String logDescription = loggable != null ? loggable.value() : "无描述";

        System.out.println(">>> 进入方法: " + className + "." + methodName + "(), 描述: " + logDescription + ", 参数: " + Arrays.toString(args));

        Object result = null;
        try {
            // 执行目标方法
            result = joinPoint.proceed();
            System.out.println("<<< 离开方法: " + className + "." + methodName + "(), 返回值: " + result);
        } catch (Throwable e) {
            System.err.println("!!! 方法异常: " + className + "." + methodName + "(), 异常信息: " + e.getMessage());
            throw e; // 重新抛出异常，让上层处理
        } finally {
            long endTime = System.currentTimeMillis();
            System.out.println("--- 方法执行耗时: " + (endTime - startTime) + "ms");
        }
        return result;
    }
}

最后，在你的Spring Boot应用中，你只需要确保你的主应用类上带有

@EnableAspectJAutoProxy

注解（在Spring Boot中，如果引入了

spring-boot-starter-aop

依赖，这个通常是自动配置的），然后就可以直接在需要拦截的方法上使用

@Loggable

注解了。

import org.springframework.stereotype.Service;
import com.example.demo.annotation.Loggable; // 假设你的注解包路径

@Service
public class MyBusinessService {

    @Loggable("处理用户订单")
    public String processOrder(String orderId, int quantity) {
        System.out.println("实际业务逻辑：正在处理订单 " + orderId + "，数量 " + quantity);
        if (quantity <= 0) {
            throw new IllegalArgumentException("数量必须大于0");
        }
        return "订单 " + orderId + " 处理成功";
    }

    @Loggable("查询商品信息")
    public String getProductInfo(String productId) {
        System.out.println("实际业务逻辑：查询商品 " + productId);
        return "商品[" + productId + "] 详情";
    }

    public void doSomethingElse() {
        System.out.println("这个方法没有注解，不会被拦截。");
    }
}

运行程序，调用

processOrder

或

getProductInfo

方法时，你就能看到切面中定义的日志输出了。

为什么选择注解来实现Java拦截器，它比传统方式有哪些优势？

选择注解来实现Java拦截器，在我看来，最显著的优势在于其无与伦比的“声明式”与“非侵入性”。想想看，过去我们可能需要通过XML配置一大堆Bean、代理，或者让业务类实现特定的接口，然后通过工厂模式来获取代理对象。这不仅让配置变得臃肿，更重要的是，它污染了业务代码。业务代码为了被拦截，不得不去感知拦截器的存在，这显然违背了单一职责原则。

注解则彻底改变了这一点。它就像给方法或类贴上了一个标签，告诉AOP框架：“嘿，这里需要特殊处理！”。业务代码本身不需要知道具体如何处理，也不需要引入额外的接口或基类。这种解耦使得业务逻辑保持了极高的纯净度，提高了代码的可读性和维护性。比如，一眼看到

@Loggable

，我就知道这个方法有日志切面在工作，而不需要去翻阅复杂的XML文件或者查看继承关系。

此外，注解方式也极大地简化了开发流程。在Spring Boot这类框架下，很多AOP配置都是自动化的，开发者只需要定义好注解和切面，几乎无需额外配置就能让拦截器生效。这比手动管理代理、配置拦截链条要高效太多了。它把原本复杂且重复的横切逻辑，转化成了一种直观、简洁的元数据声明。

自定义注解拦截器在实际开发中可能遇到哪些常见问题与挑战？

虽然注解拦截器非常强大，但在实际开发中，它也不是万能药，总会碰到一些让人挠头的问题。

DeepL

DeepL是一款强大的在线AI翻译工具，可以翻译31种不同语言的文本，并可以处理PDF、Word、PowerPoint等文档文件

下载

一个很常见的坑是“内部方法调用不被拦截”。比如，在一个Service类中，

methodA()

调用了同一个Service实例的

methodB()

，如果

methodB()

上有注解，但

methodA()

没有，那么

methodB()

的拦截器可能不会生效。这是因为Spring AOP默认是基于动态代理实现的（JDK动态代理或CGLIB），它只对外部调用有效。当

methodA()

调用

methodB()

时，它实际上是直接调用了原始对象的方法，而不是代理对象的方法。解决这个问题，通常需要通过

AopContext.currentProxy()

获取当前代理对象再调用，或者考虑引入AspectJ的编译时/加载时织入。

另一个挑战是“拦截器执行顺序”。当多个切面都匹配同一个方法时，它们的执行顺序可能会变得复杂。Spring AOP提供

@Order

注解来指定切面的优先级，数字越小优先级越高。但如果设计不当，不同的切面之间可能会产生意想不到的交互，甚至导致死循环或逻辑错误。这要求开发者在设计多个切面时，必须清晰地规划好它们的职责和执行顺序。

还有就是“性能开销”。虽然现代JVM和AOP框架对反射和代理的优化已经非常出色，但在极端高并发或对性能要求极高的场景下，过多的拦截器层层嵌套，依然可能带来额外的性能损耗。这通常不是一个大问题，但值得在性能敏感的模块中进行考量和测试。

最后，过度依赖AOP可能导致“代码的隐式性”增加，也就是所谓的“魔法”代码。虽然注解让代码看起来很干净，但如果滥用，开发者可能会忘记某个注解背后隐藏着复杂的逻辑，导致调试困难。当出现问题时，栈追踪会变得更长，更难定位到真正的业务逻辑错误。这要求我们在使用AOP时保持克制，只将真正属于横切关注点的逻辑放入其中。