网络与数据:请求封装、缓存与状态管理
本篇要点:把请求收进一层可替换的封装,说清三端凭证的传递差别,让 Pinia 与本地缓存各管一段而不是互相顶替。 前置:《界面开发:组件、布局与多端适配》把界面做出来了,这一章给它接上数据;Vue 3 的响应式与组合式写法要熟,Pinia 是这一章新引入的工具。
为什么需要它
一个会员项目上线第一周,同一个 401 演了三种样子。H5 上一切正常,浏览器把 cookie 带上了,后端认得;微信小程序里所有接口返回 401,因为小程序不发 cookie,Set-Cookie 也存不住;App 上时好时坏,冷启动第一次请求丢鉴权,重开一次又好了。同一周客服接到反馈:退出登录换个账号,新用户进来能看到上一个人的订单列表。
复盘下来,原因落在两处。请求没有统一入口,凭证怎么传跟着平台各自为政,改一次后端鉴权要改几十个调用点;缓存没有归属,页面自己去 uni.getStorageSync('orderList'),谁也不知道哪些 key 该在退出时清掉。
这一章把这两处都收拢:请求只走一个文件,缓存只走一个文件,状态交给 Pinia。版本口径截至 2026 年 11 月,uni.request 的超时默认 60000ms,content-type 默认 application/json。
核心概念
请求要有一层壳
请求封装(request wrapper)指的是在 uni.request 之上加一层自己的函数,把 baseURL、凭证、超时、错误码处理、重试、加载态这些横切逻辑收在一处。
裸调的问题不是难写,是改不动。项目里有一百处 uni.request({ url: '/api/order' }),某天后端要求所有请求加一个 X-Client-Version 头,你就要改一百处,还得担心漏。封一层之后只改一处。
// src/utils/request.js
const BASE = 'https://api.example.com'
const TIMEOUT = 15000
export function request(options) {
const token = uni.getStorageSync('token')
return new Promise((resolve, reject) => {
const task = uni.request({
url: BASE + options.url,
method: (options.method || 'GET').toUpperCase(),
data: options.data,
timeout: options.timeout || TIMEOUT,
header: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
success: (res) => {
if (res.statusCode === 401) {
uni.removeStorageSync('token')
uni.reLaunch({ url: '/pages/login/login' })
return reject(new Error('登录已过期'))
}
if (res.statusCode >= 400) return reject(new Error(`HTTP ${res.statusCode}`))
resolve(res.data)
},
fail: (err) => reject(new Error(err.errMsg || '网络异常'))
})
if (options.onTask) options.onTask(task)
})
}运行结果:request({ url: '/user/profile' }) 在拿到 200 时 resolve 出后端返回的 JSON 对象;token 过期时清掉本地 token 并 reLaunch 到登录页,调用方拿到 Error: 登录已过期;断网时 reject 出 Error: request:fail;超时的文案是 request:fail timeout,主动中断是 request:fail abort。各端措辞有出入,判断时看前缀不看全文。
method 必须大写,写小写时部分平台会直接按 GET 发出去。返回的 RequestTask 只有一个用处——中断请求,页面 onUnload 时调用 abort(),能省掉一批「页面已销毁还在 setData」的报错。
拦截器能做什么,不能做什么
拦截器(interceptor)是框架级全局钩子,写法是 uni.addInterceptor('request', {...}),四个时机:invoke(发请求前改参数)、success、fail、complete,还有一个 returnValue 可以改返回值。
它的价值在跨页面一致性:baseURL 拼接、版本头注入、日志埋点、统一 toast。它的边界也得记住:只对异步接口有效,setStorageSync 这类同步 API 拦不到;uniCloud 的 callFunction 底层也用 uni.request 发请求,如果拦截器里无差别处理 401,会把云函数调用一起打回登录页。所以拦截器里按 url 前缀放行,是必须写的一行。
401 那段有个细节容易漏:登录页自己的请求也会命中它,于是页面不停 reLaunch 到自身,看起来像死循环。判断条件里加一句「当前不在登录页」就行。
那封装和拦截器选哪个?两者不冲突,分工不同:拦截器管「所有请求都要做的事」,封装管「这一层业务语义」,比如统一返回 { code, data, message } 的拆包。项目里只留一个入口给业务调用,拦截器在入口内部生效。
三端凭证:cookie 靠不住
这是多端项目里最容易判断错的一块。uni.request 在 App 与 H5 上会自动带上 cookie,H5 端还不可手动改 header 里的 cookie;小程序端不自动保持 cookie,Set-Cookie 基本用不上。H5 的 withCredentials 默认 false,跨域要显式打开,而且按 W3C 规范,跨域响应里的 Set-Cookie 前端读不到。
| 关注点 | H5 | 微信小程序 | App |
|---|---|---|---|
| 自动带 cookie | 是 | 否 | 是 |
| 能否读写 cookie | 只能读同源、不可改 header | 不支持 | 由原生内核管理 |
| 跨域限制 | 有,需 withCredentials 与 CORS | 有,需配请求合法域名 | 无 |
| 推荐凭证方式 | header 放 token(别依赖 cookie) | header 放 token | header 放 token |
| 典型失败提示 | 跨域被拦,控制台报 CORS | request:fail url not in domain list | 首次冷启动丢 cookie |
结论只有一条:三端统一用 header 传 token,cookie 只当 H5 的兼容手段。小程序端还需要在微信后台配 request 合法域名,开发者工具里勾了「不校验合法域名」本地能跑,真机直接 fail,这是「模拟器好好的,真机全挂」的常见原因。
App 上那个「冷启动第一次请求丢鉴权」也有解释:cookie 由 WebView 内核持久化,首次启动时可能还没落盘。把 token 放 header 之后,这个偶发问题会一起消失。
Pinia 接进来,然后别把它当缓存
uni-app 的 Vue3 工程里,main.js 用的是 createSSRApp 而不是 createApp,Pinia 挂在它上面:
// src/main.js
import { createSSRApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
export function createApp() {
const app = createSSRApp(App)
const pinia = createPinia()
app.use(pinia)
return { app, pinia }
}运行结果:H5 端页面正常启动,useUserStore() 在任意页面拿到的是同一个实例。把 createSSRApp 换成 vue 导出的 createApp,H5 上照样能跑,小程序构建时就报错——小程序端只认 createSSRApp 这个入口,这也是从 Web 项目迁过来最常见的一处改动。
return { app, pinia } 这个写法是为非组件文件准备的:请求封装、路由守卫这类地方要读 store,就得拿到同一个 pinia 实例,不能在模块里再 createPinia() 一次,否则两套状态互相看不见。
持久化要自己做。Pinia 没有内置存储适配,uni-app 里也没有 localStorage 可用,思路是订阅变更后写 uni.setStorageSync,启动时读回来并做一次校验。这里有个分工必须说清楚:store 是内存,进程结束就没了;storage 是磁盘,跨会话。把「购物车」放 store 不持久化,用户杀进程回来就空了;把「商品列表」也丢进 store 并持久化,退出登录时又容易忘了清。
本地存储:三种实现,三个上限
uni.setStorageSync 在三端背后的实现完全不同,上限和生命周期也不一样:
| 端 | 底层实现 | 上限 | 会不会被清 |
|---|---|---|---|
| H5 | localStorage | 约 5MB | 会,属缓存概念,浏览器清理时会丢 |
| 微信小程序 | 原生 storage | 单 key 1MB,总计 10MB | 用户主动删或长期不用被回收 |
| App | plus.storage | 无明确上限 | 持久化,卸载才没 |
两条容易忽略的规则:uni-、uni_、dcloud-、dcloud_ 开头的是系统保留前缀,业务 key 要避开;非 App 平台上清空 Storage 会导致 deviceId 变化,埋点和风控会把它当成新设备。
缓存策略按「内存 → 磁盘 → 网络」三层排。页面级数据放内存(响应式变量),跨页面数据放 storage 并带过期时间,网络请求在缓存命中且未过期时不发。过期之后先返回旧数据再后台刷新,这套写法叫 stale-while-revalidate,用户看到的永远不是转圈,而是一份可能旧几秒的内容。读取顺序如图 4-1 所示。
图 4-1 三层缓存的读取顺序与失败回落
缓存 key 加版本前缀是一条便宜保险:v1:order:list。数据结构变了就发 v2:,旧 key 自然失效,不用写迁移代码。
弱网:先给反馈,再谈重试
弱网下的体验问题,一半出在「没有反馈」,一半出在「重试乱来」。
反馈先解决:请求超过 300ms 没回来就上骨架屏;超过 8 秒给一句「网络较慢,正在重试」,而不是让转圈一直转。
重试要挑接口。GET 与显式幂等的接口可以重试,指数退避(1s、2s、4s)加最大三次;创建订单、支付这类写接口不能盲目重试,重试两次可能生成三笔订单。真要重试,让请求带一个客户端生成的 requestId,后端按它去重。
还有一个便宜的优化:请求合并。同一个 URL 在 200ms 内被并发调用多次(首页三个组件各要一次用户信息),只发一次,其余挂在这个 Promise 上。实现只有十几行,能砍掉首屏三成请求数。
动手实践
第一步,把上面的 request 接到业务里,再加一个带缓存的读接口:
// src/utils/cache.js
const PREFIX = 'v1:'
const memory = new Map()
export function cached(key, ttl, fetcher) {
if (memory.has(key)) return Promise.resolve(memory.get(key))
const raw = uni.getStorageSync(PREFIX + key)
if (raw && raw.expiresAt > Date.now()) {
memory.set(key, raw.value)
return Promise.resolve(raw.value)
}
return fetcher().then((value) => {
memory.set(key, value)
uni.setStorageSync(PREFIX + key, { value, expiresAt: Date.now() + ttl })
return value
})
}运行结果:连续两次调用 cached('user:profile', 60000, fetchProfile),第二次不发网络请求,直接命中内存;杀掉小程序重进,第二次命中 storage,仍然不发请求;把 ttl 改成 1000 并等 1.5 秒再调,会重新走网络并覆盖缓存。这三个动作各试一次,缓存的三层就清楚了。
第二步,写一个带持久化的用户 store,并在退出登录时清干净:
// src/stores/user.js
import { defineStore } from 'pinia'
import { request } from '@/utils/request'
export const useUserStore = defineStore('user', {
state: () => ({ token: '', profile: null }),
actions: {
setToken(token) {
this.token = token
uni.setStorageSync('token', token)
},
async loadProfile() {
if (this.profile) return this.profile
this.profile = await request({ url: '/user/profile' })
return this.profile
},
logout() {
this.token = ''
this.profile = null
uni.removeStorageSync('token')
uni.removeStorageSync('v1:user:profile') // 缓存也得一起清
uni.reLaunch({ url: '/pages/login/login' })
}
}
})运行结果:登录后 loadProfile() 只请求一次,第二次直接返回内存里的对象;logout() 之后 token 与 profile 都是空,uni.getStorageSync('v1:user:profile') 返回空字符串,重新登录不会看到上一个人的数据。如果漏掉最后一行 removeStorageSync,就会复现这一章开头那个「换账号看到别人订单」的故障。
第三步,在 App 上验证冷启动。关掉后台、杀进程、重开,看首屏请求的 Authorization 头是否还在。预期结果是每次都在——因为 token 走 header,不再依赖 cookie 有没有落盘。
常见误解
以为拦截器能拦所有 API。 它只对异步接口生效,uni.setStorageSync 拦不到;微信小程序里点 tabBar 也不会触发 uni.switchTab,想在切 tab 时做鉴权只能在页面 onShow 里做。把权限兜底全押在拦截器上,通常一周内就会漏。
以为 H5 能在 header 里手动带 cookie。 文档写得很明确:H5 端不可手动修改 cookie,cookie 由浏览器管。想跨域带凭证只能开 withCredentials,还得后端配合 CORS,且响应头里的 Set-Cookie 前端读不到。绕不过去,就别在这上面花时间。
以为 storage 是永久的。 H5 的 localStorage 本质是缓存,浏览器清空间时会丢;微信小程序 10MB 用满之后 setStorageSync 会失败,而 try/catch 常常没写;App 才是真持久。更隐蔽的一条:非 App 平台 clearStorage 会换掉 deviceId,事后对不上设备埋点,很难查。
小结
- 请求只留一个入口:baseURL、凭证、超时、401、重试都在里面;
method大写,RequestTask在onUnload里abort()。 - 拦截器管全局横切,封装管业务语义;拦截器只对异步接口生效,且要在 uniCloud 请求上放行。
- 三端凭证统一走 header,cookie 只当 H5 的兼容手段;小程序必须配 request 合法域名,否则真机 fail。
- Pinia 用
createSSRApp接,return { app, pinia }给非组件文件留出口;持久化自己写,store 与 storage 职责分开。 - 缓存按内存、磁盘、网络三层排,key 带版本前缀与过期时间;弱网先给反馈,重试只给幂等接口,写接口靠
requestId去重。
相关主题
数据能拉回来了,但一个订单列表滚到第 300 条时,页面开始掉帧,小程序端的 setData 一次传了 800KB。《性能优化:setData、长列表与首屏加载》 性能优化:setData、长列表与首屏加载 用量化方式处理这三件事,把首屏时间而不是「感觉快了」当作验收标准。