Skip to content

网络与数据:请求封装、缓存与状态管理 ​

本篇要点:把请求收进一层可替换的封装,说清三端凭证的传递差别,让 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 头,你就要改一百处,还得担心漏。封一层之后只改一处。

js
// 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 } 的拆包。项目里只留一个入口给业务调用,拦截器在入口内部生效。

这是多端项目里最容易判断错的一块。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 放 tokenheader 放 token
典型失败提示跨域被拦,控制台报 CORSrequest: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 挂在它上面:

js
// 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 在三端背后的实现完全不同,上限和生命周期也不一样:

端底层实现上限会不会被清
H5localStorage约 5MB会,属缓存概念,浏览器清理时会丢
微信小程序原生 storage单 key 1MB,总计 10MB用户主动删或长期不用被回收
Appplus.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 接到业务里,再加一个带缓存的读接口:

js
// 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,并在退出登录时清干净:

js
// 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、长列表与首屏加载 用量化方式处理这三件事,把首屏时间而不是「感觉快了」当作验收标准。