Vue3 + Colada！无敌了！_colada vue-优快云博客

Pinia 负责“状态”，Pinia Colada 负责“拿状态的路上所有脏活”。两者加在一起，无需额外概念、零样板、体积忽略不计，却能让你的 Vue 项目瞬间拥有工业级的数据获取体验。

如果你已经把 Vue 状态管理交给 Pinia，却还在手写 loading / error / retry / 缓存失效那一套“样板代码”！

那么今天的主角——Pinia Colada——会让你忍不住喊一句： “哎呀，怎么不早点出现！”

Pinia：极简状态管理的“地基”

Pinia 作为 Vue 官方推荐的新一代状态管理库

用“扁平的 Store + 天然的 Composition API”让“全局状态”这件事前所未有的简单：

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const profile = ref<User | null>(null)
  async function fetchUser(id: number) {
    profile.value = await axios.get(`/api/user/${id}`)
  }
  return { profile, fetchUser }
})

组件里随用随取：

<script setup>
const user = useUserStore()
await callWhenReady(user.fetchUser, route.params.id)
</script>
<template>
  <div v-if="user.profile">{{ user.profile.name }}</div>
</template>

一切都很美好，直到你开始想：

能不能别每次都重新请求？
加载态、错误态、轮询、乐观更新、后台刷新……我不想再写一遍！
组件卸载后再回来，数据还能保持新鲜吗？

这些能力 Pinia本身都不管，只能靠自己“手搓”。于是——Pinia Colada 来了，它把上面所有“脏活累活”一次性打包好，还无缝贴合 Pinia 的编程体验。

Pinia Colada 是什么？

一句话：“专为 Vue + Pinia 设计的智能数据获取层”。

它通过提供 useQuery、useMutation 等组合式函数，把异步数据流变成状态流，并自动帮你做：

请求去重 & 内存缓存
后台刷新、失效、重试
乐观更新、回滚
与 Pinia Store 深度集成（数据即状态，状态即数据）

零依赖（除 Pinia 外）≈ 2 kB，Tree-Shaking 友好，TypeScript 100%。

Pinia Colada 的 6 大优势

(1) 无缝衔接 Pinia

数据直接进 Store，调试时仍在 DevTools 的“Pinia”面板里，心智零切换。

(2) 不写样板代码

loading / error / data 全返回，模板只关心“渲染”即可。

(3) 缓存即状态

组件销毁、路由跳转、甚至 SSR，都能复用同一份缓存。

(4) 乐观更新

useMutation 内置 onMutate / onError / onSettled，回滚一行代码。

(5) 插件化 & 可组合

自定义插件、组合函数，逻辑随处复用，与 Vue 生态完全同构。

(6) 体积够小

2 kB，只拉取用到的函数，再不用担心“为了缓存而引入半个世界”。

五分钟快速上手

(1) 安装

npm i pinia @pinia/colada

(2) 注册插件

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'

const pinia = createPinia()
pinia.use(PiniaColada)

createApp(App).use(pinia).mount('#app')

(3) 组件里直接查询

<script setup>
import { useQuery } from '@pinia/colada'

const { data, isLoading, error } = useQuery({
  key: ['todos'],
  query: () => fetch('/api/todos').then(r => r.json()),
  staleTime: 5000,   // 5 秒内不重复请求
})
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else-if="error">Oops: {{ error.message }}</div>
  <ul v-else>
    <li v-for="t in data" :key="t.id">{{ t.title }}</li>
  </ul>
</template>

(4) 提交变更（乐观更新）

const { mutate, isPending } = useMutation({
  mutation: (newTodo: string) =>
    axios.post('/api/todos', { title: newTodo }),
  onMutate: async (newTodo) => {
    // 立即写到缓存，UI 秒变
    const prev = queryClient.getQueryData(['todos'])
    queryClient.setQueryData(['todos'], old => [...old, { id: Date.now(), title: newTodo }])
    return { prev }          // 回滚快照
  },
  onError: (err, _, context) =>
    queryClient.setQueryData(['todos'], context.prev),
})

必知四大核心 API

(1) useQuery

作用：取数据典型用法：列表、详情、搜索

(2) useMutation

作用：改数据典型用法：新增、编辑、删除

(3) defineQuery / defineMutation

作用：在 Store 里复用典型用法：跨组件共享同一查询

(4) queryCache.invalidateQueries

作用：手动失效典型用法：增删改后刷新列表

与 TanStack Query 的“友好对比”

TanStack Query 是 React 世界的“数据获取王者”，Vue 社区也有同名移植版。

两者都提供缓存、后台刷新、乐观更新等能力，但定位与生态融合度略有差异：

维度	TanStack Query (Vue)	Pinia Colada
生态理念	框架无关，通用缓存层	专为 Vue + Pinia 而生
状态归属	独立于 Store，另起炉灶	查询结果 = Pinia State ，DevTools 一站式查看
学习曲线	需理解 queryClient / QueryCache 新概念	沿用 ref / computed / watch 即可
插件扩展	提供 queryClient 级插件	直接写 Pinia 插件，与现有 Store 逻辑无缝组合
体积	~ 13 kB（核心）	~ 2 kB（核心）
SSR	支持	支持，且自动复用 Pinia 的 SSR 注入