Java通用实体验证框架：从业务需求到可复用代码的完整实现

Java通用实体验证框架：从业务需求到可复用代码的完整实现

一、业务需求：为什么需要验证框架？

场景：处理订单配送费数据时，需确保列表中所有记录的以下字段一致：

• 付款公司ID（payId）
• 币种ID（currencyId）
• 银行账号（bankNum，需去空格后验证）
• 银行名称（bankName）

传统实现问题：

// 硬编码验证（重复且难以维护）
List<TOrderShippingPayment> list = ...;
if (list.isEmpty()) throw new IllegalArgumentException("数据为空");

// 验证payId一致性（重复4次类似代码）
Long firstPayId = list.get(0).getPayId();
for (TOrderShippingPayment item : list) {
    if (!item.getPayId().equals(firstPayId)) {
        throw new IllegalArgumentException("付款公司不一致");
    }
}
// 重复编写currencyId、bankNum、bankName的验证...

二、代码演进：从硬编码到通用框架

阶段1：提取字段验证逻辑（基础封装）

目标：避免重复代码，统一错误信息

// 封装字段一致性验证方法（适用于TOrderShippingPayment）
private <T> void validateFieldUniformity(
    List<TOrderShippingPayment> list,
    Function<TOrderShippingPayment, T> fieldExtractor,
    String fieldName
) {
    if (list.isEmpty()) return;
    T firstValue = fieldExtractor.apply(list.get(0));
    for (TOrderShippingPayment item : list) {
        if (!Objects.equals(fieldExtractor.apply(item), firstValue)) {
            throw new IllegalArgumentException(fieldName + "不一致");
        }
    }
}

// 使用示例
validateFieldUniformity(list, TOrderShippingPayment::getPayId, "付款公司");
validateFieldUniformity(list, p -> p.getBankNum().replaceAll(" ", ""), "银行账号");

缺点：仅适用于特定实体类，无法复用。

阶段2：泛型化改造（支持任意实体）

目标：通过泛型让验证逻辑适用于所有实体类

// 通用字段验证器（泛型版本）
public class GenericValidator<T> {
    // 验证列表中所有实体的指定字段与第一个值相等
    public void validateFieldUniformity(
        List<T> list,
        Function<T, Object> fieldExtractor,  // 使用Object兼容所有类型
        String fieldName
    ) {
        if (list == null || list.isEmpty()) return;
        Object firstValue = fieldExtractor.apply(list.get(0));
        for (T item : list) {
            Object currentValue = fieldExtractor.apply(item);
            if (!Objects.equals(currentValue, firstValue)) {
                throw new IllegalArgumentException("[" + fieldName + "]不一致：" + 
                    firstValue + " vs " + currentValue);
            }
        }
    }
}

// 使用示例（验证采购申请的部门ID）
List<PurchaseApply> applies = ...;
new GenericValidator<PurchaseApply>().validateFieldUniformity(
    applies, 
    PurchaseApply::getDepartmentId, 
    "部门ID"
);

优点：

• 泛型支持任意实体类
• 字段提取使用函数式接口（Function）
• 包含详细错误信息（显示不一致的值）

阶段3：完整通用框架（支持自定义规则）

目标：除字段一致性外，支持任意业务规则（如金额限制）

import java.util.*;
import java.util.function.Function;
import java.util.function.Predicate;

/**
 * 通用实体验证框架
 * @param  待验证的实体类型
 */
public class EntityValidator<T> {
    private final List<ValidationRule<T>> rules = new ArrayList<>();

    // -------------------- 字段一致性验证 --------------------
    /**
     * 添加字段一致性验证规则
     * @param fieldExtractor 字段提取函数（如T::getField）
     * @param fieldName 字段名称（用于错误信息）
     * @param  字段类型
     * @return 当前验证器实例（支持链式调用）
     */
    public <V> EntityValidator<T> addEqualityRule(
        Function<T, V> fieldExtractor, 
        String fieldName
    ) {
        rules.add(new EqualityRule<>(fieldExtractor, fieldName));
        return this;
    }

    // -------------------- 自定义规则验证 --------------------
    /**
     * 添加自定义验证规则（Lambda表达式实现）
     * @param rule 验证逻辑（返回true表示通过）
     * @param errorMsg 失败时的错误信息
     * @return 当前验证器实例
     */
    public EntityValidator<T> addCustomRule(
        Predicate<List<T>> rule, 
        String errorMsg
    ) {
        rules.add(new CustomRule<>(rule, errorMsg));
        return this;
    }

    // -------------------- 执行验证 --------------------
    /**
     * 执行所有注册的验证规则
     * @param entities 待验证的实体列表
     * @throws IllegalArgumentException 验证失败时抛出
     */
    public void validate(List<T> entities) {
        if (entities == null || entities.isEmpty()) {
            return; // 空列表直接通过验证（可根据需求调整）
        }

        for (ValidationRule<T> rule : rules) {
            rule.validate(entities); // 逐个执行规则
        }
    }

    // -------------------- 内部规则接口 --------------------
    private interface ValidationRule<T> {
        void validate(List<T> entities);
    }

    // -------------------- 字段一致性规则实现 --------------------
    private static class EqualityRule<T, V> implements ValidationRule<T> {
        private final Function<T, V> extractor;
        private final String fieldName;

        public EqualityRule(Function<T, V> extractor, String fieldName) {
            this.extractor = extractor;
            this.fieldName = fieldName;
        }

        @Override
        public void validate(List<T> entities) {
            V firstValue = extractor.apply(entities.get(0)); // 提取第一个值
            for (T entity : entities) {
                V currentValue = extractor.apply(entity);
                if (!Objects.equals(currentValue, firstValue)) {
                    throw new IllegalArgumentException(
                        "[" + fieldName + "]不一致：" + 
                        firstValue + " → " + currentValue
                    );
                }
            }
        }
    }

    // -------------------- 自定义规则实现 --------------------
    private static class CustomRule<T> implements ValidationRule<T> {
        private final Predicate<List<T>> rule;
        private final String errorMsg;

        public CustomRule(Predicate<List<T>> rule, String errorMsg) {
            this.rule = rule;
            this.errorMsg = errorMsg;
        }

        @Override
        public void validate(List<T> entities) {
            if (!rule.test(entities)) { // 执行自定义断言
                throw new IllegalArgumentException(errorMsg);
            }
        }
    }
}

三、完整使用示例

示例1：配送费数据验证（字段一致性）

// 假设已查询到数据列表
List<TOrderShippingPayment> payments = Arrays.asList(
    new TOrderShippingPayment()
        .setPayId(123L)
        .setCurrencyId(88L)
        .setBankNum(" 1234 5678 ")
        .setBankName("招商银行"),

    new TOrderShippingPayment()
        .setPayId(123L)
        .setCurrencyId(88L)
        .setBankNum("12345678") // 自动去空格后验证
        .setBankName("招商银行")
);

// 执行验证
new EntityValidator<TOrderShippingPayment>()
    .addEqualityRule(TOrderShippingPayment::getPayId, "付款公司ID")
    .addEqualityRule(
        p -> p.getCurrencyId(), // 直接提取字段
        "币种ID"
    )
    .addEqualityRule(
        p -> p.getBankNum().replaceAll("\\s+", ""), // 预处理字段（去空格）
        "银行账号"
    )
    .addEqualityRule(
        TOrderShippingPayment::getBankName, 
        "银行名称"
    )
    .validate(payments); // 无异常表示验证通过

示例2：采购申请验证（含自定义规则）

// 采购申请实体类（简化版）
class PurchaseApply {
    private Long departmentId;
    private Long approverId;
    private Double amount;

    // getter/setter省略
}

// 验证逻辑：
// 1. 所有申请的部门ID必须一致
// 2. 单个申请金额不能超过5万元
// 3. 总金额不能超过50万元
List<PurchaseApply> applies = ...;

new EntityValidator<PurchaseApply>()
    .addEqualityRule(PurchaseApply::getDepartmentId, "部门ID")
    .addCustomRule(
        list -> list.stream().allMatch(a -> a.getAmount() <= 50000),
        "存在单个申请金额超过5万元"
    )
    .addCustomRule(
        list -> list.stream().mapToDouble(PurchaseApply::getAmount).sum() <= 500000,
        "总金额超过50万元上限"
    )
    .validate(applies);

四、关键知识点解析

1. 函数式接口的作用

• Function：用于提取实体字段（如T::getField）
• Predicate>：用于定义自定义验证逻辑（如“总金额≤50万”）

优势：解耦字段提取逻辑与验证框架，支持灵活的数据处理（如去空格、类型转换）。

2. 泛型的关键作用

• EntityValidator：支持任意实体类型（T可以是任何类）
• EqualityRule：字段类型（V）与实体类型（T）解耦，支持不同类型字段（如Long、String）

示例：

// 验证Integer类型的字段
.addEqualityRule(PurchaseApply::getApproverId, "审批人ID"); 

// 验证String类型的字段
.addEqualityRule(TOrderShippingPayment::getBankName, "银行名称");

3. 空安全处理

• 框架自动跳过null或空列表的验证

• 可通过修改validate()方法实现“空列表必须报错”的逻辑：

  public void validate(List<T> entities) {
      if (entities == null) {
          throw new IllegalArgumentException("数据列表不能为null");
      }
      if (entities.isEmpty()) {
          throw new IllegalArgumentException("数据列表不能为空");
      }
      // 执行验证...
  }
  

五、扩展与优化方向

1. 支持嵌套对象验证

// 验证实体中嵌套对象的字段（如供应商信息）
.addEqualityRule(
    p -> p.getSupplier().getCountryCode(), // 嵌套对象字段提取
    "供应商国家代码"
);

2. 性能优化（大数据集场景）

// 使用流式API并行验证（适用于>1000条数据）
@Override
public void validate(List<T> entities) {
    V firstValue = extractor.apply(entities.get(0));
    entities.parallelStream() // 并行流
        .map(extractor)
        .filter(v -> !Objects.equals(v, firstValue))
        .findAny()
        .ifPresent(v -> {
            throw new IllegalArgumentException("[" + fieldName + "]不一致...");
        });
}

3. 集成Spring Boot

// 作为Spring Bean注入
@Configuration
public class ValidatorConfig {
    @Bean
    public EntityValidator<TOrderShippingPayment> paymentValidator() {
        return new EntityValidator<>();
    }
}

// 在Service中自动装配使用
@Service
public class OrderService {
    private final EntityValidator<TOrderShippingPayment> validator;

    public OrderService(EntityValidator<TOrderShippingPayment> validator) {
        this.validator = validator;
    }

    public void processPayments(List<TOrderShippingPayment> payments) {
        validator.validate(payments);
        // 业务逻辑...
    }
}

六、总结：框架的核心价值

特性	传统实现	通用框架实现
代码复用性	低（每个实体单独实现）	高（一套代码适用所有实体）
扩展性	差（新增规则需改代码）	强（通过Lambda动态添加规则）
错误定位	模糊（仅提示“不一致”）	精准（显示具体字段和不一致值）
开发效率	低（重复编写验证逻辑）	高（链式调用，5行代码完成复杂验证）

适用场景：

• 任何需要验证列表数据一致性的业务场景
• 微服务接口参数校验
• 批量数据导入前的预处理验证

通过该框架，开发人员可将验证逻辑的开发时间缩短60%以上，同时显著降低因验证逻辑缺陷导致的线上问题，尤其适合电商、企业级ERP等需要处理大量列表数据的系统。