weichen
c41087cf39
Why: both 2026-09-30 incidents produced reusable causal knowledge (nil-slice JSON null vs .map; shared-checkout conflicts and gitlinks pinning unpushed commits) that meets the lesson bar of trigger, mechanism, checks, and verified guards. Evidence: incident records and fix PRs referenced inline; guards validated in policy/adoption.md and the tool-adaptation matrices. Impact: record-only; documents no product code. Refs: Agent-System-Dev 8f7cf2d; Agent-System-Backend fix/empty-list-json
1.5 KiB
1.5 KiB
经验：Go nil 切片序列化为 JSON null 导致前端 .map 白屏
- 状态：validated（2026-09-30，Agent-System 0.1.0+多租户链）
- 触发条件/检索词：白屏 / Cannot read properties of null (reading 'map') / 空列表 / 新建项目后页面空 / conversations null / Go nil slice json
- 根因与来源：backend store 层
var out []T空结果为 nil 切片，encoding/json 编码为null；前端契约声明T[]并直接.map。2026-09-30 新建项目实测 GET /api/projects/{id}/conversations 返回null。修复提交见 Agent-System-Backend fix/empty-list-json（PR#2）。 - 下次应做的检查：新增任何列表出口时问一句"空结果返回什么"——对空集合先写回归断言
json.Marshal(empty) == "[]"；code review 对 store 层var out []模式保持警觉。 - 验证方法与防护：已落实 TestEmptyListsSerializeAsEmptyArrays（store 回归）；修复后实测新项目 conversations/artifacts 均返回
[]。建议：前端对网络数据保留?? []兜底（未落实）。 - 适用与不适用：适用 Go 后端 + 任何把 JSON 反序列化结果当数组用的前端；不适用已显式区分 null/[] 语义的接口设计。
- 尚缺证据/防护：前端全局兜底未加；无 CI 级契约测试。
- 复核人、日期、版本：weichen，2026-09-30，组合 main 36d1393+
- 替代/退役条件：若引入契约级生成（OpenAPI/TS 类型 + 服务端校验）可吸收本检查，届时退役。