🎯 今日核心问题
- Schema 校验通过但业务上完全错误,这类问题该怎么分层拦?
- LangChain4j 的输出解析失败时,怎么让重试带着「哪一行错了」回去,而不是整段重来?
- 业务规则写在 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}。这份错误同时喂给三个消费者——给模型的重试提示、给用户的可读提示、给监控的告警分类。你只写一遍,三处复用。
【四】常见误区
- ❌ 用
Map<String,Object>接模型输出。类型全丢了,schema 校验形同虚设;用 record/DTO 并开启 fail-on-unknown-properties。 - ❌ 把枚举写成 String。模型很容易写近义词(「已完成」vs「DONE」),枚举 +
@JsonCreator别名映射 + 大小写归一化是必需的。 - ❌ 业务校验失败也重试。这会烧三次 token 得到一个同样错的结果,还可能因为随机性碰巧通过,把脏数据写进库。
- ❌ 只校验模型输出,不校验工具入参。模型给
refund(amount=-100)时,拦在工具入口比拦在最终答复上更早、更安全。
💻 代码示例
用 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 场景下的坑。