Files
lpt-meta/.agents/roles/service-boundaries-and-validation.md
T

4.1 KiB

服务边界与校验归属

  • 功能:规定一条校验该写在哪一层服务里,禁止同一份结构约束在多个服务各写一遍。
  • 何时用:要给接口加字段校验时;发现某个服务在复核上游返回的结构时;要限制 LLM 产出格式时;评审跨服务 DTO 与解析代码时;看到「防御式」兜底代码时。

为什么有这条规则

2026-11-18 排查自由回忆草稿保存失败,根因是后端把一份自建严格 ObjectMapper 用在了三个不同方向:前端请求、落盘文档、lpt-ai 返回的 AI 结果。FAIL_ON_MISSING_CREATOR_PROPERTIES 在 record 上会把可选组件也当成必填,于是前端按契约省略 style 就被整单 400。

同一轮审计还发现后端 RecallAiResultValidator 把 lpt-ai 的严格解析器又实现了一遍,而且两套上限已经分叉(限制说明 lpt-ai ≤5 条、后端 ≤12 条)。此前那次「正常 AI 结果被判 INVALID_AI_RESULT」的事故,正是分叉的直接代价。

两次故障是同一个病:服务不相信自己的邻居,于是把对方的规则复述了一遍,复述的东西必然漂移。

规则

R1 结构由产出方保证,接收方只做映射

接口结构一旦协商确定,就由产出方保证自己发出的数据满足它、由接收方保证自己能读懂它,双方都不再复述对方的规则。

  • AI / LLM 输出:结构、字段、条数、枚举、长度上限的校验在 AI 服务内完成(如 lpt-ai 的 normalizeRecallResult),在调用模型的那一侧就解决。
  • 业务后端的 AI 结果处理只做 JSON → DTO 映射与失败分类,不重新校验结构。
  • 前端只校验信封(版本、必要字段存在),不重复业务后端的语义判定。

R2 LLM 的格式约束写在调用模型的那一侧

要限制模型返回内容合法,就在调用模型的服务里校验并做纠正/重试,不把这条规则下放到下游业务服务。下游加一层不会提高模型输出质量,只会在模型正常输出时制造误判。

R3 必需保留的复核只有一种:落库边界的不可信数据

如果本服务把数据落库或直接展示给用户,而该数据的真实性是产品的核心承诺(例如「引文确实取自本次资料」「金额确实来自支付回调」),这条复核必须由本服务自己持有,不能靠上游自证。除此之外不再加复核。

判断式:这条校验是不是只有在「落库边界」才成立? 是 → 本服务做。只是「上游应该已经做过」→ 不做。

R4 反向不适用:接收方必须拒绝的只有类型与未知字段

接收方对输入仍应拒绝真正的类型错误和未知字段(协议漂移信号),但不得把可选字段的缺席当成错误。可选性写进 DTO 就必须真的可选。

R5 发现重复校验时先问「谁的职责」,再删

看到两处做同一件事,先确认哪一层是产出方,删掉非产出方那份;不要因为「多一层更安全」而保留。真需要第二道防线时,用 R3 的判断式说明理由,并写进决策笔记。

边界

  • 本规则约束的是跨服务的规则归属,不禁止单个服务内部的充分校验。服务自己对自己的数据完整性负责,那是分内事。
  • 传输层重试、超时、幂等、鉴权不属于「结构校验」,各服务照常按需实现。
  • 数据已是历史脏数据(旧版本落盘格式)时,接收侧的「读不出来就按损坏处理」不算重复校验,见 lpt-be/.agents/notes/implemented/architecture/2026-11-18-recall-validation-ownership.md。
  • 规则与常识冲突时(例如安全审计要求二次校验),以安全要求为准,并在笔记里写明例外原因。

怎么核对

  • 问「这条规则改了要改几个仓库」:答案大于 1,就说明规则写错了层。
  • 搜索接收侧的解析代码:出现与上游同名的枚举列表、同名的条数上限、同名的长度限制,即为重复校验候选。
  • 跨服务协议调整后,两边的上限与枚举必须能一一对上;对不上就是分叉,按 R5 处理。