Vue 110 ,若依SSE流式接口限次空500排查与解决

前言

大模型接口调用成本高,按天限次基本是标配。我们项目里有一个基于 SSE 流式接口 的扫描功能,后端加了"每个用户每天最多调用 N 次"的限制,超限时抛若依自带的 ServiceException。普通接口这么写没有任何问题,前端能拿到 {code: 500, msg: "..."},弹出提示。换到流式接口上就变了样:页面只剩一行红字 「流式接口 HTTP 500」,DevTools 里连响应体都看不到,用户以为系统挂了。

这篇文章把这个问题从现象到根因、从方案选型到前后端落地完整走一遍。读完能带走四样东西:

  • 为什么 SSE 接口抛业务异常会变成一个空的 500(内容协商的锅,不是若依的 bug)
  • 四种把"次数用完"告诉前端的方案,各自的适用场景
  • 一个可以直接复制的前端流式响应统一检查函数,顺带修掉"登录过期显示成未返回内容"的老问题
  • 一套不依赖后端的本地模拟测试方法和回归脚本,以及我实测出来的几组结果

技术栈:后端 RuoYi-Vue(Spring Boot + Spring MVC),前端 RuoYi-Vue3(Vue 3 + Vite + Element Plus)。思路不挑框架,只要你是"Spring MVC 的 SSE 接口 + 浏览器 fetch 读流",都会遇到同一个坑。


图1 若依 SSE 流式接口限次空 500 排查与解决

一、问题现象:页面上只剩一个 HTTP 500

1.1 业务背景

功能本身不复杂。用户在列表页选一家企业,跳到扫描页,页面自动向后端发一个 POST 请求,后端调用大模型,把报告一段一段通过 SSE 推回来,前端边收边渲染。

因为每次调用都要花钱,后端加了限流:每个用户每天 20 次,计数和判断都在后端完成,超限直接抛异常:

java 复制代码
throw new ServiceException("该接口今日调用次数已用完,每天最多调用" + count + "次");

若依项目里几乎所有业务校验都是这么写的,全局异常处理器会把它转成 JSON 返回。大家都习惯了,没人觉得有问题。

1.2 现象

联调时把上限临时改成 1 次,第二次进入扫描页,页面直接显示红字「流式接口 HTTP 500 」。打开 DevTools 的 Network 面板,stream 请求状态是 500,点开 Response 页签,只有一句 Failed to load response data,如图2所示。


图2 超限时页面只显示 HTTP 500,响应体为空

再看响应头,Content-Length: 0 。也就是说,后端那句"今日调用次数已用完"根本没有发出来。前端不是没解析,是**无内容可解析**。

这一点很关键。很多人第一反应是"前端把 500 的响应体读出来不就行了",但响应体是空的,读也读不到。

1.3 前端当时的代码

流式请求没法用若依封装的 request.js(后面 2.4 节会讲原因),是用 fetch 手写的,出错处理只有一行:

javascript 复制代码
const resp = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'text/event-stream',
    Authorization: 'Bearer ' + getToken()
  },
  body: JSON.stringify(body),
  signal
})

if (!resp.ok) throw new Error(`流式接口 HTTP ${resp.status}`)

页面捕获到这个错误后原样显示。所以用户看到的就是一句开发者才看得懂的话。

问题分成了两半:后端的提示为什么丢了 ,以及前端该怎么知道这是"次数用完"而不是真的故障。

二、原因分析:提示文字去哪了

2.1 普通接口为什么没事

先看正常流程。若依的 GlobalExceptionHandler 里有这么一段:

java 复制代码
@ExceptionHandler(ServiceException.class)
public AjaxResult handleServiceException(ServiceException e, HttpServletRequest request) {
    log.error(e.getMessage(), e);
    Integer code = e.getCode();
    return StringUtils.isNotNull(code)
            ? AjaxResult.error(code, e.getMessage())
            : AjaxResult.error(e.getMessage());
}

方法返回一个 AjaxResult 对象,Spring MVC 负责把它写进响应。写之前要做一件事:内容协商 ------看客户端的 Accept 请求头能接受什么类型,再看手头的消息转换器能产出什么类型,取交集。

普通接口走 axios,Accept 是 application/json, text/plain, */*。Jackson 能把 AjaxResult 转成 application/json,交集非空,于是返回 HTTP 200 + JSON ,业务状态码放在 JSON 的 code 字段里。这就是若依"HTTP 永远 200,看 code 判断成败"的约定。

2.2 SSE 接口差在一个 Accept 头

流式请求的 Accept 是 text/event-stream 。这是 SSE 的规范写法,没毛病。可是异常处理器返回的还是 AjaxResult,Spring 去找"能把 AjaxResult 写成 text/event-stream 的转换器",找不到。

对照 Spring Framework 5.3.x 的源码,后面发生的事情是一条连锁反应,如图3所示:

  1. AbstractMessageConverterMethodProcessor#writeWithMessageConverters 发现可产出类型和可接受类型没有交集 ,抛出 HttpMediaTypeNotAcceptableException。
  2. 这个新异常是在 @ExceptionHandler 方法执行过程中抛的。ExceptionHandlerExceptionResolver 捕获后打一条 WARN 日志 ,内容以 Failure in @ExceptionHandler 开头,然后返回 null,意思是"我处理不了,按原始异常的默认流程走"。
  3. 原始的 ServiceException 没有其他解析器接手,一路抛到 Servlet 容器。容器把状态码置为 500 ,并转发到 Spring Boot 的 /error。
  4. /error 由 BasicErrorController 处理,它也想返回一段 JSON,再次 撞上同一个 Accept 限制。Spring Boot 对这种情况的兜底是:保留状态码,返回空响应体。


图3 一个 Accept 头引发的连锁反应

于是浏览器收到的就是 500 + Content-Length: 0 。原因一句话:客户端声明只收 text/event-stream,服务端的错误信息是 JSON,协商失败,错误信息被整个丢弃。

这里我要交代一句:后端当时的完整日志我没有拿到,上面这条链路是对照源码梳理出来的,不是抓日志看到的。它和现象(500、空响应体、响应头里还带着业务代码设置的自定义头)完全吻合,但严谨起见,下一节给出验证方法,建议你在自己的项目里跑一遍。

2.3 怎么验证是不是这个原因

两条 curl 命令就够了。先用流式的 Accept 请求超限的接口:

bash 复制代码
curl -i -X POST 'http://localhost:8080/api/ai/chat/stream' \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <你的token>' \
  -d '{"query":"test"}'

再把 Accept 换成 JSON,其余不变:

bash 复制代码
curl -i -X POST 'http://localhost:8080/api/ai/chat/stream' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <你的token>' \
  -d '{"query":"test"}'

判断标准见下表:

第一条(text/event-stream) 第二条(application/json) 结论
500,响应体为空 200,返回 {"code":500,"msg":"...已用完..."} 内容协商失败,就是本文说的原因
500,响应体为空 也是 500,响应体为空 不是 Accept 的问题,去查接口上的 produces、过滤器、网关
都能拿到 JSON ------ 你的项目没有这个问题

同时在后端日志里搜两个关键词:Failure in @ExceptionHandler 和 HttpMediaTypeNotAcceptableException。日志级别是 WARN,如果项目把 Spring 的日志调到了 ERROR 以上,会看不到,需要临时调低。

2.4 前端这边还有一层:fetch 不走 axios 拦截器

若依前端的 request.js 是基于 axios 封装的,里面做了三件事:自动带 token、把 code !== 200 的响应转成错误提示、code === 401 时弹出"登录状态已过期"。

流式请求用不了它。浏览器里的 axios 默认走 XHR,拿到的是完整响应 ,做不到边收边渲染。所以流式接口几乎都是用 fetch + ReadableStream 手写。副作用是:request.js 里那套错误处理,对流式请求全部失效。

这直接导致另一个隐蔽的问题。若依的登录过期返回的是 HTTP 200 ,响应体是 {"code":401,"msg":"认证失败,无法访问系统资源"}。对 fetch 来说 resp.ok 是 true,代码继续往下,把这段 JSON 当成 SSE 去解析------一个事件也解析不出来,最后页面显示"未返回内容"。用户根本想不到是登录过期了。

这个问题和限次是同一个根子:流式请求没有自己的响应检查。既然要改,就一起改掉。

2.5 响应体丢了,响应头为什么还在

这是方案能成立的前提,单独说一下。

HTTP 响应分两部分:状态行和响应头在前,响应体在后。response.setHeader() 只是把头记在响应对象上,并没有立刻发给浏览器 ;真正发送要等到响应"提交"(commit)的那一刻。业务代码设置完响应头就抛了异常,此时响应还没有提交,后续的异常处理、/error 转发操作的都是同一个响应对象。从抓包结果看,被改掉的只有状态码和响应体,之前设置的头还留在上面。

所以最终发出去的响应是:状态码 500(容器设的)、X-Daily-Limit(业务代码设的)、空响应体(兜底逻辑决定的)。4.2 节的抓包结果和这个推断一致。

反过来也提醒了一点:如果响应已经提交,头就改不了了 。SSE 接口一旦开始往外推数据,状态码和响应头都已经发出,这时候再 setHeader 是无效的。方案 A 只适用于"还没开始推流"的阶段,流的中途要报错,只能用 3.4 节的办法。

三、方案对比:怎么把"次数用完"告诉前端

3.1 四种方案

想清楚根因之后,可选的路其实不少。我把能想到的四种列在一起:

方案 做法 后端改动 前端改动 主要问题
A 自定义响应头 抛异常前 setHeader("X-Daily-Limit", ...),响应仍是空 500 两行 读响应头判断 状态码语义不准;跨域要额外暴露响应头
B 429 + JSON 响应体 直接往 response 写 JSON,或让异常处理器显式指定 Content-Type 中等 按状态码 + JSON 判断 要绕开内容协商,改动点比 A 多
C SSE 错误事件 照常返回 200 的事件流,第一条推 event: error 较大 解析器里加事件分支 限流逻辑要挪进流里,拦截器/切面里做不了
D 先查后调 加一个"剩余次数"查询接口,前端发起前先问 新增接口 多一次请求 有并发窗口,查的时候有、调的时候没了,还是得兜底

方案 B 的两种写法值得展开。第一种是在拦截器里自己写响应,完全不经过消息转换器:

java 复制代码
response.setStatus(429);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{\"code\":429,\"msg\":\"今日调用次数已用完\"}");
return false; // HandlerInterceptor#preHandle 返回 false,请求到此结束

第二种是给限流单独定义一个异常,在异常处理器里返回 ResponseEntity 并显式设置 Content-Type 。Spring Framework 从 5.2 开始,返回值里预设了具体的 Content-Type 时会直接采用,不再拿去和 Accept 取交集:

java 复制代码
@ExceptionHandler(DailyLimitException.class)
public ResponseEntity<AjaxResult> handleDailyLimit(DailyLimitException e) {
    return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
            .contentType(MediaType.APPLICATION_JSON)
            .body(AjaxResult.error(429, e.getMessage()));
}

这两段是方案说明,我们最终没有采用,上线前务必用 2.3 节的 curl 验证一遍,不同 Spring 版本在细节上可能有差别。

3.2 我们选了方案 A

理由很现实:

  • 改动最小 。限流逻辑已经写好并且在别的接口上用着,加两行 setHeader 就能发版。
  • 不依赖响应体 。既然响应体会被丢,那就把信息放在一个不会被丢的地方。实测抛异常之前设置的响应头,在最终的空 500 响应里是保留的。
  • 前端判断简单。有这个头就是次数用完,没有就是别的错误,不需要解析任何内容。

代价是状态码仍然是 500。对用户没影响,但对运维有影响:监控和日志里它会被算成一次服务器故障。如果你们有基于 5xx 比例的告警,要么把带 X-Daily-Limit 头的请求排除掉,要么直接上方案 B。

3.3 什么时候该选别的

给一个简单的判断:

  • 内部系统、同源部署、想快点上线 → 方案 A。
  • 对外开放的 API、有监控告警、接口文档要给第三方看 → 方案 B,429 Too Many Requests 是 RFC 6585 专门为限流定义的状态码,还可以配合 Retry-After 告诉客户端多久之后再试。
  • 限流发生在流的中途(比如按 token 用量计费,生成到一半额度用完) → 只能是方案 C,这时候响应头早就发出去了,状态码和响应头都改不了。
  • 方案 D 不能单独用。它适合做"按钮上显示今日剩余 3 次"这种体验优化,但后端的兜底校验和前端的超限处理一样都不能少。

前端这边,我的做法是按方案 A 实现,同时兼容 429。这样后端哪天把状态码改了,前端一行都不用动。

3.4 方案 C 长什么样

方案 C 我们这次没用,但它是唯一能覆盖"流的中途出错"的办法,值得把样子摆出来。后端不再抛异常,而是正常建立事件流,把错误作为一条具名事件推给前端,随即结束:

java 复制代码
SseEmitter emitter = new SseEmitter(0L);
if (overLimit) {
    emitter.send(SseEmitter.event()
            .name("error")
            .data("{\"code\":\"DAILY_LIMIT\",\"msg\":\"今日调用次数已用完\"}"));
    emitter.complete();
    return emitter;
}

此时 HTTP 状态码是 200 ,Content-Type 是 text/event-stream,内容协商完全不会出问题。前端的解析器要认得 event: 这一行:

javascript 复制代码
/** 把一个 SSE 事件块拆成 { event, data };没有 event 行时默认是 message */
function parseSseBlock(block) {
  let event = 'message'
  const data = []
  for (const line of block.split('\n')) {
    if (line.startsWith('event:')) event = line.slice(6).trim()
    else if (line.startsWith('data:')) data.push(line.slice(5).trim())
  }
  return { event, data: data.join('\n') }
}

// 读流循环里,对每个事件块:
function handleBlock(block, onDelta) {
  const { event, data } = parseSseBlock(block)
  if (!data || data === '[DONE]') return
  const payload = JSON.parse(data)
  if (event === 'error') {
    throw Object.assign(new Error(payload.msg || '请求失败'), { code: payload.code })
  }
  onDelta && onDelta(payload)
}

它的好处是错误信息想带多少带多少 ,中文也不受限制。不方便的地方有两个:一是限流判断必须写在控制器方法内部,切面和拦截器里拿不到 SseEmitter;二是状态码永远是 200,网关和监控层面完全看不出这次请求被限流了,统计只能靠业务日志。

很多大模型服务商的流式接口同时用了两种手段:请求一开始就能判断的错误 (鉴权失败、额度不足、参数不合法)走 HTTP 状态码加 JSON;生成过程中才出现的错误(内容审核中断、上游超时)走流内的错误事件。分工很清楚,自己设计接口时可以照这个思路来。

四、后端实现:响应头方案的细节

后端代码不是我写的。下面这段里,设置响应头的几行是同事的实际改动,前面的计数部分是我按常见写法补的示意,方便把前后端对上。

4.1 设置响应头,再抛异常

限流用的是切面,核心就这么几行:

java 复制代码
String key = "daily_limit:" + userId + ":" + LocalDate.now();
Long used = redisTemplate.opsForValue().increment(key);
if (used != null && used == 1L) {
    redisTemplate.expire(key, 1, TimeUnit.DAYS);
}

if (used != null && used > count) {
    HttpServletResponse response = ServletUtils.getResponse();
    if (response != null) {
        response.setHeader("X-Daily-Limit", String.valueOf(count));
        // 前后端跨域部署时,允许前端脚本读取这个响应头
        response.setHeader("Access-Control-Expose-Headers", "X-Daily-Limit");
    }
    throw new ServiceException("该接口今日调用次数已用完,每天最多调用" + count + "次");
}

三个要点:

  • 顺序不能反 。必须先 setHeader 再 throw,异常抛出之后这段代码就不会再执行了。
  • 头的值只放数字 。这里放的是每天的上限 count。为什么不放提示文字,4.3 节说。
  • ServiceException 照抛。它在流式接口上虽然发不出响应体,但普通接口复用同一个切面时还能正常返回 JSON,两边都不耽误。

4.2 Access-Control-Expose-Headers 到底要不要加

联调时这个头引起过一点讨论。结论是:同源不需要,跨域必须有。

浏览器对跨域响应有一条限制:脚本默认只能读到少数几个"安全"的响应头,包括 Cache-Control、Content-Language、Content-Length、Content-Type、Expires、Last-Modified、Pragma。自定义的 X-Daily-Limit 不在其中。这时候会出现一个很迷惑的现象:DevTools 的 Network 面板里明明看得到这个头,resp.headers.get('X-Daily-Limit') 却返回 null。

加上 Access-Control-Expose-Headers: X-Daily-Limit 之后,脚本才读得到。后端加完的实际响应如图4所示(截图里 X-Daily-Limit 的值是 1,因为联调时临时把上限调成了 1 次)。


图4 超限时的响应头:X-Daily-Limit 与 Access-Control-Expose-Headers

我们的前端开发环境用 Vite 代理、生产环境用 Nginx 反向代理,浏览器看到的都是同源请求,严格说用不上这个头。但后端加上没有任何坏处,哪天换成跨域部署也不用再改,所以保留了。跨域和同源的对照实验结果放在 6.3 节。

4.3 响应头的三个限制

不要放中文。 HTTP 头的值按规范应当是 ASCII 可见字符。我用 Node.js 22 试了一下,res.setHeader('X-Limit-Msg', '今日次数已用完') 直接抛 ERR_INVALID_CHAR: Invalid character in header content 。Java 这边不同容器的表现不一样,有的会把中文变成乱码。所以头里只放数字或英文代码,提示文案由前端决定。一定要传中文的话,后端 URLEncoder.encode,前端 decodeURIComponent,实测可以正确还原。

名字大小写不敏感,但别依赖原样。 HTTP/2 下响应头名会统一变成小写,DevTools 里看到的可能是 x-daily-limit。headers.get() 本身不区分大小写,用它读没问题;自己遍历 headers 做字符串比较就容易出错。

中间层可能把它弄丢。 这个放到注意事项里细说。

五、前端实现:流式响应的统一检查

5.1 一个函数管住所有异常响应

核心思路:fetch 返回之后、开始读流之前,先过一遍检查 。正常的事件流放行,其余情况统一转成带 code 的 Error,页面按 code 决定怎么提示。

javascript 复制代码
/**
 * 流式接口失败时抛出的 Error 带 code:
 *   DAILY_LIMIT  今日调用次数已用完:空的 500 + 响应头 X-Daily-Limit;也兼容 429
 *   AUTH         登录已过期:若依鉴权失败返回的是 200 + JSON { code: 401 }
 *   BUSINESS     后端返回 200,但给的是 JSON 业务错误而不是事件流
 *   HTTP         其他非 2xx
 */
export const STREAM_ERROR = Object.freeze({
  DAILY_LIMIT: 'DAILY_LIMIT',
  AUTH: 'AUTH',
  BUSINESS: 'BUSINESS',
  HTTP: 'HTTP'
})

function streamError(code, message, extra = {}) {
  return Object.assign(new Error(message), { code, ...extra })
}

/** 读 JSON 响应体;为空、不是 JSON 或读取失败都返回 null */
async function readJsonBody(resp) {
  try {
    const text = await resp.text()
    return text ? JSON.parse(text) : null
  } catch (e) {
    return null
  }
}

/** 正常的事件流直接放行,其余情况统一转成带 code 的 Error */
export async function assertStreamResponse(resp) {
  const contentType = (resp.headers.get('content-type') || '').toLowerCase()
  if (resp.ok && !contentType.includes('application/json')) return

  // 超限时响应体为空,只能看响应头
  if (resp.headers.get('X-Daily-Limit') !== null || resp.status === 429) {
    throw streamError(STREAM_ERROR.DAILY_LIMIT, '今日调用次数已用完', { status: resp.status })
  }

  const body = await readJsonBody(resp)
  const code = Number(body && body.code)
  const msg = String((body && body.msg) || '').trim()

  if (code === 401 || resp.status === 401) {
    throw streamError(STREAM_ERROR.AUTH, '登录状态已过期,请重新登录后再试', { status: 401 })
  }
  if (resp.ok) {
    throw streamError(STREAM_ERROR.BUSINESS,
      (code && code !== 200 && msg) || '服务返回格式异常,请稍后重试',
      { status: code || resp.status })
  }
  throw streamError(STREAM_ERROR.HTTP,
    msg || `服务暂时不可用,请稍后重试(HTTP ${resp.status})`,
    { status: resp.status })
}

判断顺序如图5所示,有几处是特意这么排的:


图5 assertStreamResponse 的判断顺序

  • 第一行的放行条件是"状态码成功,并且不是 JSON" 。只判断 resp.ok 不够,若依的登录过期就是 200。也不建议写成"必须是 text/event-stream",有些网关会改写或丢掉 Content-Type,卡太死容易误伤。
  • 次数用完的判断放在读响应体之前。它的响应体本来就是空的,没必要读。
  • 正常响应即使带了 X-Daily-Limit 头也不受影响。有的后端会在每次响应里都带上限额信息,第一行已经把正常流放走了,不会误判。
  • readJsonBody 吞掉所有异常。错误响应的响应体可能是空的、可能是 HTML 错误页,解析失败不应该盖住真正的错误。
  • 兜底文案保留状态码。「服务暂时不可用,请稍后重试(HTTP 500)」比「流式接口 HTTP 500」对用户友好,又不妨碍排查。

5.2 接入流式函数

接入只改一行。原来的 if (!resp.ok) throw ... 换成:

javascript 复制代码
export async function chatStream(url, body, { onDelta, signal } = {}) {
  const resp = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'text/event-stream',
      Authorization: 'Bearer ' + getToken()
    },
    body: JSON.stringify(body),
    signal
  })

  await assertStreamResponse(resp)
  if (!resp.body) throw new Error('当前环境不支持流式读取')

  const reader = resp.body.getReader()
  const decoder = new TextDecoder('utf-8')
  let buffer = ''
  for (;;) {
    const { done, value } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })
    let idx
    while ((idx = buffer.indexOf('\n\n')) >= 0) {
      const block = buffer.slice(0, idx)
      buffer = buffer.slice(idx + 2)
      const data = block.split('\n')
        .filter(line => line.startsWith('data:'))
        .map(line => line.slice(5).trim())
        .join('\n')
      if (!data || data === '[DONE]') continue
      onDelta && onDelta(JSON.parse(data))
    }
  }
}

项目里有两个流式函数共用同一个后端接口,我把它们都改成了调用 assertStreamResponse。后端如果是按接口计次,两个入口都会被限制,只改其中一个会留下漏网的。

5.3 页面提示:这是规则,不是故障

拿到 code 之后,页面上怎么显示,我改了三处。

用提示样式,不用报错样式。 次数用完是产品规则生效了,系统没有出任何问题。红色报错会让用户以为功能坏了,然后去找客服。我换成了 Element Plus 的 warning 色系:浅黄底、一个警示图标、一句话。改造前后的对比如图6所示。


图6 改造前显示 HTTP 500,改造后显示次数用完的提示

不重复弹窗。 原来的逻辑是气泡里显示一遍错误,顶部再弹一个 ElMessage。同一句话出现两次,没有必要。现在次数用完只在气泡里显示;只有一种情况例外------用户等待期间切到了别的会话,看不到那个气泡,这时才补一条 warning 提示。

javascript 复制代码
try {
  await chatStream(url, body, { onDelta, signal })
} catch (err) {
  if (err?.code === STREAM_ERROR.DAILY_LIMIT) {
    limitNotice = '今日深度扫描次数已用完'   // 气泡里的黄色提示
  } else {
    errorMsg = err.message || '请求失败'  // 其余情况仍按报错处理
  }
}

文案上我一开始写的是「今日次数已用完(每天最多 20 次),请明天再来」,后来定下来只保留前半句,不展示具体上限。所以响应头里的数字现在只用来判断有没有,不读它的值。这也说明把文案放在前端是对的,改一句话不需要后端发版。

不要自动降级重试 。这个坑比较隐蔽。项目里原来有一段兜底逻辑:流式请求失败且一个字都没收到时,自动改走非流式接口再请求一次。初衷是对付网络抖动。但放在限次场景下,它等于帮用户绕过限制多试了一次------如果非流式接口没有同样的限流,就真的绕过去了;如果有,也是白白多打一次后端。改法是在降级之前先判断错误类型:

javascript 复制代码
if (err?.code === STREAM_ERROR.DAILY_LIMIT || err?.code === STREAM_ERROR.AUTH) throw err
const res = await chatFallback(body)   // 只有网络类错误才走到这里

5.4 顺手修掉的登录过期问题

有了统一检查,2.4 节说的那个问题自然就解决了。若依返回 200 + {"code":401} 时,assertStreamResponse 第一行就拦下来:状态码虽然成功,但 Content-Type 是 application/json,不放行;接着读出 code === 401,抛出 AUTH 错误,页面显示「登录状态已过期,请重新登录后再试」。

要不要在这里直接调若依的 logOut 跳登录页,看各自项目的习惯。我没有加,原因是流式请求往往发生在一个比较长的操作中途,直接跳走会让用户丢失页面状态,给个明确提示让他自己决定更稳妥。

六、本地模拟测试:不等后端也能测

限次这类场景有个麻烦:要触发它,得真的把次数用完,而且一天只能测一轮。联调时后端可以临时把上限改成 1,但前端自己开发、回归的时候不能总去麻烦后端。我的做法是本地起一个小服务,把各种异常响应都模拟出来。

6.1 一个几十行的 Node 模拟服务

javascript 复制代码
// mock-server.cjs
const http = require('http')

http.createServer((req, res) => {
  const { pathname } = new URL(req.url, 'http://localhost')

  if (pathname === '/limit') {              // 次数用完:空的 500 + 响应头
    res.setHeader('X-Daily-Limit', '20')
    res.writeHead(500, { 'Content-Length': 0 })
    return res.end()
  }
  if (pathname === '/429') {                // 次数用完:429
    res.writeHead(429, { 'Retry-After': '3600' })
    return res.end()
  }
  if (pathname === '/h500') {               // 普通的空 500
    res.writeHead(500)
    return res.end()
  }
  if (pathname === '/h500json') {           // 500,带后端提示
    res.writeHead(500, { 'Content-Type': 'application/json' })
    return res.end(JSON.stringify({ code: 500, msg: '扫描服务连接超时' }))
  }
  if (pathname === '/auth') {               // 若依风格的登录过期:200 + JSON
    res.setHeader('Content-Type', 'application/json;charset=UTF-8')
    return res.end(JSON.stringify({ code: 401, msg: '认证失败,无法访问系统资源' }))
  }
  if (pathname === '/sse') {                // 正常的事件流
    res.writeHead(200, { 'Content-Type': 'text/event-stream' })
    let i = 0
    const timer = setInterval(() => {
      res.write(`data: {"delta":"片段${++i}"}\n\n`)
      if (i === 3) { clearInterval(timer); res.write('data: [DONE]\n\n'); res.end() }
    }, 50)
    return
  }
  res.writeHead(404)
  res.end()
}).listen(7001)

在 Vite 的代理配置里把流式接口指到它,或者在页面里临时把请求地址换掉,就可以逐个场景看页面表现。

6.2 各场景的实测结果

下面是把 5.1、5.2 节的代码对着这个模拟服务跑出来的结果。实测环境:Node.js 22.23、Chromium 153(通过 Playwright 1.63 驱动)。

场景 模拟的响应 抛出的 code 提示文案
正常 200 + text/event-stream 不抛错 依次收到 3 个片段
次数用完 500 + X-Daily-Limit: 20,空响应体 DAILY_LIMIT 今日调用次数已用完
次数用完 429,空响应体 DAILY_LIMIT 今日调用次数已用完
服务故障 500,空响应体 HTTP 服务暂时不可用,请稍后重试(HTTP 500)
服务故障 500 + JSON msg HTTP 扫描服务连接超时
登录过期 200 + {"code":401} AUTH 登录状态已过期,请重新登录后再试

我还特意用改造前的写法(只判断 resp.ok)跑了一次登录过期场景:resp.ok 为 true,SSE 解析器解析出 0 个事件,那段 JSON 原封不动留在缓冲区里没人管。这就是页面显示"未返回内容"的由来。

6.3 跨域对照实验

为了确认 4.2 节的结论,我起了两个端口,页面在 7001,接口分别用同源和跨域(7002)访问,读同一个响应头:

访问方式 Access-Control-Expose-Headers resp.headers.get('X-Daily-Limit')
同源 无 "20"
跨域 无 null
跨域 X-Daily-Limit "20"

三种情况下 DevTools 的 Network 面板里都能看到这个头。所以排查这类问题时,不要以 Network 面板为准,要在 Console 里实际执行一次 headers.get()。

6.4 把这些场景固化成回归脚本

手动点一遍只能保证当下没问题。流式请求这块代码后面还会改,我把上面的场景写成了一个 Playwright 脚本,每次改完跑一下,很快就能出结果:

javascript 复制代码
// check-stream.cjs
const { chromium } = require('playwright')

const CASES = [
  { path: '/limit',    expect: 'DAILY_LIMIT' },
  { path: '/429',      expect: 'DAILY_LIMIT' },
  { path: '/h500',     expect: 'HTTP' },
  { path: '/h500json', expect: 'HTTP' },
  { path: '/auth',     expect: 'AUTH' },
  { path: '/sse',      expect: null }
]

;(async () => {
  const browser = await chromium.launch()
  const page = await browser.newPage()
  await page.goto('http://localhost:5173/')          // 本地开发服务的地址

  for (const item of CASES) {
    const code = await page.evaluate(async path => {
      const { chatStream } = await import('/src/api/stream.js')
      try {
        await chatStream('/mock' + path, {})
        return null
      } catch (e) {
        return e.code || 'UNKNOWN'
      }
    }, item.path)
    console.log(code === item.expect ? 'PASS' : 'FAIL', item.path, code)
  }
  await browser.close()
})()

脚本里的 /src/api/stream.js 和 /mock 前缀按自己项目的路径和代理配置改。要点是在真实浏览器里跑 。跨域响应头的可见性、fetch 对响应体的处理,这些行为 Node 环境和浏览器并不完全一样,6.3 节那组对照结果在 Node 里是测不出来的。

页面层面的检查也可以加进去:次数用完时气泡里出现的是提示样式而不是报错样式、顶部没有弹出红色消息。这两条我在这次改动里都用脚本检查过。

七、注意事项

1. 空 500 不等于"后端没处理"。 看到 Content-Length: 0 的 500,先别急着让后端查业务代码。用 2.3 节的方法换一个 Accept 再请求一次,如果 JSON 出来了,问题在内容协商,业务逻辑是好的。这一步能省掉很多来回扯皮的时间。

2. Nginx 的 add_header 默认不作用于 5xx。 如果跨域相关的响应头(包括 Access-Control-Allow-Origin 和 Access-Control-Expose-Headers)是在 Nginx 里统一加的,注意 add_header 指令默认只对 200、204、301、302、304 等状态码生效,500 的响应上不会有。表现就是:正常请求一切正常,一到超限,浏览器报跨域错误,连状态码都读不到。解法是加上 always 参数:add_header Access-Control-Expose-Headers "X-Daily-Limit" always;。

3. 网关的错误页会吃掉响应头。 Nginx 开了 proxy_intercept_errors on 并配置了 error_page 500,或者前面有统一错误页的网关、WAF 时,后端的 500 响应会被整个替换,自定义头自然也没了。这种部署环境下方案 A 走不通,换成 429,或者在网关上对这个路径放行。

4. 原生 EventSource 做不了这件事。 它只支持 GET、不能自定义请求头,出错时 onerror 回调里拿不到状态码也拿不到响应头 。需要鉴权或者需要区分错误类型的流式接口,老老实实用 fetch。

5. 响应体只能读一次。 assertStreamResponse 在错误分支里调用了 resp.text(),之后这个响应就不能再读了。因为错误分支一定会抛异常,所以没有问题;但如果你想改成"检查完继续用",记得先 resp.clone()。

6. 不要把"已用完"缓存在前端。 我考虑过超限之后在 localStorage 记一个标记,当天不再发请求。最后没做:后端的重置时间、是否被管理员手动清零、用户是否换了账号,前端都不知道。计数和判断只放在后端,前端每次都如实发请求、如实展示结果,逻辑最简单,也最不容易出错。

7. 被拦下的请求算不算一次,要跟后端对清楚。 先 increment 再判断的写法,超限后的每次请求仍然会让计数加一。对"每天 N 次"的硬限制没有影响,但如果后面要做"显示今日已用次数",数字会偏大。

8. 前端页面别在刷新时重复发起。 我们的扫描页是带参数跳转进来后自动发起请求的。如果参数留在地址栏里,用户每刷新一次就扣一次。处理方式是发起前先把地址栏里的参数清掉。限次功能上线之前,这类"自动触发"的入口值得全部过一遍。

9. 版本差异。 本文的源码分析基于 Spring Framework 5.3.x / Spring Boot 2.5.x(RuoYi-Vue 3.8.x 使用的版本线)。Spring Boot 3.x 对应的 Spring Framework 6.x 在错误响应上有调整,较新的版本还支持在 @ExceptionHandler 上直接声明 produces。具体行为以你所用版本的官方文档和实测为准。

八、本文总结

回到最初的问题:一个在普通接口上工作良好的 throw new ServiceException(...),为什么到了 SSE 接口上就变成空的 500?

答案是内容协商 。客户端用 Accept: text/event-stream 声明只接受事件流,全局异常处理器想返回 JSON,两边对不上,错误信息被丢弃。这不是若依的缺陷,任何"JSON 统一异常处理 + SSE 接口"的 Spring MVC 项目都有同样的行为。

可以带走的几个判断:

  • 流式接口的错误,要么放在响应头和状态码里,要么放在流里,不要指望一个会被协商掉的 JSON 响应体。
  • 赶进度、同源部署 ,用自定义响应头,两行代码解决;对外接口、有 5xx 告警 ,用 429 加显式 Content-Type 的 JSON;流的中途才知道要中断,用 SSE 的错误事件。
  • 前端凡是用 fetch 手写的流式请求,都应该有一个统一的响应检查。它不只服务于限次,登录过期、业务错误、网关错误页都靠它兜住。
  • 次数用完是规则不是故障,提示样式、弹窗次数、是否自动重试,都要按这个定位重新审视一遍。

这个问题本身不大,后端两行、前端几十行。但它正好踩在 Spring 的内容协商、浏览器的跨域响应头限制、若依的"HTTP 200 + 业务 code"约定这三件事的交界处,任何一处没想清楚,联调时都要多绕一圈。

九、更多操作

本文涉及的规范和官方文档,想深入的话可以从这里看起:

框架和浏览器都在持续更新,文中的源码细节和行为描述对应写作时的版本,遇到出入请以官方文档为准。

可以继续深挖的方向:把限额信息做成标准的 RateLimit-* 系列响应头;在 SSE 流里设计统一的错误事件格式;给流式请求加上超时与断线重连。

更多前端实战内容,请看 Vue 个人专栏。

本文属于 Vue 企业级实战系列,持续更新 Vue2/Vue3、工程化、性能优化、跨域解决方案等干货,欢迎关注我的 CSDN 专栏:

👉 Vue Develop 实战专栏

本专栏聚焦 Vue(Vue2/Vue3)企业级实战开发。涵盖组件封装、组合式 API、前端工程化、状态管理、性能优化、项目架构,搭配 Element、ECharts 业务实战。汇集真实项目开发经验与避坑方案,帮你搭建完整 Vue 技术体系,持续更新硬核实战内容。

以及

👉 Electron + Vue 桌面应用专栏

本专栏聚焦 Electron + Vue 桌面应用实战,系统讲解 Vue3 与 Electron 的整合实践,涵盖环境搭建、主进程与渲染进程通信、预加载脚本、窗口菜单、打包发布、自动更新及安全实践,帮助前端开发者从零构建跨平台桌面应用。

如果本文对你有帮助,欢迎点赞、收藏、评论,你的支持是我持续输出实战干货的动力!

如果你在项目中也遇到类似问题,欢迎留言交流,分享你的场景与解决方案。

相关推荐
程序员韩星34 分钟前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson34 分钟前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
ServBay39 分钟前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho1 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
其实防守也摸鱼1 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊2 小时前
CNC计算机数控加工模拟器
前端
张一凡932 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
Brookty2 小时前
CSS基础知识(一):选择器、优先级、层叠与继承、边框属性及盒模型
前端·css
00后程序员2 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios