Java自定义注解及使用场景

1. 简介

  Java注解又称Java标注，是JDK5.0版本开始支持加入源代码的特殊语法元数据。Java语言中的类、方法、变量、参数和包等都可以被标注。和Javadoc不同，Java标注可以通过反射获取标注内容。在编译器生成类文件时，标注可以被嵌入到字节码中。Java虚拟机可以保留标注内容，在运行时可以获取到标注内容。 当然它也支持自定义Java标注。

2. 元注解

java.lang.annotation中提供了元注解，可以使用这些注解来定义自己的注解。主要使用的是Target和Retention注解

2.1 @Document

  表明该注解标记的元素可以被Javadoc 或类似的工具文档化。

2.2 @Inherited

  @Inherited注解的注解，所标记的类的子类也会拥有这个注解。

2.3 @Native

  使用 @Native 注解修饰成员变量，则表示这个变量可以被本地代码引用，常常被代码生成工具使用。对于 @Native 注解不常使用，了解即可

2.4 @Repeatable

  允许在相同的程序元素中重复注解，在需要对同一种注解多次使用时，往往需要借助 @Repeatable 注解。Java 8 版本以前，同一个程序元素前最多只能有一个相同类型的注解，如果需要在同一个元素前使用多个相同类型的注解，则必须使用注解“容器”

Java 8 之前的做法

public @interface Role {
    String roleName();
}

public class RoleTest {
    @Roles(roles = {@Role(roleName = "role1"), @Role(roleName = "role2")})
    public String doString(){
        return "这是C语言中国网Java教程";
    }
}

java 8 之后增加了重复注解

@Repeatable(Roles.class)
public @interface Role {
    String roleName();
}

public class RoleTest {
    @Role(roleName = "role1")
    @Role(roleName = "role2")
    public String doString(){
        return "这是C语言中文网Java教程";
    }
}

2.5. @Retention

表明该注解的生命周期

生命周期类型	描述
RetentionPolicy.SOURCE	编译时被丢弃，不包含在类文件中
RetentionPolicy.CLASS	JVM加载时被丢弃，包含在类文件中，默认值
RetentionPolicy.RUNTIME	由JVM 加载，包含在类文件中，在运行时可以被获取到

2.6. @Retention

Target类型	描述
ElementType.TYPE	应用于类、接口（包括注解类型）、枚举
ElementType.FIELD	应用于属性（包括枚举中的常量）
ElementType.METHOD	应用于方法
ElementType.PARAMETER	应用于方法的形参
ElementType.CONSTRUCTOR	应用于构造函数
ElementType.LOCAL_VARIABLE	应用于局部变量
ElementType.ANNOTATION_TYPE	应用于注解类型
ElementType.PACKAGE	应用于包
ElementType.TYPE_PARAMETER	应用于类型变量
ElementType.TYPE_USE	应用于任何使用类型的语句中（例如声明语句、泛型和强制转换语句中的类型）

3. 注解的使用

既然上面定义了注解，那得有办法拿到我们定义的注解啊。java.lang.reflect.AnnotationElement接口则提供了该功能。注解的处理是通过java反射来处理的。如下，反射相关的类Class, Method, Field都实现了AnnotationElement接口。

因此，只要我们通过反射拿到Class, Method, Field类，就能够通过getAnnotation(Class)拿到我们想要的注解并取值。

4. 示例

先定义一个注解

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyFirstFieldAnnotation {

    String description();
    int length();
}

通过反射获取注解上的值

public class FieldTest {

    @MyFirstFieldAnnotation(description = "描述信息",length = 2)
    String name;

    @Test
    public void testFieldAnnotation() throws NoSuchFieldException {

        FieldTest fieldTest = new FieldTest();
        Class<FieldTest> fieldTestClass = FieldTest.class;
        //getField 只能获取public的，包括从父类继承来的字段。
        //getDeclaredField 可以获取本类所有的字段，包括private的，但是不能获取继承来的字段。 (注： 这里只能获取到private的字段，但并不能访问该private字段的值,除非加上setAccessible(true))
        Field nameField = fieldTestClass.getDeclaredField ("name");
        MyFirstFieldAnnotation annotation = nameField.getAnnotation(MyFirstFieldAnnotation.class);
        System.out.println(annotation.description());
        System.out.println(annotation.length());

    }

5. 应用场景

5.1 自定义注解+拦截器 实现登录校验

我们使用springboot拦截器实现这样一个功能，如果方法上加了@LoginRequired，则提示用户该接口需要登录才能访问，否则不需要登录。

自定义一个LoginRequired注解

package com.cjz.study.test02.annotation;

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 LoginRequired {
}

通过实现spring的HandlerInterceptor 定义拦截器

package com.cjz.study.test02.Interceptor;

import com.cjz.study.test02.annotation.LoginRequired;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;


public class WebInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        System.out.println("preHandle方法在业务处理器处理请求之前被调用");
        // 反射获取方法上的LoginRequred注解
        HandlerMethod handlerMethod = (HandlerMethod) handler;
        LoginRequired loginRequired = handlerMethod.getMethodAnnotation(LoginRequired.class);
        if (loginRequired == null) {
            return true;
        }

        // 有LoginRequired注解说明需要登录，提示用户登录
        response.setContentType("application/json; charset=utf-8");
        response.getWriter().print("你访问的资源需要登录");
        return false;

    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        System.out.println("postHandle方法在业务处理器处理请求执行完成后，生成视图之前执行");
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        System.out.println("afterCompletion方法在DispatcherServlet完全处理完请求后被调用，可用于清理资源等");
    }
}

实现spring类WebMvcConfigurer，创建配置类把拦截器添加到拦截器链中

package com.cjz.study.test02.config;

import com.cjz.study.test02.Interceptor.WebInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;


@Configuration
public class WebAppConfigurer implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //可添加多个
        registry.addInterceptor(new WebInterceptor()).addPathPatterns("/**");
    }
}

controller

package com.cjz.study.test02.controller;

import com.cjz.study.test02.Service.MyFirstAopService;
import com.cjz.study.test02.annotation.LoginRequired;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;


@RestController
public class MyFirstAopController {

    @Autowired
    MyFirstAopService myFirstAopService;

    @GetMapping(value = "/sourceA")
    @LoginRequired
    public String sourceA(){
        System.out.println("你正在访问资源A,service.test()前");
        System.out.println(myFirstAopService.test());
        System.out.println("你正在访问资源A,service.test()后");
        return "你正在访问资源A";
    }

    @GetMapping(value = "/sourceB")
    public String sourceB(){
        System.out.println("你正在访问资源B,service.test()前");
        System.out.println(myFirstAopService.test());
        System.out.println("你正在访问资源B,service.test()后");
        return "你正在访问资源B";
    }

}

业务类

package com.cjz.study.test02.Service;

import org.springframework.stereotype.Service;


@Service
public class MyFirstAopService {
    public String test(){
        System.out.println("这里是service.test()");
        return "test()";
    }
}

访问http://localhost:8080/sourceA

访问http://localhost:8080/sourceB

没有被拦截

5.2 自定义注解+AOP 实现日志打印

通过AOP设置所有带有@MyLog注解的方法为切点，然后通过AOP中的@Around的功能完成该方法的日志输出。

需要的依赖包

<dependency>
      <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

配置类

package com.cjz.study.test03.aspect;

import com.cjz.study.test03.annotation.MyLog;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.Signature;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;


@Aspect // 1.表明这是一个切面类
@Component
public class MyLogAspect {

    Logger logger = LoggerFactory.getLogger(MyLogAspect.class);


    /**
     * 2. PointCut 表示这是一个切点，@annotation表示这个切点切到一个注解上，后面带该注解的全类名
     * 切面主要的是切点，所有的都围绕切点发生
     */
    @Pointcut(value = "@annotation(myLog)")
    public void logPointCut(MyLog myLog) {

    }

    @Around(value = "logPointCut(myLog)", argNames = "joinPoint, myLog")
    public Object logAround(ProceedingJoinPoint joinPoint, MyLog myLog) {
        Signature signature = joinPoint.getSignature();
        String methodName = signature.getName();

        // 获取入参
        Object[] param = joinPoint.getArgs();
        StringBuilder sb = new StringBuilder();
        for (Object o : param) {
            sb.append(o).append("; ");
        }

        logger.info("进入{}方法，参数str值为{}", methodName, sb.toString());

        Object object = null;
        // 继续执行方法
        try {
            //接受方法的返回值
            object = joinPoint.proceed();
        } catch (Throwable throwable) {
            throwable.printStackTrace();
        }
        logger.info("{}方法执行结束", methodName);
        return object;
    }
}

相关业务

public interface TestLogService {

    void testLogAspect(String str);
}

@Service
public class TestLogServiceImpl implements TestLogService {
    @Override
    @MyLog
    public void testLogAspect(String str) {
        System.out.println(str);
    }
}

测试

 @Test
 public void testLogAspect(){
      testLogService.testLogAspect("test");
  }

输出

2022-08-08 13:44:26.973  INFO 10124 --- [           main] com.cjz.study.test03.aspect.MyLogAspect  : 进入testLogAspect方法，参数str值为test; 
test
2022-08-08 13:44:26.995  INFO 10124 --- [           main] com.cjz.study.test03.aspect.MyLogAspect  : testLogAspect方法执行结束