前言
pinia-colada 是一款基于 Pinia 的状态管理库插件，旨在为 Vue 应用提供强大而便捷的异步状态管理和请求处理能力。其官方功能亮点包括：
⚡️ 自动缓存：具备智能的客户端缓存机制，支持请求去重，避免重复加载。
🗄️ 异步状态管理：轻松管理各种异步操作和状态。
🔌 插件系统：提供灵活且强大的插件扩展机制。
✨ 乐观更新：支持在请求提交前先行更新 UI，提升用户体验。
💡 合理的默认配置：内置推荐配置，同时支持高度自定义。
🧩 开箱即用的插件：提供一组组合式函数，简化数据获取逻辑。
📚 TypeScript 支持：具备完整的 TypeScript 类型定义。
💨 轻量体积：核心大小约 2KB，支持 Tree Shaking 优化。
📦 零依赖：除 Pinia 外不依赖任何其他第三方库。

⚙️ SSR 支持：天然兼容服务端渲染（SSR）场景。

与 vue-use 等工具库中的 useAxios 不同，pinia-colada 直接依托 Pinia Store 进行请求缓存，具备更原生的缓存管理机制。该库的核心是 useQuery 和 useMutation，同时还提供 defineQuery 与 defineMutation，用于在 Pinia Store 中组织查询与变更逻辑。

一.useQuery
useQuery 用于处理异步数据获取，支持缓存、加载状态与错误处理，其基本返回结构如下：

import { useQuery } from'@pinia/colada';
const {
  state,          // 包含 data、error、status 等状态对象
  asyncStatus,    // 异步状态（loading / error / success 等）
  refresh,        // 手动刷新当前查询
  refetch,        // 重新获取（忽略缓存）
// 以下为状态别名：
  error,          // 错误对象
  data,           // 成功返回的数据
  status,         // 状态：idle / loading / success / error
  isLoading,      // 是否正在加载
  isPending,      // 是否处于等待中
  isPlaceholderData, // 是否为占位数据
} = useQuery({
key: ['todos'], // 查询唯一标识
query: () => fetch('/api/todos').then((res) => res.json()), // 查询函数
});

动态查询
key 不仅可以是静态数组，也可以是函数，适用于依赖动态参数的场景：

const todoId = ref(1);
const { data, isLoading } = useQuery({
  key: () => ['todo', todoId.value], // 依赖响应式变量动态生成 key
  query: () => fetch(`/api/todos/${todoId.value}`).then((res) => res.json()),
});
// 堆代码 duidaima.com
// todoId 变化时，useQuery 会自动重新发起请求
todoId.value = 2;

动态 key 的使用场景：
.适用于分页、筛选、详情查询等依赖动态参数获取数据的场景。
.key 变化时会自动触发查询重新执行。
.若在分页等场景中希望保留上一页数据作为占位，可使用 placeholderData 避免UI闪烁：

const { state } = useQuery({
  key: () => ['contacts', Number(route.query.page) || 1],
  query: () =>
    fetch(`/api/contacts?page=${Number(route.query.page) || 1}`).then((res) => res.json()),
  placeholderData: (previousData) => previousData,
})

二.defineQuery
defineQuery 用于在 Pinia Store 中定义查询方法，使其可在多个组件中复用。

基本用法

import { defineStore } from'pinia';
import { defineQuery } from'@pinia/colada';

exportconst useTodoStore = defineStore('todo', () => {
const fetchTodos = defineQuery({
    key: ['todos'],
    query: () => fetch('/api/todos').then((res) => res.json()),
  });

return { fetchTodos };
});

在组件中使用：

import { useTodoStore } from '@/stores/todoStore';
const todoStore = useTodoStore();
const { data, isLoading } = todoStore.fetchTodos();

动态查询

const fetchTodoById = defineQuery({
  key: (id) => ['todo', id],
  query: (id) => fetch(`/api/todos/${id}`).then((res) => res.json()),
});

// 在组件中使用
const { data, isLoading } = fetchTodoById(todoId.value);

三.useMutation
useMutation 用于处理数据变更操作（如 POST、PUT、DELETE 等），提供状态管理与提交能力。

import { useMutation } from'@pinia/colada';

const {
  mutate,          // 触发变更的函数
  state,           // 包含 data、error、status 的状态对象
  asyncStatus,     // 异步状态
  reset,           // 重置状态
// 状态别名：
  error,
  data,
  status,
  isLoading,
  isPending,
} = useMutation({
mutation: (newTodo) =>
    fetch('/api/todos', {
      method: 'POST',
      body: JSON.stringify(newTodo),
    }).then((res) => res.json()),
});

// 提交变更
mutate({ title: 'New Todo', completed: false });
defineMutation
defineMutation 用于在 Pinia Store 中定义变更操作，增强代码组织性。

import { defineStore } from'pinia';
import { defineMutation } from'@pinia/colada';

exportconst useTodoStore = defineStore('todo', () => {
const addTodo = defineMutation({
    mutation: (newTodo) =>
      fetch('/api/todos', {
        method: 'POST',
        body: JSON.stringify(newTodo),
      }).then((res) => res.json()),
  });

return { addTodo };
});

在组件中使用：

import { useTodoStore } from '@/stores/todoStore';
const todoStore = useTodoStore();
const { mutate, isLoading } = todoStore.addTodo;
mutate({ title: 'New Todo', completed: false });

总结
pinia-colada 通过 useQuery / defineQuery 和 useMutation / defineMutation 提供了一套完整而优雅的异步状态管理方案。它不仅支持静态与动态的查询场景，还具备缓存管理、乐观更新、插件扩展等高级功能，显著简化了复杂应用中的数据加载与状态管理逻辑。

相关链接：
官方库：github.com/posva/pinia-colada
官方文档：pinia-colada.esm.dev