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

Ne0inhk

— 10 min read
Java 注解与反射实战：手把手实现自定义日志与参数校验注解

前言：为什么需要自定义注解？

在日常开发中，我们经常遇到两类重复工作：

日志记录：每个重要方法都要写 "开始执行"、"参数是 xxx"、"执行结束" 的代码；参数校验：判断输入是否为 null、年龄是否在合理范围、手机号格式是否正确等。

这些工作机械且冗余，而注解 + 反射正是解决这类问题的 "银弹"—— 用注解标记需要处理的地方，用反射自动执行逻辑，实现 "一次定义，多处复用"。

本文将带你从零实现两个实用案例：

  1. 自定义日志注解@Log：自动记录方法调用细节；
  2. 自定义参数校验注解@NotNull、@Range：自动校验方法参数合法性。

全程实战，代码可直接运行，搭配图解帮你吃透底层逻辑。

案例一：自定义日志注解@Log—— 自动记录方法调用轨迹

需求分析

我们需要一个注解，标记在方法上后，能自动完成：

记录方法开始执行的时间；打印方法参数（可选）；记录方法执行耗时；打印返回结果（可选）；捕获并记录方法抛出的异常。

步骤 1：定义@Log注解

import java.lang.annotation.*; // 只能标记在方法上 @Target(ElementType.METHOD) // 运行时保留，允许反射获取 @Retention(RetentionPolicy.RUNTIME) public @interface Log { // 操作描述（如"创建订单"） String description() default ""; // 是否记录参数 boolean recordParams() default true; // 是否记录返回值 boolean recordResult() default true; // 是否记录异常 boolean recordException() default true; }

元注解说明：

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

步骤 2：创建使用@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) {} } }

步骤 3：实现注解解析器（核心逻辑）

通过反射拦截方法调用，解析@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); } } }

步骤 4：测试日志注解效果

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.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 "参数不在指定范围内"; }

步骤 2：创建使用校验注解的业务类

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); } }

步骤 3：实现参数校验器（核心逻辑）

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

import java.lang.reflect.Method; import java.lang.reflect.Parameter; 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); } }

步骤 4：测试参数校验效果

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注解，校验字符串是否符合正则表达式（如手机号、邮箱）。

欢迎在评论区分享你的实现思路！

Read more

Elasticsearch核心概念与Java客户端实战 构建高性能搜索服务

Elasticsearch核心概念与Java客户端实战 构建高性能搜索服务

目录 🎯 先说说我被ES"虐惨"的经历 ✨ 摘要 1. 为什么选择Elasticsearch？ 1.1 从数据库的痛苦说起 1.2 Elasticsearch的优势 2. ES核心架构解析 2.1 集群架构 2.2 索引与分片 3. Java客户端实战 3.1 客户端选型对比 3.2 RestHighLevelClient配置 3.3 Spring Data Elasticsearch配置 4. 索引设计最佳实践 4.1 索引生命周期管理 4.2 映射设计技巧 5. 查询优化实战 5.1 查询类型对比 5.

By Ne0inhk
【微服务】Java 对接飞书多维表格使用详解

【微服务】Java 对接飞书多维表格使用详解

目录 一、前言 二、前置操作 2.1 开通企业飞书账户 2.2 确保账户具备多维表操作权限 2.3 创建一张测试用的多维表 2.4 获取飞书开放平台文档 2.5 获取Java SDK 三、应用App相关操作 3.1 创建应用过程 3.2 应用发布过程 3.3 应用添加操作权限 四、多维表应用授权操作 五、使用控制台API调试操作多维表 5.1 控制台调试多维表操作过程 5.1.1 获取token 5.1.2 获取多维表数据 5.1.3

By Ne0inhk
JDK21安装与配置教程

JDK21安装与配置教程

文章目录 * 一、下载JDK * 1. 下载地址 * 2. 下载JDK21 * 二、JDK21安装及配置 * 1. 解压zip压缩包 * 2. 配置Java环境变量 * 2.1 打开系统属性设置 * 2.2 新建系统环境变量 * 2.3 编辑 PATH 环境变量 * 2.4 验证环境变量是否配置成功 一、下载JDK 1. 下载地址 华为云镜像下载地址： 地址 1（OracleJDK）：https://repo.huaweicloud.com/java/jdk/ 地址 2（OpenJDK）：https://mirrors.huaweicloud.com/openjdk/ 地址

By Ne0inhk
JAVA中对象的几种比较

JAVA中对象的几种比较

文章目录 * 引言 * 基本元素比较 * 1. 基本数据类型：直接用 `==` 比较值 * 2. 包装类：分两种情况 * 3. String 类型：核心看 `==` 和 `equals()` 的区别 * 基本元素比较的核心建议 * 总结 * 对象的比较 * 1. 覆写基类 `Object` 的 `equals()` + `hashCode()` * 核心用途 * 核心规则 * 实现要点 * 示例 * 适用场景 * 2. 基于 `Comparable` 接口的比较 * 核心用途 * 核心方法 * 实现要点 * 示例 * 适用场景 * 3. 基于 `Comparator` 比较器的比较 * 核心用途 * 核心方法 * 实现形式 * 示例 * 适用场景 * 总结一下

By Ne0inhk