在 Java 开发中，自定义注解（Annotation）是一种元编程机制，广泛用于框架设计、代码增强（如 AOP）、参数校验、权限控制、日志埋点等场景。大型的框架工具，如Spring、MyBatis、Hibernate 都大量使用注解机制，一些我们熟知的第三方工具（Hutool、Lombok）也都是用了大量的注解机制来增强和扩展应用。

一般来说，常见的自定义注解基本的语法包括

自定义注解一般的获取方式是结合反射读取注解，而在使用方向上结合 Spring AOP 使用注解是最多的，Spring已经应用在各类Java语言中的架构中。

 是一个元注解（Meta‐annotation），来源于

，用来标记一个注解自身应当被保留到哪个阶段（源码／字节码／运行时），他只能用在其他注解的定义上。

一张图来看下Retention注解RetentionPolicy中的参数。

，也就是注解信息在什么阶段可见、可用。它包含三个枚举值

public enum RetentionPolicy {
    SOURCE,
    CLASS,
    RUNTIME
}

为了更好的理解Retention注解，可以参看下代码示例。

package com.liu.aop;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.Method;

/**
 * <p> RetentionTest </p>
 * class
 * TODO
 *
 * @author Aion.Liu
 * @version v1.0.0
 * @since 2025/5/21 09:07
 */
public class RetentionTest {

    @SourceOnly
    @ClassOnly
    @RuntimeVisible
    public void test() {
    }

    public static void main(String[] args) throws Exception {
        // 仅 RuntimeVisible 会被反射读取到
        Method m = RetentionTest.class.getMethod("test");
        System.out.println("SOURCE present: " + m.isAnnotationPresent(SourceOnly.class));
        System.out.println("CLASS present:  " + m.isAnnotationPresent(ClassOnly.class));
        System.out.println("RUNTIME present:" + m.isAnnotationPresent(RuntimeVisible.class));
    }
}


// 仅源码阶段
@Retention(RetentionPolicy.SOURCE)
@interface SourceOnly { }

// 编译后保留，但运行时不可见
@Retention(RetentionPolicy.CLASS)
@interface ClassOnly { }

// 运行时可见
@Retention(RetentionPolicy.RUNTIME)
@interface RuntimeVisible { }


/xxx/jdk1.8.0_321.jdk/Contents/Home/bin/java -javaagent:/Applications/IntelliJ IDEA 2024.3.4.1.app/Contents/lib/idea_rt.jar=54099 -Dfile.encoding=UTF-8 -classpath /Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/charsets.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/deploy.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/cldrdata.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/dnsns.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/jaccess.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/jfxrt.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/localedata.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/nashorn.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/sunec.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/sunjce_provider.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/sunpkcs11.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/ext/zipfs.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/javaws.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/jce.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/jfr.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/jfxswt.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/jsse.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/management-agent.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/plugin.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/resources.jar:/Library/Java/JavaVirtualMachines/jdk1.8.0_321.jdk/Contents/Home/jre/lib/rt.jar:/Users/Aion/WorkSpace/JavaSpace/SpringBootSpace/springcloud_day5/chapter-spring-aop/target/classes:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-starter-web/2.7.11/spring-boot-starter-web-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-starter-json/2.7.11/spring-boot-starter-json-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/core/jackson-databind/2.13.5/jackson-databind-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/core/jackson-annotations/2.13.5/jackson-annotations-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/core/jackson-core/2.13.5/jackson-core-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/datatype/jackson-datatype-jdk8/2.13.5/jackson-datatype-jdk8-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/datatype/jackson-datatype-jsr310/2.13.5/jackson-datatype-jsr310-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/com/fasterxml/jackson/module/jackson-module-parameter-names/2.13.5/jackson-module-parameter-names-2.13.5.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-starter-tomcat/2.7.11/spring-boot-starter-tomcat-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/org/apache/tomcat/embed/tomcat-embed-core/9.0.74/tomcat-embed-core-9.0.74.jar:/usr/local/apache-maven-3.9.9-resp/org/apache/tomcat/embed/tomcat-embed-el/9.0.74/tomcat-embed-el-9.0.74.jar:/usr/local/apache-maven-3.9.9-resp/org/apache/tomcat/embed/tomcat-embed-websocket/9.0.74/tomcat-embed-websocket-9.0.74.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-web/5.3.27/spring-web-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-beans/5.3.27/spring-beans-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-webmvc/5.3.27/spring-webmvc-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-aop/5.3.27/spring-aop-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-context/5.3.27/spring-context-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-expression/5.3.27/spring-expression-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-core/5.3.27/spring-core-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/spring-jcl/5.3.27/spring-jcl-5.3.27.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-starter/2.7.11/spring-boot-starter-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot/2.7.11/spring-boot-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-autoconfigure/2.7.11/spring-boot-autoconfigure-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/org/springframework/boot/spring-boot-starter-logging/2.7.11/spring-boot-starter-logging-2.7.11.jar:/usr/local/apache-maven-3.9.9-resp/ch/qos/logback/logback-classic/1.2.12/logback-classic-1.2.12.jar:/usr/local/apache-maven-3.9.9-resp/ch/qos/logback/logback-core/1.2.12/logback-core-1.2.12.jar:/usr/local/apache-maven-3.9.9-resp/org/apache/logging/log4j/log4j-to-slf4j/2.17.2/log4j-to-slf4j-2.17.2.jar:/usr/local/apache-maven-3.9.9-resp/org/apache/logging/log4j/log4j-api/2.17.2/log4j-api-2.17.2.jar:/usr/local/apache-maven-3.9.9-resp/org/slf4j/jul-to-slf4j/1.7.36/jul-to-slf4j-1.7.36.jar:/usr/local/apache-maven-3.9.9-resp/jakarta/annotation/jakarta.annotation-api/1.3.5/jakarta.annotation-api-1.3.5.jar:/usr/local/apache-maven-3.9.9-resp/org/yaml/snakeyaml/1.30/snakeyaml-1.30.jar:/usr/local/apache-maven-3.9.9-resp/org/projectlombok/lombok/1.18.26/lombok-1.18.26.jar com.liu.aop.RetentionTest
SOURCE present: false
CLASS present:  false
RUNTIME present:true

的元注解（Meta-annotation），它定义了注解的

，帮助编译器在错误的地方使用注解时给出提示。

中的参数（注意：图中包括JDK 1.5 - JDK16之间注解参数值）。

 注解参数是ElementType，他是一个枚举值，

 定义了所有可用的目标类型，一共12种（截止到JDK21，）

public enum ElementType {
    TYPE,
    FIELD,
    METHOD,
    PARAMETER,
    CONSTRUCTOR,
    LOCAL_VARIABLE,
    ANNOTATION_TYPE,
    PACKAGE,
    TYPE_PARAMETER, 	// JDK 8
    TYPE_USE, 				// JDK 8
    MODULE, 					// JDK 9
    RECORD_COMPONENT; // JDK 16
}

Target注解只能应用在类和方法上面，在字段或参数上使用会编译报错。


// 自定义注解
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Audit {
    String action();
}

// 应用在类名称上
@Audit(action = "UserService")
public class UserService { ... }

public class OrderService {

    // 应用在方法上
    @Audit(action = "createOrder")
    public void create() { ... }
}

，用于指示某个注解类型是否应该被包含在 Javadoc 等生成的文档中。它是 Java 注解机制的一部分，定义在 

可从源代码中查看定义，当定义一个自定义注解，并在其上添加了 

任何使用了该注解的地方，在生成 Javadoc 时都会包含该注解

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}

// 1. 定义时使用Documented注解
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ApiDescription {
    String value();
}


// 2. 在类中使用自定义注解
@ApiDescription("注解描述。")
public class UserController {
}


// 3. 在shell中执行命令，生成的 HTML 文档中将包含注解 @ApiDescription 的信息。
javadoc -d doc UserController.java


，它控制一个注解是否会被子类

自定义注解一般结合 Spring Boot + AOP 实现：

上述这些也都是在Java语言中，使用Spring框架使用的常用方式。

详解JDK自定义注解

概述在 Java 开发中，自定义注解（Annotation）是一种元编程机制，广泛用于框架设计、代码增强（如 AOP）、参数校验、权限控制、日志埋点等场景。大型的框架工具，如Spring、MyBatis、Hibernate 都大量使用注解机制，一些我们熟知的第三方工具（Hutool、Lombok）也都是用了大量的注解机制来增强和扩展应用。1 关于自定义注解一般来说，常见的自定义注解基本的语法包括@

产品KOL

后端

Java自定义注解是元编程机制，用于框架设计和代码增强。关键元注解包括@Target（作用目标）、@Retention（保留策略）、@Documented（文档包含）和@Inherited（子类继承）。@Retention有SOURCE、CLASS、RUNTIME三个策略，RUNTIME可通过反射读取。合理使用注解可提升代码可读性和维护性。

IntelliJ IDEA

Spring Boot

编译器

Java

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

Java自定义注解是元编程机制，用于框架设计和代码增强。关键元注解包括@Target（作用目标）、@Retention（保留策略）、@Documented（文档包含）和@Inherited（子类继承）。@Retention有SOURCE、CLASS、RUNTIME三个策略，RUNTIME可通过反射读取。合理使用注解可提...

详解JDK自定义注解

详解JDK自定义注解

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐