Java库与客户端契约构建：自定义方法参数记录规则实现方案咨询

我正在开发一款Java库，用于记录方法执行前后的参数，相关代码如下：

库代码 #

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RecordArgs {
}

@Aspect
public class RecordMethodArgsAspect {

    @Before("@annotation(RecordArgs)")
    public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
         //record method arguments i.e. Item object in below example
    }
}

应用代码（库的客户端） #

class Item {
    private String name;
    private String id;
    // mutable private fields

    public Item(String name, String id) {
        this.name=name;
        this.id=id;
    }

    // getter and setters

}

class ItemVisitor {
    @RecordArgs
    public void visit(Item item) {
        // export item object
    
        // business logic which mutates item

        // export item object
    }
}

核心需求 #

我希望提供一种方式，让应用代码（如本例中的Item类）指定在调用logMethod时需要记录哪些字段值或数据，确保未来Item类结构变更时无需修改该库，请问该如何实现？

以下是三种可行的实现方案，均能满足"实体类结构变更无需修改库代码"的需求：

方案1：自定义字段注解标记需记录的字段 #

通过给实体类的目标字段添加自定义注解，让切面通过反射识别并记录这些字段，实体类变更时只需给新增字段加注解即可。

库端修改 #

1. 新增字段标记注解

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface LogField {
    // 可选：给字段设置日志显示别名
    String alias() default "";
}

2. 更新切面逻辑（将@Before改为@Around以支持执行前后记录）

@Aspect
public class RecordMethodArgsAspect {

    @Around("@annotation(RecordArgs)")
    public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
        // 记录方法执行前的参数
        recordTargetArgs(joinPoint.getArgs(), "BEFORE");

        // 执行原业务方法
        Object result = joinPoint.proceed();

        // 记录方法执行后的参数
        recordTargetArgs(joinPoint.getArgs(), "AFTER");

        return result;
    }

    private void recordTargetArgs(Object[] args, String stage) {
        for (Object arg : args) {
            if (arg == null) continue;

            Class<?> clazz = arg.getClass();
            System.out.printf("[%s] 记录对象 %s 的字段：%n", stage, clazz.getSimpleName());
            
            // 扫描所有带@LogField注解的字段
            for (Field field : clazz.getDeclaredFields()) {
                if (field.isAnnotationPresent(LogField.class)) {
                    field.setAccessible(true);
                    try {
                        // 优先使用别名，无别名则用字段名
                        String logKey = field.getAnnotation(LogField.class).alias().isEmpty()
                                ? field.getName()
                                : field.getAnnotation(LogField.class).alias();
                        Object fieldValue = field.get(arg);
                        System.out.printf("  %s: %s%n", logKey, fieldValue);
                    } catch (IllegalAccessException e) {
                        // 异常处理：可记录日志而非直接打印栈信息
                        e.printStackTrace();
                    }
                }
            }
        }
    }
}

应用端修改 #

只需给Item类中需要记录的字段添加@LogField注解：

class Item {
    @LogField(alias = "商品名称")
    private String name;
    @LogField
    private String id;
    // 无需记录的字段无需添加注解
    private String internalStatus;

    public Item(String name, String id) {
        this.name = name;
        this.id = id;
        this.internalStatus = "INIT";
    }

    // getter and setters
}

方案2：让实体类实现自定义接口，主动提供日志数据 #

定义一个接口，让实体类实现该接口并返回需要记录的键值对，实体类完全掌控日志内容，支持动态计算字段。

库端修改 #

1. 定义日志数据提供接口

public interface Loggable {
    // 返回需要记录的日志数据，键为日志显示名，值为对应数据
    Map<String, Object> getLogData();
}

2. 更新切面逻辑

@Aspect
public class RecordMethodArgsAspect {

    @Around("@annotation(RecordArgs)")
    public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
        Object[] args = joinPoint.getArgs();
        // 记录执行前数据
        logLoggableObjects(args, "BEFORE");

        Object result = joinPoint.proceed();

        // 记录执行后数据
        logLoggableObjects(args, "AFTER");

        return result;
    }

    private void logLoggableObjects(Object[] args, String stage) {
        for (Object arg : args) {
            if (arg instanceof Loggable loggable) {
                System.out.printf("[%s] 记录日志数据：%n", stage);
                loggable.getLogData().forEach((key, value) ->
                        System.out.printf("  %s: %s%n", key, value));
            }
        }
    }
}

应用端修改 #

让Item类实现Loggable接口，自定义返回的日志数据：

class Item implements Loggable {
    private String name;
    private String id;
    private int stock;

    public Item(String name, String id, int stock) {
        this.name = name;
        this.id = id;
        this.stock = stock;
    }

    // 业务逻辑：修改字段
    public void reduceStock(int amount) {
        this.stock -= amount;
    }

    @Override
    public Map<String, Object> getLogData() {
        Map<String, Object> logData = new HashMap<>();
        logData.put("商品ID", id);
        logData.put("商品名称", name);
        logData.put("当前库存", stock);
        // 支持添加动态计算的字段
        logData.put("库存状态", stock > 0 ? "充足" : "缺货");
        return logData;
    }
}

方案3：通过配置文件指定需记录的字段 #

无需修改实体类代码，通过外部配置文件（如properties/yaml）指定每个类要记录的字段，库启动时加载配置，反射读取字段。

库端修改 #

1. 添加配置文件加载逻辑

@Aspect
public class RecordMethodArgsAspect {
    // 存储类名与对应需记录字段的映射
    private static final Map<String, List<String>> CLASS_FIELD_CONFIG = new HashMap<>();

    static {
        // 加载配置文件
        try (InputStream is = RecordMethodArgsAspect.class.getClassLoader().getResourceAsStream("log-fields.properties")) {
            Properties props = new Properties();
            props.load(is);
            for (Map.Entry<Object, Object> entry : props.entrySet()) {
                String className = (String) entry.getKey();
                String[] fields = ((String) entry.getValue()).split(",");
                CLASS_FIELD_CONFIG.put(className, Arrays.asList(fields));
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Around("@annotation(RecordArgs)")
    public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
        Object[] args = joinPoint.getArgs();
        // 记录执行前数据
        logConfiguredFields(args, "BEFORE");

        Object result = joinPoint.proceed();

        // 记录执行后数据
        logConfiguredFields(args, "AFTER");

        return result;
    }

    private void logConfiguredFields(Object[] args, String stage) {
        for (Object arg : args) {
            if (arg == null) continue;

            String className = arg.getClass().getName();
            List<String> targetFields = CLASS_FIELD_CONFIG.get(className);
            if (targetFields == null || targetFields.isEmpty()) continue;

            System.out.printf("[%s] 记录对象 %s 的字段：%n", stage, className);
            Class<?> clazz = arg.getClass();
            for (String fieldName : targetFields) {
                try {
                    Field field = clazz.getDeclaredField(fieldName);
                    field.setAccessible(true);
                    Object fieldValue = field.get(arg);
                    System.out.printf("  %s: %s%n", fieldName, fieldValue);
                } catch (NoSuchFieldException | IllegalAccessException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

2. 新增配置文件log-fields.properties（放在类路径下）

# 格式：全限定类名=字段1,字段2,...
com.example.Item=name,id
# 可添加其他类的配置
com.example.User=username,email

应用端修改 #

只需维护log-fields.properties文件，当Item类结构变更时，更新配置中的字段列表即可，无需修改任何代码。

内容的提问来源于stack exchange，提问作者user762421