麻雀窝 Sparrow Zoo

HTTP 状态码与 Result:前后端同步的底层接口协议

从业务异常、MVC 解析错误到认证过滤器与 Fetcher,说明 HTTP 状态和 Result 各管什么、如何同步处理,以及当前仍需补齐的边界。

适合维护 Spring MVC、统一 Result 响应体和 sparrow-js Fetcher 的前后端开发者。发布于 更新于
HTTP × Result两层信息,一条明确约定HTTP:请求处在哪一层200 · 400 · 401 · 403 · 500Result:业务发生了什么code · message · data按入口区分错误,按 code 区分业务
阅读目录

结论先行

项目约定:成功请求返回 HTTP 200 和 Result.code='0';可预期的业务拒绝返回 400 和原业务错误码;MVC 已知请求错误保留框架状态;未预料到的故障返回 500;认证与授权分别由过滤器返回 401、403。HTTP 状态说明请求在协议层的结果,Result.code 说明具体业务原因,两者不重复。

ResponseEntity<Result<T>> 没有增加一层 JSON:状态在 HTTP 响应行,正文仍是顶层 Result。前端共享 Fetcher 同时检查状态与 code,成功时仍把原样的 Result<T> 交给业务,失败时统一提示并拒绝 Promise。认证过滤器的 API 失败分支现已显式设置 401;授权 403、认证挑战头及应用装配仍需按真实响应核验,不能仅凭共享代码已修改就宣称整条链路完成。

问题背景

过去统一返回 Result 容易让 HTTP 响应始终停在 200:页面能看到业务错误码,浏览器、代理和调用方却无法从状态判断请求已被拒绝。直接把所有异常改成 500 又会混淆格式错误、业务规则拒绝和程序故障。前后端必须对同一条响应采用同一套判断,底层请求封装才能把细节留在内部,不迫使每个业务页面重写错误处理。

Spring 的 ResponseEntity 管状态、响应头和正文;Result 是 JSON 正文,字段仍为 code、key、message、data 等。比如 HTTP 400 的正文可以是 {"code":"name_taken","message":"名称已占用","data":null},前端 response.json() 读到的 code 就在顶层。Spring Framework 的 ResponseEntity 说明也明确区分状态、响应头与正文。

错误可能出现在容器、过滤器、MVC 参数解析、Controller 或业务服务。处在哪一层决定谁能设置状态;是否有 Result 正文决定前端能否展示具体业务原因。本文按当前代码说明已实现的路径,同时指出认证和授权响应仍需核验的部分。

详细内容

先把五类结果说清楚

这套项目协议的状态与正文
HTTP场景响应正文与处理方
200请求成功顶层 Result,code 为 0;Controller 返回,Fetcher 原样交给业务
400可预期业务拒绝、无法接受的输入BusinessException 保留原 Result.code;MVC 解析错误由 Advice 保留 400
401未通过认证认证过滤器设置状态;API 可写 Result,前端触发登录回调
403没有访问权限授权过滤器设置状态;前端提示权限问题
500未知程序或依赖故障Advice 兜底,返回安全的系统错误 Result

这是项目选择的常用状态,不是说其他状态无效。当前 Advice 对框架实现了 ErrorResponse 的异常读取其状态,例如方法不支持时可保留 405。3xx 属于重定向类,304 才是其中与缓存有关的状态;本组 JSON 业务接口无需把 3xx 当业务错误码。项目若要求所有成功 API 都是 200,现存的 201、202 响应还应逐一核对和迁移,不能仅因共享封装接受 2xx 就算完成约定。RFC 9110 的状态码语义是这一层的依据。

Controller 方法调用前失败,也可能进入 ControllerAdvice

请求进入 Spring MVC,不等于 Controller 方法已经执行。无效 JSON 在解析 @RequestBody 时可抛出 HttpMessageNotReadableException;这发生在方法调用前,但 MVC 的异常处理仍可能接住。当前 ControllerReturnAdvice 对实现 ErrorResponse 的异常读取框架状态,对 JSON 不可读、参数类型不匹配等情况给 400,其余未知异常给 500。

若请求在 MVC 之前已被容器拒绝,ControllerAdvice 接不到;认证过滤器提前拒绝也应自行设置状态。API 异常分支由 Advice 写 ResponseEntity,传统 HTML 页面分支仍可能重定向。不能把 HTML 重定向、容器错误页和 JSON API 正文都假定成同一种格式。Spring 的 Controller Advice 说明给出了全局处理的适用范围。

后端 Advice 怎样保留状态,又只输出一层 Result

当前 sparrow-starter 的 ControllerReturnAdvice 对 Ajax/API 请求把 BusinessException 返回为 HTTP 400,正文直接使用 Result.fail(e),原来的业务 code、key 不被状态码替换。通用异常先判断框架给出的状态:4xx 使用安全的非法请求 Result,其他未知异常使用安全的系统错误 Result 并返回 500。它并没有把所有 BusinessException 再细分成一套 HTTP 映射。

code
@ExceptionHandler(BusinessException.class)
public Object business(HttpServletRequest request, BusinessException e) {
    if (isAjax(request)) {
        return ResponseEntity.badRequest().body(Result.fail(e));
    }
    // HTML 页面仍走原有的错误页重定向
}

@ExceptionHandler(Exception.class)
public Object unexpected(HttpServletRequest request, Exception e) {
    HttpStatusCode status = frameworkStatus(e);
    Result<?> result = status.is4xxClientError()
            ? Result.fail(SparrowError.SYSTEM_ILLEGAL_REQUEST)
            : Result.fail(SparrowError.SYSTEM_SERVER_ERROR);
    if (isAjax(request)) return ResponseEntity.status(status).body(result);
    // HTML 页面仍走原有的错误页重定向
}

上面只摘取关键分支。ResponseBodyAdvice 还检查实际正文是否已经是 Result,防止 ResponseEntity<Result<T>> 再被包装成 Result<Result<T>>。因此 HTTP 400 的 JSON 仍是 {"code":"业务码",...},并没有额外的 body 或 result 外层对象。

认证与授权由过滤器明确设置状态

401、403 发生在认证或授权过滤器时,ControllerAdvice 不能替过滤器设置状态。当前 MonolithicBearerFilter.loginFail 的 Ajax/API 分支已经显式设置 HTTP 401,再写出 Result JSON 与内容类型;页面入口仍按原逻辑重定向,不把它改成 API 的 401。前端遇到 401 会触发已有登录回调。

还要核验两件事

授权过滤器是否在实际装配路径设置 403,仍需逐条验证。RFC 9110要求 401 响应包含适用的 WWW-Authenticate 挑战头;当前代码只设置了状态和 JSON,挑战头与现有原始 token 格式如何配合,还需单独设计和验证,不能声称已完全满足该标准。

手动解析 JSON 时,要保住格式错误的边界

若 Controller 使用 @RequestBody String,MVC 只把文本交给方法,后续 JSON 解析由业务入口自己执行。解析失败发生在 Controller 方法内部,不能再指望 MVC 自动识别为 400。现有客服示例将解析失败转换为 SessionException(INVALID_REQUEST);它与普通业务拒绝都需要由该应用自己的接入层明确映射,不能直接假定 sparrow-starter 的 BusinessException 处理器会接住所有 SessionException。

这类入口应继续保持先校验可信会话凭据、再解析正文的顺序,避免未授权请求探测字段细节。具体业务状态与是否适用 400,应由该应用的异常映射和回归测试确认。

前端 Fetcher 怎样闭环,又不改变业务调用

共享的 sparrow-js/common/src/common/lib/Fetcher.ts 为 get、post 共用请求准备逻辑:拼接 API 地址、读取 token、设置请求头和可选 Cookie。fetch 收到 HTTP 400 不会自动把 Promise 判为失败,所以它先尝试读取顶层 Result,再同时判断 HTTP 状态与 Result.code。Fetch Standard把 response.ok 定义为 200–299;项目业务约定的成功仍是 200。

code
const response = await sendRequest('POST', props, props.body);
const result = await parseResult(response); // JSON 正文顶层是 Result
if (!response.ok || !result || result.code !== '0') {
    // 使用 Result.key 翻译业务错误;没有合法 Result 时按 HTTP 状态处理
    throw new FetchError(message, response.status);
}
return result; // 仍返回 Result<T>,不是 result.data

这是流程示意,不是可直接复制的完整实现。HTTP 400 携带合法业务 Result 时,用 key 翻译具体错误并拒绝 Promise;401 触发已有登录回调,403 给出权限提示。遇到空正文、HTML 或无法识别的 JSON 时,封装保留 HTTP 状态,不让 JSON 解析异常掩盖它。只有 HTTP 成功且 code='0' 才原样返回 Result<T>;上层继续读取 result.data,失败仍走原有 Promise 错误路径。

response.ok 为真而正文无有效 Result,不是正常业务分支,而是协议被破坏的兜底情形。下载接口另按文件与 JSON 错误正文分流,不能把 HTML 错误页或 JSON 错误保存成 zip;下载成功继续返回文件对象,并不假装返回 Result<T>。

国际化配置与前后端同步验收

业务错误优先用后端 Result.key 和参数交给页面传入的 translator;没有标准 Result 的 HTTP 错误则用 user_not_login、http_forbidden、http_bad_request、system_server_error、http_invalid_response 等键。对应中英文文案已配入相关站点和页面命名空间,不在 Fetcher 里硬编码两套语言。缺少 translator 或键时,封装只显示 HTTP 401 等状态信息;这也提醒新页面接入时必须提供可用的翻译配置。

同步改造时的检查点
位置应验证的结果
Advice业务拒绝 400 且保留原 code;MVC 解析错误 400;未知异常 500;Result 不重复包装
过滤器认证实际发出 401、授权实际发出 403;API 错误正文与响应头匹配
Fetcher400 可读业务 Result;401 登录回调;403 权限提示;空正文与 HTML 保留状态
业务页面成功仍收到 Result<T>,读取 result.data 的代码无需改动;翻译键可解析

当前后端 Advice 的 MockMvc 测试已覆盖 400、500、成功正文只包装一次;前端定向测试已覆盖成功、业务 400、401/403、非 JSON 错误和下载错误。认证过滤器 API 分支已写入 401 且模块编译通过;过滤器真实响应、挑战头、授权 403、应用装配与端到端联测仍需单独核验。共享库代码通过测试不等于所有部署实例已切换到新协议。

总结归纳

这套约定自洽的关键是两层判断各有职责:HTTP 状态表达请求成功、被拒绝或服务故障,Result.code 表达更细的业务原因;ResponseEntity 不改变 JSON 形状,Fetcher 也不改变成功返回给上层的 Result<T>。全局 Advice、过滤器、前端封装与翻译配置都要按同一规则运行。当前 Advice、Fetcher 和认证过滤器的 API 401 状态已更新;授权过滤器的 403、认证挑战头以及应用层整体联测仍以实际响应验证为准。

参考资料

  1. RFC 9110:HTTP 状态码语义

    核对 2xx、3xx、4xx、5xx 和 400/401/403/500 的含义,以及 401 的挑战头要求。

  2. Spring Framework:Controller Advice

    核对全局异常处理的作用范围。

  3. Spring Framework:异常处理方法

    核对 MVC 异常如何交给 ExceptionHandler。

  4. Spring Framework:ResponseEntity

    核对状态、响应头与正文的职责。

  5. Fetch Standard:Response.ok

    核对 fetch 对 2xx 状态的判断;业务 code 是项目自身的第二层约定。