前言
大模型接口调用成本高,按天限次基本是标配。我们项目里有一个基于 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所示:
AbstractMessageConverterMethodProcessor#writeWithMessageConverters发现可产出类型和可接受类型没有交集 ,抛出HttpMediaTypeNotAcceptableException。- 这个新异常是在
@ExceptionHandler方法执行过程中抛的。ExceptionHandlerExceptionResolver捕获后打一条 WARN 日志 ,内容以Failure in @ExceptionHandler开头,然后返回null,意思是"我处理不了,按原始异常的默认流程走"。 - 原始的
ServiceException没有其他解析器接手,一路抛到 Servlet 容器。容器把状态码置为 500 ,并转发到 Spring Boot 的/error。 /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"约定这三件事的交界处,任何一处没想清楚,联调时都要多绕一圈。
九、更多操作
本文涉及的规范和官方文档,想深入的话可以从这里看起:
- Access-Control-Expose-Headers(MDN):https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Access-Control-Expose-Headers
- 429 Too Many Requests(RFC 6585):https://www.rfc-editor.org/rfc/rfc6585
- Server-Sent Events 规范(WHATWG):https://html.spec.whatwg.org/multipage/server-sent-events.html
- Spring MVC 异常处理(官方文档):https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-exceptionhandler.html
- RuoYi-Vue(MIT 许可):https://gitee.com/y_project/RuoYi-Vue
框架和浏览器都在持续更新,文中的源码细节和行为描述对应写作时的版本,遇到出入请以官方文档为准。
可以继续深挖的方向:把限额信息做成标准的 RateLimit-* 系列响应头;在 SSE 流里设计统一的错误事件格式;给流式请求加上超时与断线重连。
更多前端实战内容,请看 Vue 个人专栏。
本文属于 Vue 企业级实战系列,持续更新 Vue2/Vue3、工程化、性能优化、跨域解决方案等干货,欢迎关注我的 CSDN 专栏:
本专栏聚焦 Vue(Vue2/Vue3)企业级实战开发。涵盖组件封装、组合式 API、前端工程化、状态管理、性能优化、项目架构,搭配 Element、ECharts 业务实战。汇集真实项目开发经验与避坑方案,帮你搭建完整 Vue 技术体系,持续更新硬核实战内容。
以及
本专栏聚焦 Electron + Vue 桌面应用实战,系统讲解 Vue3 与 Electron 的整合实践,涵盖环境搭建、主进程与渲染进程通信、预加载脚本、窗口菜单、打包发布、自动更新及安全实践,帮助前端开发者从零构建跨平台桌面应用。
如果本文对你有帮助,欢迎点赞、收藏、评论,你的支持是我持续输出实战干货的动力!
如果你在项目中也遇到类似问题,欢迎留言交流,分享你的场景与解决方案。
