Java自定义注解完全指南：从基础到实战落地

// 元注解组合
@Target({ElementType.METHOD, ElementType.TYPE}) // 作用于类和方法
@Retention(RetentionPolicy.RUNTIME) // 运行时保留，支持反射解析
@Documented // 生成javadoc文档
@Inherited // 允许子类继承
public @interface MyAnnotation {
    // 注解属性：格式为“属性类型 属性名() [default 默认值];”
    String value() default ""; // 特殊属性：value，使用时可省略属性名直接赋值
    int order() default 0; // 普通属性，带默认值
    String[] tags(); // 数组类型属性，无默认值，使用时必须赋值
}

// 作用于类，所有属性显式赋值
@MyAnnotation(value = "user-service", order = 1, tags = {"service", "user"})
public class UserService {

    // 作用于方法，value属性省略名称，tags赋值单个值
    @MyAnnotation("get-user")
    public User getUserById(@MyAnnotation("user-id") Long id) {
        return new User();
    }
}

import java.lang.annotation.*;

@Target(ElementType.METHOD) // 仅作用于方法
@Retention(RetentionPolicy.RUNTIME) // 运行时保留，支持反射
@Documented
public @interface LogRecord {
    // 日志描述，默认取方法名
    String desc() default "";
    // 是否记录请求参数
    boolean recordParam() default true;
    // 是否记录返回结果
    boolean recordResult() default false;
}

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.stereotype.Component;
import java.lang.reflect.Method;
import java.time.LocalDateTime;

// 切面类，拦截注解标注的方法
@Aspect
@Component
public class LogRecordAspect {

    // 切入点：拦截所有标注@LogRecord的方法
    @Around("@annotation(com.example.annotation.LogRecord)")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        // 1. 反射获取方法及注解属性
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        LogRecord logRecord = method.getAnnotation(LogRecord.class);

        // 2. 解析注解属性
        String desc = logRecord.desc().isEmpty() ? method.getName() : logRecord.desc();
        boolean recordParam = logRecord.recordParam();
        boolean recordResult = logRecord.recordResult();

        // 3. 日志前置记录
        LocalDateTime startTime = LocalDateTime.now();
        String username = getCurrentUsername(); // 模拟获取当前登录用户
        System.out.printf("[日志记录] 时间：%s，用户：%s，操作：%s%n", startTime, username, desc);
        if (recordParam) {
            Object[] args = joinPoint.getArgs();
            System.out.printf("[日志记录] 请求参数：%s%n", args);
        }

        // 4. 执行目标方法
        long start = System.currentTimeMillis();
        Object result = joinPoint.proceed(); // 执行原方法
        long cost = System.currentTimeMillis() - start;

        // 5. 日志后置记录
        if (recordResult) {
            System.out.printf("[日志记录] 返回结果：%s%n", result);
        }
        System.out.printf("[日志记录] 执行耗时：%dms%n", cost);

        return result;
    }

    // 模拟获取当前登录用户
    private String getCurrentUsername() {
        return "admin";
    }
}

@RestController
@RequestMapping("/user")
public class UserController {

    // 使用日志注解，配置记录参数和结果
    @LogRecord(desc = "根据ID查询用户", recordParam = true, recordResult = true)
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        User user = new User();
        user.setId(id);
        user.setUsername("zhangsan");
        return user;
    }
}

[日志记录] 时间：2026-01-29T15:30:00，用户：admin，操作：根据ID查询用户
[日志记录] 请求参数：[1]
[日志记录] 返回结果：User(id=1, username=zhangsan)
[日志记录] 执行耗时：12ms

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresPermission {
    // 所需权限标识（支持多个）
    String[] value();
    // 无权限时的提示信息
    String message() default "无权限访问该接口";
}

@Aspect
@Component
public class PermissionAspect {

    @Around("@annotation(com.example.annotation.RequiresPermission)")
    public Object checkPermission(ProceedingJoinPoint joinPoint) throws Throwable {
        // 1. 解析注解
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        RequiresPermission permission = signature.getMethod().getAnnotation(RequiresPermission.class);
        String[] requiredPermissions = permission.value();
        String message = permission.message();

        // 2. 获取当前用户拥有的权限（模拟从登录上下文获取）
        List<String> userPermissions = getCurrentUserPermissions();

        // 3. 权限校验
        boolean hasPermission = Arrays.stream(requiredPermissions)
                .anyMatch(userPermissions::contains);
        if (!hasPermission) {
            throw new RuntimeException(message);
        }

        // 4. 校验通过，执行目标方法
        return joinPoint.proceed();
    }

    // 模拟获取当前用户权限
    private List<String> getCurrentUserPermissions() {
        return Arrays.asList("user:query", "user:add"); //  admin用户拥有的权限
    }
}

@RestController
@RequestMapping("/user")
public class UserController {

    // 要求拥有"user:query"权限
    @RequiresPermission("user:query")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return new User(id, "zhangsan");
    }

    // 要求拥有"user:delete"权限（当前用户无此权限）
    @RequiresPermission(value = "user:delete", message = "无删除用户权限")
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        return "删除成功";
    }
}

// 复合注解：组合@LogRecord和@RequiresPermission
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@LogRecord(desc = "需权限校验的操作", recordParam = true)
@RequiresPermission("admin:operate")
public @interface LogAndAuth {
    // 可重写组合注解的属性（可选）
    String logDesc() default "";
}

@LogAndAuth(logDesc = "管理员操作")
@PostMapping("/admin/operate")
public String adminOperate() {
    return "操作成功";
}

// 定义日志级别枚举
public enum LogLevel {
    INFO, WARN, ERROR
}

// 注解属性使用枚举
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Log {
    LogLevel level() default LogLevel.INFO; // 枚举类型属性
    String desc();
}

// 使用注解
@Log(level = LogLevel.WARN, desc = "敏感操作日志")
public void sensitiveOperate() {
    // 业务逻辑
}