Java中如何编写自定义注解

最新推荐文章于 2025-11-11 10:00:00 发布

原创最新推荐文章于 2025-11-11 10:00:00 发布 · 1.6k 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#Java #注解

Java 专栏收录该内容

3 篇文章

订阅专栏

本文深入讲解Java注解的概念、分类及应用，包括常见注解、自定义注解的创建与处理，以及注解处理器的编写。

博客主要用来记录和分享学习的知识，如果有错误的地方希望大家可以指出哈~

文章目录

一、概念

注解（也被成为元数据）为我们在代码中添加信息提供了一种形式化的方式，使我们可以在稍后的某个时刻更容易的使用这些数据。

二、常见注解

1. Java 自带

在Java中自带了三个基本注解和四个元注解，基本注解分别是@Override、@Deprecated和@SuppressWarnings等。

注解	说明
`@Override`	表示被标注的方法重写了从父类继承下来的方法
`@Deprecated`	表示被标注的方法已经过时了，不建议再引用
`@SuppressWarnings`	关闭代码中不需要的警告信息

2. 第三方注解

也就是第三方框架自带的注解，如Spring框架中的@Autowired、@Controller等注解；Mybatis中的@InsertProvider、@Mapper等；这些不是文章的重点，所以不一一介绍了，感兴趣的童鞋可以自行Google哈~

3. 自定义的注解

在Java中允许我们自定义注解，我们可以根据自己的需求编写所需的代码

三、注解分类

按照运行的机制来分的话，注解可以分为：

源码注解：注解只在源码中存在，编译（变成.class文件）后就不存在了
编译时注解：源码和.class文件中都会存在，如上面三个Java自带注解
运行时注解：在程序运行时也一直起作用，甚至会影响运行逻辑的注解，像Spring中的@Autowired

除了以上还有一些注解，如 元注解，就是用来标注其他注解的注解，一般用来创建新的注解；标记注解，表示注解实际没有什么功能，只有标记作用。

四、自定义注解

1. 元注解

Java中有四个元注解，它们的作用就是注解其他的注解，当自定义注解的时候，需要编写相应的处理器来处理它们：

名称	说明
`@Target`	表示注解可以作用在哪些地方（即作用域），参数为ElementType枚举包括： CONSTRUCTOR：构造器说明 FIELD：字段或域的声明, 包括enum实例 LOCAL_VARIABLE：局部变量声明 METHOD：方法声明 PACKAGE：包声明 PARAMETER：参数声明 TYPE：类、接口、注解或enum声明
`@Retention`	表示需要在什么级别保存该注解信息（生命周期），参数为RetentionPolicy枚举，包括： SOURCE：只在源码中显示，编译时丢弃 CLASS：`.class`文件中可用，运行时丢弃 RUNTIME：运行器也会存在，因此可以通过反射机制来读取注解的信息
`@Documented`	生成Javadoc时会把带有该注解的注解也包括进去，是一个标识注解
`@Inherited`	允许子类继承父类中的注解，是一个标识注解

2. 如何自定义注解

自定义注解的语法和定义Java中的接口差不多，而且注解也会生成.class文件。编写语法如下：

import java.lang.annotation.*;

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface UseCase {

    int id();

    String description() default "no description";

}

这样就定义了一个简单的注解，接下来说明说明一下：
① 用元注解来标注注解
② 使用@Interface关键字来定义注解，比定义接口的关键字多了一个@；
③ id()和description()在《Java编程思想》中称其为元素，类似接口中的方法，不同的是元素不能有入参且可以指定默认值，但不能是null值，如果想绕过这个约束可以使用空字符或负数；而且注解可以没有元素，没有元素时该注解就是标注注解，没有实际作用。

3. 使用自定义注解

使用自定义注解和使用Java自带的注解一样，以上面创建的@UseCase注解为例：

import java.util.List;

public class PasswordUtils {

    @UseCase(id = 47, description = "at least one numeric")
    public boolean validatePassword(String password) {
        return (password.matches("\\w*\\d\\w*"));
    }

	// 这里没有定义 default 的值, 之后处理时会使用默认值
    @UseCase(id = 48)
    public String encryptPassword(String password) {
        return new StringBuilder(password).reverse().toString();
    }

    @UseCase(id = 49, description = "new passwords can't equal previously used ones")
    public boolean checkForNewPassword(List<String> prevPasswords, String password) {
        return !prevPasswords.contains(password);
    }

}

注解需要根据@Target注解定义的作用范围来使用，否则编译不通过；注解中如果元素有定义default默认值的话可以省略不写，否则都要显示指定值。

4. 解析注解（编写注解处理器）

如果没有用于读取注解的工具，那么注解不会比注释更有用。使用注解中一个很重要的部分就是，创建与使用注解处理器。Java 拓展了反射机制的 API 用于帮助你创造这类工具。

——《Java编程思想》

就想书里说的，我们使用注解主要目的就是为了可以读取注解并进行动态操作。
下面是一个非常简单的注解处理器，我们用它来读取被注解的 PasswordUtils 类，并且使用反射机制来寻找 @UseCase 注解并打印出来。

import java.lang.reflect.Method;

/**
 * @author Jason
 * @version V1.0
 * @Date 2019/11/21 22:52
 */
public class UseCaseTracker {

    public static void main(String[] args) {
        Class<PasswordUtils> clz = PasswordUtils.class;

        for (Method method : clz.getMethods()) {
            UseCase annotation = method.getAnnotation(UseCase.class);
            if (annotation != null) {
                System.out.println("id=" + annotation.id() + ", desc=" + annotation.description());
            }
        }

    }

}

运行main()后输出:

id=49, desc=new passwords can't equal previously used ones
id=48, desc=no description
id=47, desc=at least one numeric

这个程序用来两个反射的方法:

getMethods：获取类中的方法
getAnnotation：获取方法上特定的注解，而getDeclaredAnnotations则是获取方法上的所有注解