后台有三个页面都要展示同一个客户的订单:列表、客户详情卡片、运营首页待办。每个页面都在组件里直接发请求,各自维护 loading、error、list。上线后问题一个个冒出来:打开运营首页,三个组件同时挂载,同一个接口在同一秒发了三次;从订单详情返回列表,列表从头再拉一遍,筛选条件和滚动位置都丢了;搜索框每敲一个字发一次请求,输入「张三丰」的时候,「张」的响应最后才到,把「张三丰」的结果盖掉,页面显示的是姓张的所有人的单子。
修的时候才发现更麻烦。三份代码的重试逻辑不一样:一份失败就白屏,一份把错误吞掉只留空列表,第三份弹 alert。鉴权头有的加了有的没加,取消请求只有一个页面做了。产品问「能不能加个下拉刷新」,开发估了一下说要改三个页面。
这篇讲请求层怎么设计。不推荐某个库,而是把「组件该关心什么、client 该管什么、缓存 key 怎么定、什么时候失效、重复请求和竞态怎么处理、错误怎么分类、重试该不该做」串成一条线。React 示例按 React 18 写,Vue 示例按 Vue 3 写;库的版本行为拿不准就标「待确认」。
每个组件自己写请求,问题不在代码长短
单看一个组件的请求代码,十几行,没什么问题。问题出在它被复制到第十个组件之后。真正让维护变难的,是下面这几件事同时发生。
- 重复代码只是表面。更麻烦的是状态处理不一致:有的页面失败后保留旧数据,有的清空列表,有的连错误都不展示。用户看到的行为取决于他打开的是哪个页面。
- 竞态。同一个搜索框,先发的请求后到,后发的请求先到,最终显示什么全靠网络运气。组件里如果没有「这次响应还算不算数」的判断,UI 就会回退到旧结果。
- 重复请求。三个组件挂载时各发一次,接口没有做幂等,后端日志里同一秒三条一样的查询,数据库压力白背。
- 取消、重试、缓存各写一套。有人用 axios 拦截器,有人用 fetch 包一层,有人干脆在 catch 里写 setTimeout 重试,规则散在项目各处。
有人会说,抽一个 useRequest 的自定义 hook 不就好了。能解决一部分,但只到「单页复用」这一层。跨页面共享缓存、写操作后让相关列表失效、同一条请求同时只发一次,这些都不是一个 hook 能覆盖的,需要一个独立的请求层。
请求层是为了让页面少写代码:页面只描述要什么数据,不管怎么拿、失败了怎么办、拿过之后怎么存。
请求层分三层,组件只消费结果
把它分成三层,每层只做一件事。分层的好处不是好看,而是出问题时能快速定位在哪一层。
三层的边界要写进团队约定:业务请求函数不写弹窗,client 不写业务判断,页面不写状态码。破一次例,后面就会跟着破。
client 的边界:鉴权、超时、错误归一化
client 只做四件事:拼 baseURL、加鉴权头、控制超时、把各种失败归一化成同一种形状。它不决定要不要重试,也不决定给用户看什么文案,那些属于上层。
// src/api/client.js:只负责发请求、超时、鉴权头和错误归一化
const BASE_URL = "/api";
function fail(kind, message, extra) {
return { kind, message, ...extra };
}
export async function request(path, { params, timeout = 8000, headers: extraHeaders, ...init } = {}) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeout);
const clean = Object.fromEntries(
Object.entries(params || {}).filter(([, value]) => value !== undefined && value !== "")
);
const query = Object.keys(clean).length ? "?" + new URLSearchParams(clean).toString() : "";
const headers = { "Content-Type": "application/json", ...extraHeaders };
const token = localStorage.getItem("token");
if (token) headers.Authorization = "Bearer " + token;
try {
const response = await fetch(BASE_URL + path + query, {
...init,
headers,
signal: controller.signal,
});
if (response.status === 401) throw fail("auth", "登录状态已失效", { status: 401 });
if (!response.ok) throw fail("http", "请求失败", { status: response.status });
const body = await response.json();
if (body.code !== 0) throw fail("business", body.message, { code: body.code });
return body.data;
} catch (error) {
if (error.name === "AbortError") throw fail("abort", "请求已取消");
if (error.kind) throw error;
throw fail("network", "网络异常,请稍后重试");
} finally {
clearTimeout(timer);
}
}
这段代码在浏览器里能跑,前提是同源下有 /api 这个后端。参数要先过滤空值,否则 undefined 会变成字符串 "undefined" 拼进 URL。401 只归一化,不在这里跳登录,因为不同页面可能有不同的登录入口。超时用 AbortController 实现,fetch 本身没有超时选项,细节见浏览器 API。
归一化后的错误至少要有 kind、message,可选 status、code。上层只认这几个字段,不直接读 response。这样以后换请求库、加网关、改错误码,页面代码不用动。
业务请求层很薄,一个接口一个函数。不要在页面里拼字符串,也不要在组件里写 fetch("/api/orders")。函数名就是接口清单,改接口时搜函数名,比搜 URL 靠谱。
// src/api/orders.js:一个接口一个函数
import { request } from "./client";
export function getOrders({ customerId, keyword, page = 1, pageSize = 20, signal } = {}) {
return request("/orders", {
params: { customerId, keyword, page, pageSize },
signal,
});
}
export function createOrder(payload) {
return request("/orders", {
method: "POST",
body: JSON.stringify(payload),
});
}
页面消费层的写法要统一成「只认三个东西」:数据、状态、错误。React 里可以是一个返回 { data, status, error, refresh } 的 hook,Vue 里可以是一个返回同样字段的 composable。状态用有限的几个值,不要用多个布尔量拼:idle、loading、success、error。布尔量多了会出现「loading 为 true 同时 error 也有值」这种没人处理的状态。
缓存 key 与失效:缓存最容易错的地方
缓存最难的不是存,而是 key 和失效。key 漏了参数,两个筛选条件的列表互相污染;key 没带租户或用户,切换组织后看到上一个组织的数据;key 用了整个对象序列化,字段顺序一变就命中不了。实际项目里,这三类问题都比「缓存没做」更常见。
key 的设计可以按「资源 + 参数 + 身份」来拼:资源名用固定前缀,参数按键名排序,身份至少带租户或用户的作用域。分页参数必须进 key,否则第一页和第二页会互相覆盖。
function buildKey(resource, params = {}, scope = {}) {
const merged = { ...params, tenantId: scope.tenantId, userId: scope.userId };
const parts = Object.keys(merged)
.filter((key) => merged[key] !== undefined && merged[key] !== "")
.sort()
.map((key) => key + "=" + String(merged[key]));
return resource + "?" + parts.join("&");
}
console.log(buildKey("orders", { page: 2, keyword: "张三" }, { tenantId: "t-01" }));
// orders?keyword=张三&page=2&tenantId=t-01
前缀要有层级,方便批量失效。比如列表统一用 orders?,详情用 order:123,字典用 dict:status。写操作之后按前缀清理,不要把每个页面里的列表变量挨个手动改一遍。手动改漏一个,就是「新建成功但列表不刷新」的经典 bug。
什么时候该复用,什么时候必须重新拉
判断可以问三个问题。这份数据会不会在几分钟内被别人改?用户能不能接受看到旧值?重新拉一次的代价有多大?三个答案组合起来,基本就能决定缓存多久、要不要在窗口获得焦点时重取。
适合复用的:字典、状态枚举、权限码、列表首屏、详情页的静态部分。这些数据变化慢,用户也不指望它是实时值。不适合复用的:支付前的金额、库存、审批状态、验证码、提交前的余额。这些数据错一次就是事故,宁可每次重新拉,也不要用缓存换那一点性能。
焦点重取和轮询要看场景。后台系统里用户经常切到别的标签页再回来,窗口获得焦点时重取一次列表,是成本很低的保鲜方式。轮询适合看板、排队状态这种会自己变的页面,间隔不要太短,页面不可见时要停掉。
分页和搜索有两个细节。翻页时保留上一页数据,不要先清空再加载;搜索时把确认过的关键词放进 key,避免留下半截词的缓存。无限滚动的缓存要设上限,翻到第五十页还全留着,内存迟早出问题。
重复请求与竞态:三件事要分开处理
重复请求和竞态常被当成一件事,其实是三件:同一 key 短时间多次发起,要去重并共享 Promise;旧请求结果回来得晚,要取消或丢弃;组件卸载后请求才回来,要中止。
去重可以在 client 外面包一层,按「方法 + 路径 + 参数」做 key。只对读请求去重,写请求不能合并,两个「创建订单」合并成一个,用户会少一单。
const inflight = new Map();
export function requestOnce(key, task) {
if (inflight.has(key)) return inflight.get(key);
const promise = task().finally(() => inflight.delete(key));
inflight.set(key, promise);
return promise;
}
取消用 AbortController。把 signal 从页面一路传到 fetch,组件卸载、搜索词变化、切换客户时调用 abort。被取消的请求会以 AbortError 结束,要单独识别,不能当成网络错误弹提示,否则用户每敲一个字都能看到一条「网络异常」。Promise 的错误传播见异步编程。
但只靠取消还不够。响应已经拿到、正在解析时,abort 拦不住,所以再加一个序号,只有最新一次允许写状态。取消省带宽,序号保证 UI 不被旧结果污染。
// React 18:搜索框的防抖、取消和序号校验
function useOrderSearch() {
const [keyword, setKeyword] = useState("");
const [result, setResult] = useState({ status: "idle", data: [], error: null });
const seqRef = useRef(0);
const controllerRef = useRef(null);
useEffect(() => {
if (!keyword.trim()) {
setResult({ status: "idle", data: [], error: null });
return;
}
const seq = ++seqRef.current;
const timer = setTimeout(async () => {
controllerRef.current?.abort();
const controller = new AbortController();
controllerRef.current = controller;
setResult((prev) => ({ ...prev, status: "loading" }));
try {
const data = await getOrders({ keyword, signal: controller.signal });
if (seq !== seqRef.current) return;
setResult({ status: "success", data, error: null });
} catch (error) {
if (error.kind === "abort") return;
if (seq !== seqRef.current) return;
setResult({ status: "error", data: [], error });
}
}, 300);
return () => {
clearTimeout(timer);
controllerRef.current?.abort();
};
}, [keyword]);
return { keyword, setKeyword, result };
}
这段代码在 Vite 创建的 React 18 项目里能直接跑,前提是 getOrders 接受 signal 并传给 fetch。清理时同时清定时器并 abort,已经发出去的请求也会被取消。
请求库:把能力和代价一起算
React 生态里常见的是 TanStack Query 和 SWR,Vue 生态里对应的是 Vue Query,或者用 Pinia 管理状态、自己写一层组合式函数。它们解决的核心问题和上面说的一样:按 key 缓存、请求去重、后台刷新、写操作后失效、重试、无限滚动。区别在于这些能力是现成的,还是你自己拼。
先说能力。用请求库之后,页面通常不用再手写 loading 和 error,缓存共享、失效、重试都有现成开关;开发者工具能看到每个 key 的状态,排查「为什么显示旧数据」会快很多。分页、无限滚动、乐观更新这些也有现成模式,不用每次重新设计。
再说代价。团队要理解缓存生命周期,否则「数据改了页面还是旧的」更难查;抽象会泄漏,配置越加越多;包体积、升级和测试成本都要算进去。
手写请求层
代码量可控,行为完全看得懂,适合页面不多、接口简单、团队对缓存没有复杂要求的项目。代价是去重、失效、重试都要自己实现,边界情况容易漏。
用请求库
能力齐全,约定统一,适合页面多、接口互相关联、需要共享缓存的项目。代价是学习曲线、抽象复杂度和升级成本,团队不熟时反而增加排查难度。
两层也可以并存:client 继续负责鉴权、超时和错误归一化,请求库只负责缓存和调度,换库时业务函数不用动。页面只有三五个、接口一只手数得过来,手写一层 hook 加内存缓存就够了;页面十几个以上、同一数据多处出现,再用库。
库的版本差异要留意。TanStack Query 从 v4 到 v5 有选项改名,SWR 2.x 和 1.x 行为不完全一样,Vue Query 与 Vue 3 小版本的兼容范围也要核对。落代码前以所装版本文档为准,拿不准就标「待确认」。
错误分类与重试:别把所有失败当成一种
「请求失败」这四个字背后至少有五种情况,处理方式完全不同。全都弹「系统异常,请稍后重试」,用户不知道该重试还是该改输入,客服也拿不到有效信息。
| 错误类型 | 典型表现 | 上层该怎么做 |
|---|---|---|
| 网络失败 | 断网、DNS 失败、跨域被拦,fetch 直接 reject | 提示检查网络,保留重试按钮,不要自动狂重试 |
| 超时 | 请求发出后长时间没有响应,被 AbortController 中止 | 提示稍后重试,只对读请求自动重试;写请求先确认服务端是否已处理 |
| HTTP 401 | 登录过期或 token 失效 | 跳登录或刷新 token,不重试原请求 |
| HTTP 403 | 没有权限 | 提示无权限,不要引导用户反复重试 |
| HTTP 422 或 400 | 参数校验没过,字段级错误 | 把错误映射到具体字段,让用户改输入 |
| HTTP 5xx | 服务端异常、网关错误 | 提示服务暂时不可用,读请求可有限重试并上报 |
| HTTP 200 但业务码失败 | 接口成功返回,code 非 0,message 是业务原因 | 按业务错误展示 message,不要当成网络问题 |
重试有一个硬前提:请求必须是幂等的。GET、HEAD、以及设计上幂等的 PUT 可以重试;创建订单、支付、发验证码、发消息这类 POST,没有服务端幂等键就不要自动重试。网络超时的时候,服务端可能已经处理成功,客户端再发一次就是两单。
重试策略本身也要克制。次数两到三次足够,间隔按指数退避加一点随机抖动,避免所有客户端在同一秒重试把服务打垮。4xx 基本不重试,408 和 429 可以例外。重试过程中 UI 要显示「正在重试」,不要静默进行,否则用户会以为页面卡死。
完整场景:客户详情订单卡片从三处请求到一层
需求来自产品:客户详情页要显示该客户最近订单,支持手动刷新;切换客户时不能串数据;订单列表的搜索要跟手;新建订单后,详情页的卡片要立刻更新。第一版是复制来的,长这样。
// 第一版:组件自己 fetch,问题都埋在这几行里
function CustomerOrders({ customerId }) {
const [list, setList] = useState([]);
const [loading, setLoading] = useState(false);
useEffect(() => {
setLoading(true);
fetch("/api/orders?customerId=" + customerId)
.then((res) => res.json())
.then((body) => {
setList(body.data);
setLoading(false);
});
}, [customerId]);
return loading ? <p>加载中…</p> : <List data={list} />;
}
这段代码上线后出了四个问题。没有错误分支,接口 500 时 loading 永远是 true,页面一直转圈。没有取消,快速切换客户时,上一个客户的响应后到,卡片显示的是别人的订单。没有缓存,列表页、首页、详情页同时挂载就发三次。没有失效,新建订单成功后卡片还是旧数据,用户以为没保存上。
第二版把请求收进业务函数和 hook,key 带上客户和租户,页面只消费状态。新建订单成功后按前缀失效,不逐个页面通知。
// 第二版:页面只消费 data、status、error
function CustomerOrders({ customerId }) {
const { data, status, error, refresh } = useOrders({ customerId });
if (status === "loading" && !data) return <p>加载中…</p>;
if (status === "error") return <ErrorBox error={error} onRetry={refresh} />;
return <OrderList data={data} onRefresh={refresh} />;
}
// 新建订单后,按前缀让相关缓存失效
async function submitOrder(payload) {
const created = await createOrder(payload);
invalidate("orders?");
invalidate("order:" + created.id);
return created;
}
Vue 3 项目里,切换客户时的取消可以放在 watch 的清理函数里。这样列表页和详情页用的是同一套请求函数,只是消费方式不同。
// Vue 3:切换客户时取消上一次请求
watch(
() => props.customerId,
(id, oldId, onCleanup) => {
const controller = new AbortController();
onCleanup(() => controller.abort());
loadOrders(id, controller.signal);
},
{ immediate: true }
);
上线后又遇到下面这些反馈。表格里的第一条和第二条最容易被误判成后端问题,实际都在前端请求层。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 打开首页,同一接口一次加载发三次 | 三个组件各自请求,没有共享缓存和去重 | Network 面板按 URL 过滤,数同一时刻的请求数 |
| 快速切换客户,卡片显示上一个客户的订单 | 旧请求没取消,返回晚于新请求 | 在回调里打印当前 customerId 和响应里的 customerId |
| 搜索「张三丰」却显示「张」的结果 | 响应乱序,没有序号校验 | 打印每次响应的关键词和序号,看最终写入的是哪一次 |
| 从详情返回列表,筛选条件丢了 | 筛选状态只存在组件里,组件重建后归零 | 看筛选条件是组件 state,还是放在路由或全局状态里 |
| 新建订单成功,列表和卡片都没变 | 写操作后没有失效相关缓存 | 搜 createOrder 调用点后面有没有 invalidate |
| 断网时页面一直转圈 | 没有错误分支,或 catch 里没有写 error 状态 | 断网复现,看 catch 是否只打了日志 |
表格里第二条值得多说一句。加 abort 不等于旧请求一定不写状态:如果响应已经拿到、正在解析,取消拦不住。序号校验就是给这一段兜底。
边界与代价:什么规模该上这一层
请求层和组件库一样,是资产也是负债。规模不到,抽出来反而绕;规模过了,不抽会更痛。团队里没人讲得清缓存生命周期时,宁可不引入。
- 只有两三个页面、五个以内接口、数据不跨页面共享时,一个 client 加一个简单 hook 就够,再加缓存框架,收益抵不过成本。
- 缓存 key 多到需要一张表来维护、失效关系画成图还理不清,说明缓存粒度太细。优先合并 key,按页面或资源粗粒度缓存,而不是继续加规则。
- 强一致的数据不要缓存。余额、库存、审批状态、支付结果,每次重新拉,或者由服务端推送。省下的那点请求时间换不来一次事故。
- 请求层会成为全站单点。client 改一个错误归一化规则,所有页面的错误提示都可能变,要有回归清单和测试,不能随手改。
- 内存缓存要有上限和清理策略。路由切换、退出登录、切换租户时清空,避免把上一个用户的数据留给下一个用户,这既是性能问题也是安全问题。
- 服务端渲染要小心:进程级缓存不能跨用户复用,否则 A 的数据会出现在 B 的页面上。
一句话的判断:请求层解决的是「同一份数据被多个页面反复消费」的问题。如果数据只在一个页面用一次,直接请求反而更清楚。
今天就能验证的练习,和小结
- 在现有项目里搜
fetch(和axios,统计同一个接口在多少个文件里出现。超过三个,就把它列进请求层改造清单。 - 打开一个列表页,在 Network 面板里按接口名过滤,记录一次加载发了几条同样的请求;再快速输入搜索词,看响应顺序和页面最终显示是否一致。
- 手写一个
buildKey,故意不带 tenantId,切换组织后打开同一个列表,看是否出现上一个组织的数据。 - 找一个提交按钮,连点两次,看后端是否生成两条记录;再给按钮加
submitting状态,确认第二次点击被拦住。 - 用 AbortController 取消一个故意延迟的请求,确认控制台里是
AbortError,而不是被当成网络错误弹了提示。
数据请求看起来是「调个接口」,真正难的是同一份数据被多个页面用的时候,谁负责缓存、谁负责失效、谁负责处理失败。把这三件事从组件里拿出来,页面才会变得可预测。
数据层稳定之后,页面还需要另一类交互:用户输入。表单里的值和校验,比请求状态更容易失控:三十个字段各管各的 state,同一条规则写在三个地方,提交失败还留不住用户填的内容。下一篇讲表单与校验,从受控与非受控的真实差别开始。