Java自定义注解案例怎么开发

wen java案例 2026-07-01 28

Java自定义注解案例开发：从零到实战的完整指南

目录导读

Java注解基础认知 – 什么是注解？元注解有哪些？
自定义注解开发步骤 – 四个关键步骤详解
实战案例一：日志记录注解 – 自动记录方法调用日志
实战案例二：权限校验注解 – 拦截未授权访问
注解与AOP结合 – 如何让注解真正生效
常见问题与问答 – 你可能遇到的坑与解决方案

Java注解基础认知

注解（Annotation）是Java 5引入的一种元数据机制，它不直接影响程序逻辑，但可以被编译器或运行时框架解析，从而控制程序行为，理解自定义注解前，必须掌握四个元注解：

Java自定义注解案例怎么开发

@Target：注解作用范围（方法、类、字段等）
@Retention：注解生命周期（源码、编译时、运行时）
@Inherited：是否允许子类继承
@Documented：是否包含在Javadoc中

问答：为什么开发自定义注解必须设置@Retention？答：若不设置RetentionPolicy.RUNTIME，注解仅在编译前或编译时存在，运行时无法通过反射获取，导致AOP切面无法识别，绝大多数业务场景都需要RUNTIME。

自定义注解开发四个核心步骤

步骤1：定义注解接口

使用@interface关键字定义，与定义接口类似，但可以设置默认值。

步骤2：配置元注解

根据用途选择@Target和@Retention，建议大多数业务注解都设为@Retention(RUNTIME)。

步骤3：添加注解属性

定义属性时需注意：属性类型必须为基本类型、String、Class、Enum、Annotation或它们的数组。

步骤4：编写解析逻辑

通过反射获取注解实例,然后执行对应的业务逻辑，通常与AOP（如Spring AOP）结合使用。

核心语法示例：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyLog {
    String value() default "";  // 属性可以设置默认值
}

问答：注解属性可以定义复杂对象吗？答：不可以，属性只能使用基本类型、String、Class、枚举、注解或它们的数组，如果需要传递复杂对象，建议使用String属性配合JSON序列化。

实战案例一：日志记录注解

需求：自动记录每个方法的调用时间、参数和返回值，用于监控系统性能。

1 定义注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MethodLog {
    String description() default "";
}

2 使用AOP解析注解

在Spring项目中添加依赖后,编写切面类：

@Aspect
@Component
public class LogAspect {
    @Around("@annotation(methodLog)")
    public Object logExecution(ProceedingJoinPoint joinPoint, MethodLog methodLog) throws Throwable {
        long start = System.currentTimeMillis();
        String methodName = joinPoint.getSignature().getName();
        Object[] args = joinPoint.getArgs();
        System.out.println("调用方法：" + methodName + "，描述：" + methodLog.description());
        Object result = joinPoint.proceed();
        long duration = System.currentTimeMillis() - start;
        System.out.println("方法执行耗时：" + duration + "ms");
        return result;
    }
}

3 使用示例

@RestController
public class UserController {
    @MethodLog(description = "查询用户信息")
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        // 业务逻辑
    }
}

问答：日志注解在分布式系统中如何避免性能损耗？答：可以使用异步日志记录，例如将日志发送到消息队列（如Kafka），或利用Spring的@Async异步处理，同时建议在@Around中仅记录关键链路。

实战案例二：权限校验注解

需求：对特定接口进行角色校验，无权限时返回403。

1 定义权限注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiresRole {
    String[] value() default {};
    String message() default "无访问权限";
}

2 编写校验切面

@Aspect
@Component
public class AuthAspect {
    @Before("@annotation(requiresRole)")
    public void checkAuthority(JoinPoint joinPoint, RequiresRole requiresRole) {
        String[] requiredRoles = requiresRole.value();
        // 从安全上下文获取当前用户角色（伪代码）
        String currentUserRole = SecurityContextHolder.getContext().getUserRole();
        boolean authenticated = Arrays.asList(requiredRoles).contains(currentUserRole);
        if (!authenticated) {
            throw new SecurityException(requiresRole.message());
        }
    }
}

3 在Controller中使用

@PostMapping("/admin/delete")
@RequiresRole({"ADMIN","SUPER_ADMIN"})
public void deleteUser(@RequestParam Long userId) {
    // 删除逻辑
}

问答：权限注解和Spring Security的@PreAuthorize有什么区别？答：@PreAuthorize是Spring Security内置的表达式驱动注解，更灵活但依赖Security框架，自定义权限注解更轻量，适合不需要完整安全框架的微服务场景，且可以自定义错误消息与返回格式。