🎯 今日核心问题

  1. Schema 校验通过但业务上完全错误,这类问题该怎么分层拦?
  2. LangChain4j 的输出解析失败时,怎么让重试带着「哪一行错了」回去,而不是整段重来?
  3. 业务规则写在 Java 里还是写在规则引擎里,多人维护时哪种更不容易腐化?

📖 精读提纲

【一】三层校验,越靠前越便宜

把「输出对不对」拆成三层,每层失败的处置方式不同:第一层语法(是不是合法 JSON、有没有多余的解释性文字);第二层结构(字段齐不齐、类型对不对、枚举取值是否在允许集内);第三层业务(金额是否为正、状态流转是否合法、时间是否在可操作窗口内、引用实体是否存在)。

第一层失败要重试,因为模型偶尔会多写一句「好的,结果如下」。第二层失败通常也重试一次,并把具体路径回灌。第三层失败不要重试——模型已经理解了任务,是它给出的值本身不合法,重试大概率还是同一个错。正确做法是把它当作业务异常,走降级或转人工。

【二】不要用自然语言约定结构

常见错误是在 System Prompt 里写「请返回 JSON,包含 orderId、amount、reason 三个字段」,然后把输出丢给 objectMapper.readValue。模型少一个字段、把 amount 写成 "100元",你就得在 catch 块里猜。正确做法是用 JsonSchema 把结构声明出来,多数模型厂商支持的 response_format 里带 json_schema(structured outputs)能保证结构合法率接近 100%,成本是把 schema 也计入 token。

LangChain4j 的 AiServices 里,返回 POJO 时框架会自动生成 schema 并注入。但要注意:框架的自动重试会掩盖真实问题。默认解析失败会重试若干次,你在日志里看到的是「重试后成功」,看不到「第一次为什么错」。上线前把解析器的 maxRetries 显式设成 1 并打开 debug 日志,排查完再调回去。

【三】业务规则要能被产品读、被测试跑

业务校验写成 Service 里一串 if,问题是产品经理改规则时改不动,测试覆盖也只能靠人肉。建议两条路选一条:规则数少于 15 条、变化不频繁,用 jakarta.validation 注解 + 自定义 ConstraintValidator,干净且零依赖;规则多且需要业务方自己维护,上 Drools 或轻量表达式引擎(SpEL / Aviator),把规则外置成配置文件,改规则不用发版。

无论走哪条,校验失败必须返回结构化错误:{field, code, message}。这份错误同时喂给三个消费者——给模型的重试提示、给用户的可读提示、给监控的告警分类。你只写一遍,三处复用。

【四】常见误区

💻 代码示例

用 Jakarta Validation 做声明式结构校验,再把错误翻译成模型能看懂的重试提示。

public record RefundDecision(
        @NotBlank String orderId,
        @NotNull @DecimalMin("0.01") @DecimalMax("5000.00") BigDecimal amount,
        @NotNull RefundReason reason,
        @Size(max = 200) String explanation) {}

public enum RefundReason {
    LOGISTICS_DELAY, QUALITY_ISSUE, DUPLICATE_ORDER, GOODWILL;

    @JsonCreator
    public static RefundReason from(String raw) {
        String k = raw.trim().toUpperCase().replace('-', '_');
        for (RefundReason r : values()) {
            if (r.name().equals(k)) return r;
        }
        throw new IllegalArgumentException("unknown reason: " + raw);
    }
}

三段式校验编排器:结构、规则、实体存在性,逐层短路并累计错误。

@Service
@RequiredArgsConstructor
public class OutputValidator {

    private final Validator validator;
    private final OrderRepository orderRepository;
    private final ObjectMapper mapper;

    public ValidationOutcome validate(String rawJson) {
        List<FieldError> errors = new ArrayList<>();

        // L1 语法
        RefundDecision d;
        try {
            d = mapper.readValue(stripFence(rawJson), RefundDecision.class);
        } catch (JsonProcessingException e) {
            return ValidationOutcome.syntax(e.getOriginalMessage());
        }

        // L2 结构
        validator.validate(d).forEach(v ->
                errors.add(new FieldError(v.getPropertyPath().toString(), v.getMessage())));

        // L3 业务
        Order order = orderRepository.findById(d.orderId()).orElse(null);
        if (order == null) {
            errors.add(new FieldError("orderId", "订单不存在"));
        } else {
            if (!"PAID".equals(order.status())) {
                errors.add(new FieldError("orderId", "订单状态 " + order.status() + " 不可退款"));
            }
            if (d.amount().compareTo(order.paidAmount()) > 0) {
                errors.add(new FieldError("amount", "退款金额超过实付金额 " + order.paidAmount()));
            }
            if (order.paidAt().isBefore(LocalDateTime.now().minusDays(90))) {
                errors.add(new FieldError("orderId", "超过 90 天退款窗口"));
            }
        }
        return errors.isEmpty() ? ValidationOutcome.ok(d) : ValidationOutcome.business(errors);
    }

    /** 把错误翻译成给模型的下一轮提示,只回复错误字段,避免模型重写正确部分 */
    public String rewriteHint(ValidationOutcome out) {
        return "你的输出存在以下问题,请只修正这些字段后重新输出完整 JSON:\n"
                + out.errors().stream()
                    .map(e -> "- " + e.field() + ": " + e.message())
                    .collect(Collectors.joining("\n"));
    }

    private String stripFence(String s) {
        return s.replaceAll("^```(?:json)?", "").replaceAll("```$", "").trim();
    }

    public record FieldError(String field, String message) {}
}

工具入参这一侧同样要拦,建议在 ToolRegistry 的 invoke 入口统一做:

public String invoke(String tool, String jsonArgs) {
    ToolSpec spec = specs.get(tool);
    if (spec == null) return "ERROR: unknown tool " + tool;
    Set<ConstraintViolation<Object>> vs = validator.forExecutables()
            .validateParameters(spec.target(), spec.method(), spec.bind(jsonArgs));
    if (!vs.isEmpty()) {
        return "ERROR: invalid args " + vs.stream()
                .map(v -> v.getPropertyPath() + " " + v.getMessage()).toList();
    }
    return spec.method().invoke(spec.target(), spec.bind(jsonArgs)).toString();
}

✏️ 今日动手

把退款决策从「模型自由输出文本」改成返回 RefundDecision:① 开启 structured outputs,对比开关前后 50 次调用的解析成功率;② 故意传入超过实付金额的 amount、不存在的 orderId、状态为 CANCELLED 的订单,确认三类业务错误都被拦且提示准确;③ 把 rewriteHint 接进重试,实测「一次重试成功率」——超过 80% 说明提示设计合格,低于 50% 说明 Prompt 里的字段说明不够,先去补 schema 的 description。

🔖 明日预告

校验会失败,失败要重试。但有些操作重试一次就是灾难——明天讲重试策略:把工具按副作用分类,给出「可重试 / 有条件重试 / 绝不重试」三档,以及 Resilience4j 在 Agent 场景下的坑。