Class BeanDiff

java.lang.Object

cloud.opencode.base.reflect.bean.BeanDiff

public final class BeanDiff
extends Object

BeanDiff - Before/after bean field change detection Bean 差异 - Bean 字段前后变更检测

Computes the set of changed fields between two bean instances of the same type. Useful for audit trails, change tracking, and conditional update generation.

计算同类型两个 Bean 实例之间已变更字段的集合。 适用于审计追踪、变更跟踪和条件更新生成。

Features | 主要功能:

• Field-level comparison with before/after values - 字段级比较，含前后值
• Skips static and final fields by default - 默认跳过 static 和 final 字段
• Configurable field filter via annotation or predicate - 可通过注解或谓词配置字段过滤
• Inheritance support — compares fields from all superclasses - 继承支持，比较所有父类字段
• Immutable result object safe to pass across layers - 不可变结果对象，可跨层安全传递

Usage Examples | 使用示例:

// Basic diff
BeanDiff.Result diff = BeanDiff.diff(before, after);

// Diff with annotation exclusion (e.g., @Transient)
BeanDiff.Result diff = BeanDiff.diff(before, after, MyTransient.class);

// Diff with custom field filter
BeanDiff.Result diff = BeanDiff.diff(before, after, f -> !f.getName().equals("password"));

if (diff.hasChanges()) {
    auditLog.record(diff.changes());
}

Security | 安全性:

• Thread-safe: Yes (stateless utility, immutable result) - 线程安全: 是（无状态工具，不可变结果）
• Null-safe: No (caller must ensure non-null bean arguments) - 空值安全: 否（调用方须确保非空bean参数）

Since:

JDK 25, opencode-base-reflect V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	BeanDiff.Change	A single field change: the field name, before-value, and after-value.
static final record	BeanDiff.Result	The result of a diff operation, containing all detected field changes.

Method Summary

Modifier and Type	Method	Description
static <T> BeanDiff.Result	diff(T before, T after)	Computes the diff between before and after beans.
static <T> BeanDiff.Result	diff(T before, T after, Class<? extends Annotation> excludeAnnotation)	Computes the diff, excluding fields annotated with the given annotation.
static <T> BeanDiff.Result	diff(T before, T after, Predicate<Field> fieldFilter)	Computes the diff with a custom field filter.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

diff

public static <T> BeanDiff.Result diff(T before,
 T after)

Computes the diff between before and after beans. No fields are excluded except static and final. 计算两个 Bean 之间的差异。仅排除 static 和 final 字段。

Type Parameters:

T - the bean type | Bean 类型

Parameters:

before - the original bean | 原始 Bean

after - the modified bean | 修改后的 Bean

Returns:

diff result | 差异结果

diff

public static <T> BeanDiff.Result diff(T before,
 T after,
 Class<? extends Annotation> excludeAnnotation)

Computes the diff, excluding fields annotated with the given annotation. 计算差异，排除带指定注解的字段。

Type Parameters:

T - the bean type | Bean 类型

Parameters:

before - the original bean | 原始 Bean

after - the modified bean | 修改后的 Bean

excludeAnnotation - annotation class to exclude | 要排除的注解类

Returns:

diff result | 差异结果

diff

public static <T> BeanDiff.Result diff(T before,
 T after,
 Predicate<Field> fieldFilter)

Computes the diff with a custom field filter. 使用自定义字段过滤器计算差异。

Type Parameters:

T - the bean type | Bean 类型

Parameters:

before - the original bean | 原始 Bean

after - the modified bean | 修改后的 Bean

fieldFilter - predicate that returns true for fields to include | 返回 true 表示包含该字段

Returns:

diff result | 差异结果