async/await 不感知 API 版本错误，需通过语义判断和主动检查识别；网络失败可被 try/catch 捕获，HTTP 状态异常需手动检查 response.ok，业务版本错误须解析 JSON 后判断字段。
async/await 本身不感知 API 版本错误——它只响应 Promise 的状态（fulfilled 或 rejected）。所谓“版本错误”，比如请求 /v1/users 却收到 404 Not Found 或 410 Gone，又或后端返回 {"error": "API version v1 is deprecated"}，这类问题需靠**语义判断 + 主动检查**来识别和处理，不能依赖 try/catch 自动捕获。
明确区分网络失败、HTTP 状态异常与业务版本错误
三者性质不同，处理方式也不同：
- 网络失败（如 DNS 失败、连接超时）：fetch 默认 reject，可被 try/catch 捕获
-
HTTP 状态异常（如 404、500）：fetch 不 reject，必须手动检查
response.ok或response.status -
业务版本错误（如返回
{ code: 426, message: "Upgrade Required", version: "v2" }）：属于成功响应体内的语义错误，需解析 JSON 后判断字段
在 fetch 封装层统一拦截版本相关响应
避免每个接口调用都重复写判断逻辑。推荐在基础请求函数中集中处理：
async function api<T>(url: string, options: RequestInit = {}): Promise<T> {
const res = await fetch(url, options);
// 步骤1：网络正常但 HTTP 状态异常
if (!res.ok) {
if ([404, 410, 426].includes(res.status)) {
throw new ApiVersionError(`API version mismatch: ${res.status} ${res.statusText}`, {
status: res.status,
url
});
}
throw new Error(`HTTP error: ${res.status}`);
}
// 步骤2：解析 JSON
const data = await res.json();
// 步骤3：检查业务级版本错误码（按团队约定）
if (typeof data === 'object' && data?.code === 426) {
throw new ApiVersionError(data.message || 'API version deprecated', {
code: data.code,
requiredVersion: data.version,
currentUrl: url
});
}
return data;
}
再配合自定义错误类：
class ApiVersionError extends Error {
constructor(message: string, public details: Record<string, any>) {
super(message);
this.name = 'ApiVersionError';
}
}
调用时分场景响应，不一刀切
根据错误类型提供不同用户反馈和降级策略：
- 遇到
ApiVersionError：提示“系统正在升级，请稍后重试”或自动跳转新版入口 - 若已知旧版即将下线，可在请求头加
X-Expected-Version: v2，后端据此返回更明确提示 - 对非关键接口（如推荐位），捕获
ApiVersionError后静默 fallback 到本地默认数据，不中断主流程 - 全局监听未捕获的
ApiVersionError，上报监控平台，辅助识别漏处理的版本迁移点
配合自动化手段提前发现
仅靠运行时处理不够，还需预防：
- CI 流程中扫描所有
fetch('/v1/...')字面量，提醒替换为配置驱动的api.endpoint('users') - Swagger/OpenAPI 文档变更时，触发比对脚本，检测是否存在已标记
deprecated: true的路径仍在前端调用 - 灰度发布期，在响应头注入
X-API-Deprecated: "v1 will be removed on 2026-08-01"，前端控制台打印 warn 并记录日志
