如果你已經(jīng)把 Vue 狀態(tài)管理交給 Pinia，卻還在手寫 loading / error / retry / 緩存失效 那一套“樣板代碼”！

那么今天的主角——Pinia Colada——會讓你忍不住喊一句： “哎呀，怎么不早點出現(xiàn)！”

Pinia：極簡狀態(tài)管理的“地基”

Pinia 作為 Vue 官方推薦的新一代狀態(tài)管理庫

用“扁平的 Store + 天然的 Composition API”讓“全局狀態(tài)”這件事前所未有的簡單：

// 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>

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

• 能不能別每次都重新請求？
• 加載態(tài)、錯誤態(tài)、輪詢、樂觀更新、后臺刷新……我不想再寫一遍！
• 組件卸載后再回來，數(shù)據(jù)還能保持新鮮嗎？

這些能力 Pinia本身都不管，只能靠自己“手搓”。于是——Pinia Colada 來了，它把上面所有“臟活累活”一次性打包好，還無縫貼合 Pinia 的編程體驗。

Pinia Colada 是什么？

一句話：“專為 Vue + Pinia 設(shè)計的智能數(shù)據(jù)獲取層”。

它通過提供 useQuery、useMutation 等組合式函數(shù)，把異步數(shù)據(jù)流變成狀態(tài)流，并自動幫你做：

• 請求去重 & 內(nèi)存緩存
• 后臺刷新、失效、重試
• 樂觀更新、回滾
• 與 Pinia Store 深度集成（數(shù)據(jù)即狀態(tài)，狀態(tài)即數(shù)據(jù)）

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

Pinia Colada 的 6 大優(yōu)勢

(1) 無縫銜接 Pinia

數(shù)據(jù)直接進 Store，調(diào)試時仍在 DevTools 的“Pinia”面板里，心智零切換。

(2) 不寫樣板代碼

loading / error / data 全返回，模板只關(guān)心“渲染”即可。

(3) 緩存即狀態(tài)

組件銷毀、路由跳轉(zhuǎn)、甚至 SSR，都能復用同一份緩存。

(4) 樂觀更新

useMutation 內(nèi)置 onMutate / onError / onSettled，回滾一行代碼。

(5) 插件化 & 可組合

自定義插件、組合函數(shù)，邏輯隨處復用，與 Vue 生態(tài)完全同構(gòu)。

(6) 體積夠小

2 kB，只拉取用到的函數(shù)，再不用擔心“為了緩存而引入半個世界”。

五分鐘快速上手

(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 秒內(nèi)不重復請求
})
</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

作用：取數(shù)據(jù)典型用法：列表、詳情、搜索

(2) useMutation

作用：改數(shù)據(jù)典型用法：新增、編輯、刪除

(3) defineQuery / defineMutation

作用：在 Store 里復用典型用法：跨組件共享同一查詢

(4) queryCache.invalidateQueries

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

與 TanStack Query 的“友好對比”

TanStack Query 是 React 世界的“數(shù)據(jù)獲取王者”，Vue 社區(qū)也有同名移植版。

兩者都提供緩存、后臺刷新、樂觀更新等能力，但定位與生態(tài)融合度略有差異：

結(jié)論：

• 若你同時維護 React & Vue 項目，需要“一份 API 到處跑”，TanStack Query 仍是穩(wěn)妥選擇。
• 若你深耕 Vue 生態(tài)，已經(jīng)用 Pinia 管理所有狀態(tài)，只想“用最 Vue 的方式搞定接口緩存”，Pinia Colada 會更順手、更輕量、更一體化。

寫在最后

Pinia 負責“狀態(tài)”，Pinia Colada 負責“拿狀態(tài)的路上所有臟活”。兩者加在一起，無需額外概念、零樣板、體積忽略不計，卻能讓你的 Vue 項目瞬間擁有工業(yè)級的數(shù)據(jù)獲取體驗。

還等啥？

npm i @pinia/colada 一下，把 loading = true / false 和 try…catch 統(tǒng)統(tǒng)刪掉，感受“狀態(tài)即緩存，緩存即狀態(tài)”的絲滑吧！

官網(wǎng)地址：https://pinia-colada.esm.dev/