关联：fetch 不会弹出 HTTP Basic 登录框 (fetch does not prompt for HTTP Basic) · Web 登录鉴权 (Session, Cookie, Bearer, JWT)

发生条件

  • 现有 React 管理端用自写 fetchJson，错误只读 data.detail / data.detail.message
  • 后端把 FastAPI HTTPException.detail 收成统一信封 {error:{code,message,...}}
  • 两条路径叠在一起：源 FastAPI 全局 handler 丢掉 detail；Rust 重写若只回信封，前端同样拿不到文案

症状

  • Toast / 终端里错误变成 "{}" 或空对象字符串
  • HTTP 状态码是 400/404/409，用户却看不到「上传记录不存在」「至少需要一个启用的配置」
  • curl 看着信封是对的，浏览器管理台像没接上 API

根因

useApi.js 按 FastAPI 默认错误体写的：

  • 字符串 detail
  • 或对象 detail.message（builder preflight 失败就是这种）

统一 {error:{message}} 对机器客户端更好，但这段前端不会读 error.message。源系统自己的全局 handler 其实也有这个问题；迁移时若「对齐源信封」而不给前端开路，现有页面会静默变差。

处理

  • 响应同时带两套：error 信封（code/message/degraded/retry_after）+ 顶层 detail
  • 普通错误：detail = 字符串 message
  • 结构化失败（如配置预检）：detail = {message, preflight}，让 detail.message 仍能显示
  • 不要为迁就前端改掉信封；也不要只改前端（迁移原则是前端不重写）

下次怎么认

看到「现有 React + FastAPI 风格 fetch + 新后端统一错误信封」，先打开前端错误解析，确认它读的是 detail 还是 error.message。只测 curl/状态码会漏掉这条。

项目证据

  • RoleFit job-admin/frontend/src/hooks/useApi.js
  • rolefit-rs crates/rf-admin/src/error.rs（ApiErrorResponse 增加 detail）

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Web