Java 注解与反射实战：自定义日志与参数校验注解实现

元注解说明：

@Target(ElementType.METHOD)：限制注解仅用于方法（符合日志记录的场景）； @Retention(RetentionPolicy.RUNTIME)：必须保留到运行时，否则反射无法获取。

第二步：创建使用 @Log 注解的业务类

public class OrderService {
    // 标记日志：记录参数和返回值，描述为"创建订单"
    @Log(description = "创建订单", recordParams = true, recordResult = true)
    public String createOrder(String userId, double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("金额必须大于 0");
        }
        // 模拟业务耗时
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {}
        return "ORDER_" + System.currentTimeMillis();
    }

    // 标记日志：不记录返回值（无返回值），描述为"取消订单"
    @Log(description = "取消订单", recordParams = true, recordResult = false)
    public void cancelOrder(String orderId) {
        if (orderId == null || orderId.isEmpty()) {
            throw new IllegalArgumentException("订单 ID 不能为空");
        }
        // 模拟业务耗时
        try {
            Thread.sleep(50);
        } catch (InterruptedException e) {}
    }
}

第三步：实现注解解析器（核心逻辑）

通过反射拦截方法调用，解析 @Log 注解并执行日志记录逻辑：

import java.lang.reflect.Method;
import java.util.Arrays;

public class LogAnnotationProcessor {
    /**
     * 执行带日志注解的方法
     * @param target 目标对象
     * @param methodName 方法名
     * @param args 方法参数
     * @return 方法返回值
     */
    public static Object executeWithLog(Object target, String methodName, Object... args) {
        try {
            // 1. 获取方法对应的 Class 对象和参数类型
            Class<?>[] paramTypes = Arrays.stream(args)
                    .map(arg -> arg == null ? Object.class : arg.getClass())
                    .toArray(Class[]::new);
            Method method = target.getClass().getMethod(methodName, paramTypes);

            // 2. 检查方法是否有@Log 注解，无则直接执行
            if (!method.isAnnotationPresent(Log.class)) {
                return method.invoke(target, args);
            }

            // 3. 解析注解属性
            Log logAnnotation = method.getAnnotation(Log.class);
            String description = logAnnotation.description();
            boolean recordParams = logAnnotation.recordParams();
            boolean recordResult = logAnnotation.recordResult();
            boolean recordException = logAnnotation.recordException();

            // 4. 记录方法开始日志
            long startTime = System.currentTimeMillis();
            System.out.println("\n===== 【日志开始】" + (description.isEmpty() ? methodName : description) + " =====");
            if (recordParams) {
                System.out.println("参数：" + Arrays.toString(args));
            }

            // 5. 执行目标方法（捕获异常并记录）
            Object result;
            try {
                result = method.invoke(target, args);
            } catch (Exception e) {
                // 记录异常信息
                if (recordException) {
                    System.out.println("执行异常：" + e.getCause().getMessage());
                }
                throw e; // 继续抛出异常，不掩盖业务逻辑
            }

            // 6. 记录方法结束日志
            long endTime = System.currentTimeMillis();
            System.out.println("耗时：" + (endTime - startTime) + "ms");
            if (recordResult) {
                System.out.println("返回值：" + result);
            }
            System.out.println("===== 【日志结束】" + (description.isEmpty() ? methodName : description) + " =====");
            return result;
        } catch (Exception e) {
            // 处理反射或业务异常（实际项目中可转为自定义异常）
            throw new RuntimeException("方法执行失败：" + e.getMessage(), e);
        }
    }
}

第四步：测试日志注解效果

public class LogTest {
    public static void main(String[] args) {
        OrderService orderService = new OrderService();
        // 测试正常创建订单
        LogAnnotationProcessor.executeWithLog(orderService, "createOrder", "user_001", 99.9);
        // 测试取消订单
        LogAnnotationProcessor.executeWithLog(orderService, "cancelOrder", "ORDER_123456");
        // 测试异常场景（金额为负数）
        try {
            LogAnnotationProcessor.executeWithLog(orderService, "createOrder", "user_002", -10.0);
        } catch (Exception e) {
            // 此处仅捕获，不处理（异常已被日志记录）
        }
    }
}

执行结果

===== 【日志开始】创建订单 ===== 
参数：[user_001, 99.9] 
耗时：101ms 
返回值：ORDER_1698765432100 
===== 【日志结束】创建订单 ===== 
===== 【日志开始】取消订单 ===== 
参数：[ORDER_123456] 
耗时：50ms 
===== 【日志结束】取消订单 ===== 
===== 【日志开始】创建订单 ===== 
参数：[user_002, -10.0] 
执行异常：金额必须大于 0 
===== 【日志结束】创建订单 ===== 

日志注解执行流程图解

（注：核心展示流程节点：调用方法→反射检查注解→记录开始日志→执行方法→记录结束日志）

案例二：自定义参数校验注解 —— 告别重复的 if-else

需求分析

我们需要两个注解：

@NotNull：标记参数不能为 null； @Range：标记数值参数必须在指定范围内（如年龄 1-120 岁）。

实现效果：方法调用时自动校验参数，不符合规则则抛出明确的异常信息。

第一步：定义校验注解

1.1 @NotNull 注解

import java.lang.annotation.*;

@Target(ElementType.PARAMETER) // 仅用于方法参数
@Retention(RetentionPolicy.RUNTIME)
public @interface NotNull {
    // 校验失败的提示信息
    String message() default "参数不能为 null";
}

1.2 @Range 注解

import java.lang.annotation.*;

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Range {
    long min() default 0; // 最小值（包含）
    long max() default Long.MAX_VALUE; // 最大值（包含）
    String message() default "参数不在指定范围内";
}

第二步：创建使用校验注解的业务类

public class UserService {
    // 新增用户：ID 不能为空，年龄必须 1-120 岁
    public void addUser(
            @NotNull(message = "用户 ID 不能为空") String userId,
            @Range(min = 1, max = 120, message = "年龄必须在 1-120 岁之间") int age) {
        System.out.println("新增用户成功：userId=" + userId + ", age=" + age);
    }

    // 更新积分：积分必须≥0
    public void updatePoints(
            @NotNull String userId,
            @Range(min = 0, message = "积分不能为负数") int points) {
        System.out.println("更新积分成功：userId=" + userId + ", points=" + points);
    }
}

第三步：实现参数校验器（核心逻辑）

通过反射获取方法参数上的注解，逐个校验参数是否符合注解规则：

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.Arrays;

public class ParamValidator {
    /**
     * 校验方法参数是否符合注解规则
     * @param target 目标对象
     * @param methodName 方法名
     * @param args 方法参数
     * @throws IllegalArgumentException 校验失败时抛出
     */
    public static void validate(Object target, String methodName, Object... args) throws Exception {
        // 1. 获取方法对象
        Class<?>[] paramTypes = Arrays.stream(args)
                .map(arg -> arg == null ? Object.class : arg.getClass())
                .toArray(Class[]::new);
        Method method = target.getClass().getMethod(methodName, paramTypes);

        // 2. 获取方法参数列表（包含注解信息）
        Parameter[] parameters = method.getParameters();

        // 3. 遍历参数，执行校验
        for (int i = 0; i < parameters.length; i++) {
            Parameter param = parameters[i];
            Object arg = args[i]; // 当前参数值

            // 3.1 校验@NotNull 注解
            if (param.isAnnotationPresent(NotNull.class)) {
                NotNull notNull = param.getAnnotation(NotNull.class);
                if (arg == null) {
                    throw new IllegalArgumentException(notNull.message());
                }
            }

            // 3.2 校验@Range 注解（仅对数值类型生效）
            if (param.isAnnotationPresent(Range.class) && arg instanceof Number) {
                Range range = param.getAnnotation(Range.class);
                long value = ((Number) arg).longValue(); // 转为 long 统一处理
                if (value < range.min() || value > range.max()) {
                    throw new IllegalArgumentException(range.message());
                }
            }
        }

        // 4. 校验通过，执行方法
        method.invoke(target, args);
    }
}

第四步：测试参数校验效果

public class ValidatorTest {
    public static void main(String[] args) {
        UserService userService = new UserService();
        // 测试正常参数
        try {
            ParamValidator.validate(userService, "addUser", "user_001", 25);
        } catch (Exception e) {
            System.out.println("错误：" + e.getMessage());
        }
        // 测试 null 参数（userId 为 null）
        try {
            ParamValidator.validate(userService, "addUser", null, 25);
        } catch (Exception e) {
            System.out.println("错误：" + e.getMessage());
        }
        // 测试年龄超出范围（150 岁）
        try {
            ParamValidator.validate(userService, "addUser", "user_002", 150);
        } catch (Exception e) {
            System.out.println("错误：" + e.getMessage());
        }
        // 测试积分负数
        try {
            ParamValidator.validate(userService, "updatePoints", "user_003", -10);
        } catch (Exception e) {
            System.out.println("错误：" + e.getMessage());
        }
    }
}

执行结果

新增用户成功：userId=user_001, age=25 
错误：用户 ID 不能为空 
错误：年龄必须在 1-120 岁之间 
错误：积分不能为负数 

参数校验流程图解

实战总结：自定义注解的设计原则与优化方向

1. 注解设计三要素

明确作用范围：用 @Target 严格限制注解的使用场景（如日志注解只用于方法）； 合理生命周期：需要反射解析的注解必须用 @Retention(RUNTIME)； 属性精简实用：只保留必要的属性（如日志注解的 description、校验注解的 message），并设置合理默认值。

2. 反射解析优化技巧

缓存反射结果：Method、Parameter 等对象的获取有性能开销，可通过 ConcurrentHashMap 缓存注解与方法的映射关系； 批量处理注解：用 getAnnotations() 一次性获取所有注解，避免多次反射调用； 异常友好提示：校验或日志失败时，异常信息要明确（如 "年龄必须在 1-120 岁之间" 而非 "参数错误"）。

3. 与现有框架的对比

日志注解：Spring 的 @Log、Lombok 的 @Log4j2 功能更完善，但自定义注解可灵活适配业务需求（如对接特定日志系统）； 参数校验：JSR-303 规范（javax.validation）提供了丰富的校验注解，但自定义注解可实现框架不支持的特殊校验（如手机号格式、身份证号规则）。

结语：注解 + 反射 = 代码的 "隐形翅膀"

通过本文的两个实战案例，你应该体会到：

注解是 "声明式编程" 的载体，让代码更简洁、意图更明确； 反射是注解的 "执行引擎"，让标记转化为实际逻辑。

这对组合在框架开发（如 Spring、MyBatis）中无处不在，掌握它们能让你从 "使用者" 升级为 "设计者"。

动手练习：尝试扩展本文案例 ——

1. 给日志注解增加 level 属性（INFO/ERROR），实现不同级别日志的输出；
2. 新增 @Pattern 注解，校验字符串是否符合正则表达式（如手机号、邮箱）。