响应信封统一
模块:HTTP 端点层(
internal/runengine/+web/src/api.ts)| 状态:已落地(cd85050,2026-10-22)| 证据:doc/40-响应信封统一.md、tmp/A7-信封迁移/planning.md
1. 场景与病灶
前端要在拦截器里统一弹错、按业务码跳登录页。但后端当时一半接口回 {"error":"session_not_found"},一半回裸对象,还有 204 无 body。
结果是每个端点各自判定错误形状,前端散落魔法字符串;登录失败弹一句、会话 404 再弹另一套;新增端点就多一处漂移。
2. 候选与代价
| 问题 | 候选 | 好处 | 代价 |
|---|---|---|---|
| 统一还是保留 | A 保留旧体 | 不动前端 | 永久分叉 |
B 统一 {code, message, data},顺序固定(定案) |
一次拦截器、业务码可分支 | 全量替换、期间前端坏 | |
| 迁移节奏 | A 加兼容层 / 过渡开关 | 期间前端不坏 | 临时分支永远转不了正,最后没人敢删 |
| B 后端逐拍换 + 前端在最后一拍一次性换(定案) | 终态干净 | 中间几拍本地前端坏,验收靠 curl | |
| media 成功体套不套 | A 套 | 形式统一 | 图片变 base64 JSON,推翻「对话只存 path、显示时才换字节」的设计 |
| B 成功体保持字节,只换错误分支(定案) | 流式、零拷贝 | 一处不统一 | |
DELETE /api/dev/reset 换不换 |
A 一起换 | 全仓零旧体 | 碰全库 TRUNCATE 端点,零收益、手滑风险极高 |
| B 刻意保留旧体,写成唯一例外(定案) | 零风险 | 全仓唯一例外 |
裁定:B / B / B / B。
3. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 字段顺序要固定吗? | 固定 code → message → data |
前端与验收字节可逐字比对 |
失败时 data 能省吗? |
不能省,没有内容就是 null |
省掉字段会让前端拆包多一种分支 |
| HTTP 状态要不要也改成 200? | 不改,照旧 400/401/403/404/409/429/500 | 状态给网关分类,业务码给页面区分同一种状态里的不同原因 |
| 已验收的老接口(runs/sessions/mcp/media/memory)怎么办? | 仍是旧体,单独一拍改 | 不借别的任务顺手换 |
| 业务码表在哪? | doc/28 §5.4 |
前端靠它分支,不拆 message 句子 |
4. 证据
- 方案:
doc/40-响应信封统一.md§1(病灶)、§6(三样不动)、§8(已拍 D1/D2)。 - 台账:
tmp/A7-信封迁移/planning.md§0 边界、§5 已拍、§8 A7-1…A7-8。 - 代码:
auth.go的writeEnvelope;envelope_test.go的TestInternalEnvelope;api.ts(唯一拆包入口:成功剥data、失败抛ApiError);server.go的getMedia(成功走ServeContent)。 - 复核命令:
grep -n "func writeEnvelope" yk-tako-eino/internal/runengine/auth.go。
5. 现状
仍有效。DELETE /api/dev/reset 是唯一保留旧体的端点,这是刻意例外。