tako 文档 GitHub

响应信封统一

模块: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. 证据

5. 现状

仍有效。DELETE /api/dev/reset 是唯一保留旧体的端点,这是刻意例外。