Spring Boot中OpenAPI生成模型的JSON路径式校验错误提示方案咨询

推荐工具库与实现方案 #

1. Jakarta Validation（JSR-380）+ 自定义校验器 #

Jakarta Validation是Java生态的标准校验框架，配合Spring Boot可轻松扩展，通过ConstraintValidatorContext追踪校验路径，结合模型类字段映射生成JSON路径：

• 自定义校验注解

@Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = BlacklistCompanyValidator.class)
public @interface BlacklistCompany {
    String message() default "公司在黑名单中";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

• 实现带路径追踪的校验器

public class BlacklistCompanyValidator implements ConstraintValidator<BlacklistCompany, List<EmploymentHistory>> {
    private static final Set<String> BLACKLIST = Set.of("xyz corporation");

    @Override
    public boolean isValid(List<EmploymentHistory> histories, ConstraintValidatorContext context) {
        if (histories == null || histories.isEmpty()) {
            return true;
        }

        context.disableDefaultConstraintViolation();
        for (int i = 0; i < histories.size(); i++) {
            EmploymentHistory history = histories.get(i);
            if (BLACKLIST.contains(history.getCompanyname())) {
                String jsonPath = String.format("$.employee.employmenthistory[%d].companyname", i);
                context.buildConstraintViolationWithTemplate(
                        String.format("公司在黑名单中，路径：%s", jsonPath)
                ).addConstraintViolation();
                return false;
            }
        }
        return true;
    }
}

• 在生成的模型类上应用注解
  修改Employee类：

public class Employee {
    Personal personal;
    @BlacklistCompany
    List<EmploymentHistory> employmentHistories;
}

2. Jackson 树模型直接遍历JSON #

如果需要跳过生成的模型类直接操作JSON结构，用Jackson的JsonNode遍历并记录路径：

public void validateEmployeeJson(String json) throws IOException {
    ObjectMapper mapper = new ObjectMapper();
    JsonNode root = mapper.readTree(json);
    Set<String> blacklist = Set.of("xyz corporation");

    JsonNode employmentHistoryNode = root.path("employee").path("employmenthistory");
    if (employmentHistoryNode.isArray()) {
        for (int i = 0; i < employmentHistoryNode.size(); i++) {
            JsonNode companyNode = employmentHistoryNode.get(i).path("companyname");
            if (companyNode.isTextual() && blacklist.contains(companyNode.asText())) {
                String jsonPath = String.format("$.employee.employmenthistory[%d].companyname", i);
                throw new ValidationException("公司在黑名单中，路径：" + jsonPath);
            }
        }
    }
}

3. Hibernate Validator 路径API（进阶） #

作为Jakarta Validation的实现，Hibernate Validator提供精细的路径追踪API，可从ConstraintValidatorContext获取校验路径并转换为JSON格式：

@Override
public boolean isValid(List<EmploymentHistory> histories, ConstraintValidatorContext context) {
    if (histories == null || histories.isEmpty()) {
        return true;
    }

    context.disableDefaultConstraintViolation();
    Path basePath = context.getConstraintDescriptor().getPropertyPath();
    for (int i = 0; i < histories.size(); i++) {
        EmploymentHistory history = histories.get(i);
        if (BLACKLIST.contains(history.getCompanyname())) {
            // 处理模型类字段名与JSON字段名的驼峰/下划线差异
            String jsonPath = "$." + basePath.toString().replace("employmentHistories", "employmenthistory") + "[" + i + "].companyname";
            context.buildConstraintViolationWithTemplate(
                    String.format("公司在黑名单中，路径：%s", jsonPath)
            ).addConstraintViolation();
            return false;
        }
    }
    return true;
}

关键注意事项 #

• OpenAPI生成的模型类字段名（如employmentHistories）与JSON字段名（employmenthistory）可能存在命名差异，可通过生成时配置@JsonProperty注解，或在校验逻辑中手动映射字段名。
• 可封装通用工具类，基于模型类的JsonProperty注解自动转换字段名为JSON路径中的名称，减少硬编码。

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