路由级数据加载:把请求瀑布流拆成一片湖
学完能验收的四条
- 能画出三层嵌套路由下
onMounted取数的时序图,并指出哪一段等待是被组件挂载顺序强制的 - 能判断一个页面该不该迁到 Data Loader,说得出"迁了不会变快"的三种情形
- 会给 loader 补上取消、预期错误、鉴权三处处理,不依赖默认行为
- 能在四种取数方案之间做出选择,并解释为什么选了其中一种
版本前提先说清楚,因为这一块的坑多半出在版本上:Vue Router 5.0.0 于 2026-01-29 发布,截至 2026 年 11 月 16 日最新是 5.5.1(2026-11-13 发布),4.x 线仍在维护(4.6.5)。Data Loaders 到本文写作时依然从 vue-router/experimental 导入,官方把它放在实验性子路径下,说明 API 还有调整空间。API 细节以官方 Data Loaders 指南 与 experimental 子路径的导出说明 为准,本文写作后如有变动,以文档为准。这意味着可以在内部中后台先跑,但要有"接口改名了要跟着改"的心理准备,别在对外承诺了交付期的项目上豪赌。
1. 这一节在整个类目里的位置
路由这一层有三个职责,很多团队把它们混在一起写,最后谁也说不清一个页面为什么慢。分开看就清楚了:导航守卫管"能不能去",Data Loader 管"去之前要准备什么数据",组件管"数据到了怎么画"。
先记住一句话:本篇所有内容都在回答同一个问题——页面从"自己取数"变成"路由取数",哪些问题消失了,哪些问题换了一种形式冒出来。
2. 导入案例:一次点击之后的两秒空白
2026 年 9 月,一个做设备巡检的系统找到我们。订单详情页 /orders/42 点进去要等 2.1 秒才出现内容,用户反馈"点了没反应"。
打开代码,结构是这样的:父路由组件 OrderLayout 在 onMounted 里请求订单主表,拿到 customerId 之后才渲染子路由 CustomerCard,而 CustomerCard 在自己的 onMounted 里请求客户信息。再往下还有一层 ContractList,依赖客户 ID。
三段请求,每段都要等上一段的组件挂载完成。后端每个接口的 RT 都在 300ms 到 500ms 之间,单看哪个接口都不算慢。
问题不在接口,在它们被强制排了队。你可能会想:"那把三个请求都塞进父组件不就行了?"这确实能解决串行,但代价是父组件要提前知道所有子路由需要什么数据——这条耦合会在第三次加子页面时反噬你。
3. 三个概念,三种反例
3.1 瀑布流:串行,而不是慢
瀑布流的成因是依赖关系被组件的挂载顺序表达了出来。组件必须先存在,才能在 setup 或 onMounted 里发请求;子组件又必须等父组件渲染出来。这条链条是 Vue 的渲染模型决定的,不是谁写错了。
反例:以为"把请求挪到 onBeforeMount 就能并行"。挪了之后请求确实早了几十毫秒发出,但它依然在组件树上,父子依赖没变,水管还是那根水管。
3.2 loader:一个挂在路由上的纯取数函数
loader 的定义方式是"在页面组件里定义并具名导出"。导出这一步是硬要求,路由靠 export 出来的东西才能收集到它;不导出,它就退化成普通 composable,导航阶段不会等它。
<!-- src/pages/orders/[id].vue -->
<script lang="ts">
// 前提:vue-router@5.5.1;loader 在 setup 之外定义,不能有响应式副作用
import { defineBasicLoader } from 'vue-router/experimental'
import { fetchOrder } from '@/api/orders'
export const useOrder = defineBasicLoader('/orders/[id]', async (to, { signal }) => {
return await fetchOrder(String(to.params.id), { signal })
})
</script>
<script setup lang="ts">
const { data: order, isLoading, error, reload } = useOrder()
</script>
<template>
<div v-if="isLoading">加载中…</div>
<div v-else-if="error">
<p>{{ error.message }}</p>
<button @click="reload()">重试</button>
</div>
<OrderDetail v-else-if="order" :order="order" />
</template>反例:在 loader 里写 ref() 或 watch()。loader 是纯取数函数,入参只有目标路由和上下文,它的返回值会被路由打包提交,响应式对象在这里没有意义,只会让"数据什么时候生效"变得不可预测。
3.3 pack:一次导航的原子提交
这是 Data Loader 相对"在守卫里手动 await"最实质的优势,也是最容易被略过的一条。
一次导航中收集到的所有 loader 被视为一个 pack。只要有一个失败或导航被取消,任何结果都不会被采用;只有全部成功,数据才一次性提交。所以你永远不会看到"头部是新的、列表还是旧的"这种中间态。
反例:以为把慢接口拆成 lazy loader 能改善首屏。不能。lazy loader 很快返回,它的数据也要等整批就绪才更新,它只减少导航阻塞时间,不改善首屏。
4. 动手任务:把三段串行改成一次并行
任务目标:把案例里的三层路由改成路由级取数,并验证耗时变化。
第一步,装插件。顺序不能反——DataLoaderPlugin 必须在 router 之前注册,因为初始导航由 app.use(router) 触发:
// src/main.ts
// 前提:vue-router@5.5.1,Data Loaders 仍在 experimental 子路径
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental'
import { routes } from './routes'
import App from './App.vue'
const router = createRouter({ history: createWebHistory(), routes })
const app = createApp(App)
app.use(DataLoaderPlugin, { router }) // ← 必须在 router 之前
app.use(router)
app.mount('#app')预期输出:无报错,页面照常渲染。如果顺序写反,你会看到初始导航没有等待任何 loader——不报错,只是第一个页面直接闪出空状态。这个错误的表现是"看起来生效了一半",最难查。
第二步,在子页面里导出 loader,把 customerId 依赖消掉:
<!-- src/pages/orders/[id]/customer.vue -->
<script lang="ts">
import { defineBasicLoader } from 'vue-router/experimental'
import { fetchCustomer } from '@/api/customer'
// 用同一个路由模式注册,两个 loader 之间没有数据依赖 → 并行执行
export const useCustomer = defineBasicLoader('/orders/[id]', async (to) => {
return await fetchCustomer(String(to.params.id))
})
</script>预期输出:Network 面板里订单和客户两个请求几乎同时发出,首屏从 2.1 秒降到约 0.9 秒(单个接口 RT 的上下界)。
这里容易卡住:defineBasicLoader 的第一个参数可以传路由模式也可以省略,两种写法官方文档里都存在。带路径会把路由显式写出来,可读性好,接类型化路由时也更省事;运行时语义没有区别。一个仓库里选一种,别混用——混用之后你没法 grep 出某个页面到底有几个 loader。
第三步,验证行为。从 /orders/41 跳到 /orders/42 时,导航会被推迟到数据返回之后才提交。用户点击后页面会"停"在原地一小会儿。
这不是 bug,是这套模型的固有代价。要缓解就配全局进度条,或者对非关键区域改用 lazy loader。
5. 三处必须显式写,默认行为会教你做人
取消。上下文对象带 AbortSignal。导航被新导航取代或取消时信号 abort,把它传给 fetch 才能真正中断请求。不传的话旧请求会跑完,虽然这批数据不会被采用,但服务端压力是实打实的。
错误。默认所有抛出的错误都算意外错误,会中止导航并交给 router.onError(),页面根本渲染不出来,你也就看不到 error。希望页面本地展示错误,必须显式声明预期错误类型。
权限。不要用 loader 做鉴权。loader 是数据层,鉴权属于导航守卫,职责分开才不会互相等待。
// src/pages/admin/dashboard.vue 的 loader 部分
// 前提:vue-router@5.5.1
import { defineBasicLoader, reroute } from 'vue-router/experimental'
class ApiError extends Error {
override name = 'ApiError'
constructor(message: string, public status: number) { super(message) }
}
export const useDashboard = defineBasicLoader(
'/admin',
async (to, { signal }) => {
// inject / store 必须在第一个 await 之前调用
const res = await fetch('/api/admin/stats', { signal })
if (res.status === 401) reroute('/login') // 内部抛异常,后面不会执行
if (!res.ok) throw new ApiError('统计接口失败', res.status)
return res.json()
},
{ errors: [ApiError] }, // 声明为预期错误:不中止导航,落进 error
)reroute() 的语义值得单独记:它内部抛异常,调用后不需要 return,也不接受 true 或 undefined,因为那不改变导航;传 false 取消本次导航,传路径或 location 对象表示重定向。
还有一条设计约束:lazy loader 不能用 reroute()。它不阻塞导航,导航早就提交了,此时改目标毫无意义。
6. 四种取数方案的取舍
选型时最容易被忽略的其实是"导航该不该等数据"。等,首屏更完整但点击有延迟;不等,点击立刻响应但会闪一下空状态。
| 方案 | 并行 | 可取消 | 缓存 | 阻塞导航 | 适用 |
|---|---|---|---|---|---|
onMounted 内请求 | ❌ 依赖挂载顺序 | 需手写 | 需自建 | ❌ | 弹窗、局部刷新 |
beforeEach 里 await | 需手写 Promise.all | 需手写 | 需自建 | ✅ | 强依赖数据的鉴权跳转 |
| Basic Loader | ✅ 自动 | ✅ 内置 signal | ❌ 每次导航重取 | ✅ | 数据实时性优先的详情页 |
| Colada Loader | ✅ 自动 | 建议不取消 | ✅ staleTime + 去重 | ✅ | 列表、可回退的浏览型页面 |
最后一行有个反直觉的点:用 Colada Loader 时官方建议不要取消请求。它的价值来自缓存复用,中断请求等于放弃"用户返回上一页时秒开"的收益。取消策略和缓存策略必须一起决策,分开拍必然返工。
明确一条我不建议的做法:不建议在 beforeEach 里 await 取数,除非那是鉴权跳转。守卫里取数会阻塞每一次导航,包括你只是想改个 query 的场景;而且守卫拿不到 pack 的原子性,失败时页面状态是半新半旧的。
7. 三个常见误解
很多人以为 Data Loader 是 <Suspense> 的替代品,实际上两者解决的不是同一层问题:Suspense 等的是组件内部的异步 setup,取数仍写在组件里、仍受挂载顺序影响;Data Loader 等的是路由级的数据准备,取数发生在组件存在之前。已经在用 Suspense 的项目迁过来,收益来自并行化与缓存解耦,不是少写几个 await。
很多人以为 loader 之间会自动做依赖分析,实际上不会。把 customerId 拆成两个 loader 依然是两次往返,正确做法是在第一个 loader 里一次取回,或者让后端出聚合接口。
很多人以为客户端跑通就等于 SSR 跑通,实际上差得远。服务端渲染有两个只在真机上暴露的约束:一是超时,客户端卡住用户还能刷新,服务端卡住会一直挂到网关超时,所以 loader 里的下游请求必须设超时,超时后抛预期错误、退化成骨架屏直出;二是状态隔离,服务端进程是复用的,任何写进模块级变量的结果都会在请求之间泄漏,取数结果只能存在请求上下文里。这两点在 vite dev 下完全不会暴露。
8. 想一想,然后动手
第一题。你的详情页有四个 loader,其中一个依赖最快的那个接口的返回值才能发。把依赖的那个改成 lazy loader,首屏会变快吗?为什么?
第二题。reload() 抛出的错误会走 errors 过滤吗?如果不会,你的重试逻辑应该写在哪一层?
第三题。给一个已经用 beforeEach 做鉴权的中后台加 Data Loader,你要怎么用测试把"守卫先于 loader"这个顺序固定下来?直觉在这里不可靠。
9. 中英名词对照
| 中文 | 英文 | 一句话解释 |
|---|---|---|
| 数据加载器 | Data Loader | 定义在页面组件上、由路由在导航阶段收集执行的取数函数 |
| 打包提交 | pack | 一次导航内所有 loader 结果作为一个原子单元生效或全部丢弃 |
| 预期错误 | expected error | 显式声明后不中止导航、交由页面渲染错误态的错误类型 |
| 重定向 | reroute | 在 loader 内改变导航目标,内部以抛异常实现 |
| 导航阻塞 | blocking navigation | 导航提交被推迟到数据就绪之后 |
| 延迟加载器 | lazy loader | 不阻塞导航、数据就绪后单独更新的 loader |
| 取数瀑布流 | request waterfall | 因组件挂载顺序被强制串行的多次请求 |