54 lines
4.1 KiB
Markdown
54 lines
4.1 KiB
Markdown
# 服务边界与校验归属
|
|
|
|
- **功能**:规定一条校验该写在哪一层服务里,禁止同一份结构约束在多个服务各写一遍。
|
|
- **何时用**:要给接口加字段校验时;发现某个服务在复核上游返回的结构时;要限制 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 处理。
|