Pinia 状态管理深度详解

npm install pinia

// main.js
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const app = createApp(App);
const pinia = createPinia();

app.use(pinia);
app.mount('#app');

npm install @pinia/nuxt

// nuxt.config.js
export default defineNuxtConfig({
  modules: ['@pinia/nuxt']
});

// stores/counter.js
import { defineStore } from 'pinia';

// 第一个参数 'counter' 是全局唯一 ID，用于 Devtools 与数据隔离
export const useCounterStore = defineStore('counter', {
  // state：状态（必须是返回对象的箭头函数，保证每个实例独立）
  state: () => ({
    count: 0,
    name: 'Pinia'
  }),

  // getters：计算属性
  getters: {
    doubleCount: (state) => state.count * 2,
    upperName: (state) => state.name.toUpperCase()
  },

  // actions：方法
  actions: {
    increment() {
      this.count++;
    },
    incrementBy(amount) {
      this.count += amount;
    }
  }
});

<script setup>
import { useCounterStore } from '@/stores/counter';

const counterStore = useCounterStore();

// 访问 state
console.log(counterStore.count);

// 访问 getters
console.log(counterStore.doubleCount);

// 调用 actions
counterStore.increment();
counterStore.incrementBy(5);
</script>

<template>
  <div>
    <p>Count: {{ counterStore.count }}</p>
    <p>Double: {{ counterStore.doubleCount }}</p>
    <button @click="counterStore.increment">+1</button>
    <button @click="counterStore.incrementBy(5)">+5</button>
  </div>
</template>

const store = useCounterStore();
console.log(store.count);

import { storeToRefs } from 'pinia';

const store = useCounterStore();
// storeToRefs 会把 state 和 getters 转成 ref，解构后仍保持响应式
const { count, name } = storeToRefs(store);

console.log(count.value); // 在 <script> 中用 .value，模板中直接用 count

const store = useCounterStore();
const { count } = store;
// count 只是一次性拷贝的普通值，store.count 之后变化，这里的 count 不会更新

store.count = 10;

// 修改多个字段：Pinia 会合并成一次更新，只触发一次订阅
store.$patch({
  count: 10,
  name: 'New Name'
});

// 函数形式：适合数组操作或依赖旧值的复杂修改
store.$patch((state) => {
  state.count++;
  state.items.push({ id: 1 });
});

store.increment();

// Options Store 自带 $reset，恢复到 state() 定义的初始值
store.$reset();

// 订阅 state 变化
const unsubscribe = store.$subscribe((mutation, state) => {
  console.log('变更类型:', mutation.type);
  console.log('最新状态:', state);
});
unsubscribe(); // 组件卸载时可手动取消（默认会随组件自动清理）

export const useUserStore = defineStore('user', {
  state: () => ({
    firstName: 'John',
    lastName: 'Doe',
    age: 25
  }),
  getters: {
    // 通过 state 参数访问状态
    fullName: (state) => state.firstName + ' ' + state.lastName,

    // 通过 this 访问其他 getter（注意：此时不能用箭头函数）
    fullInfo() {
      return this.fullName + ', ' + this.age + ' years old';
    }
  }
});

export const useProductStore = defineStore('product', {
  state: () => ({
    products: [
      { id: 1, name: 'Product A', price: 100 },
      { id: 2, name: 'Product B', price: 200 }
    ]
  }),
  getters: {
    // 返回函数的 getter（无缓存）
    getProductById: (state) => (id) => {
      return state.products.find((p) => p.id === id);
    },
    getProductsByPrice: (state) => (maxPrice) => {
      return state.products.filter((p) => p.price <= maxPrice);
    }
  }
});

const productStore = useProductStore();
const product = productStore.getProductById(1);
const cheapProducts = productStore.getProductsByPrice(150);

export const useCartStore = defineStore('cart', {
  state: () => ({ items: [] }),
  getters: {
    total: (state) => {
      // 在 getter 内部可以直接调用其他 store
      const userStore = useUserStore();
      const discount = userStore.isVip ? 0.9 : 1;
      return state.items.reduce((sum, item) => sum + item.price, 0) * discount;
    }
  }
});

export const useUserStore = defineStore('user', {
  state: () => ({
    user: null,
    token: '',
    loading: false
  }),
  actions: {
    // 同步 action
    setUser(user) {
      this.user = user;
    },

    // 异步 action
    async login(credentials) {
      this.loading = true;
      const response = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify(credentials)
      });
      const data = await response.json();
      this.user = data.user;
      this.token = data.token;
      localStorage.setItem('token', data.token);
      this.loading = false;
    },

    logout() {
      this.user = null;
      this.token = '';
      localStorage.removeItem('token');
    }
  }
});

actions: {
  async loginAndFetchProfile(credentials) {
    // 调用当前 store 的其他 action
    await this.login(credentials);

    // 调用其他 store 的 action
    const profileStore = useProfileStore();
    await profileStore.fetchProfile();
  }
}

actions: {
  async login(credentials) {
    try {
      const response = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify(credentials)
      });
      if (!response.ok) throw new Error('Login failed');
      const data = await response.json();
      this.user = data.user;
      this.token = data.token;
    } catch (error) {
      console.error('Login error:', error);
      throw error; // 继续抛出，让组件层决定如何提示用户
    }
  }
}

const store = useUserStore();

store.$onAction(({ name, args, after, onError }) => {
  const start = Date.now();
  after((result) => {
    console.log(`[action] ${name} 成功，耗时 ${Date.now() - start}ms`);
  });
  onError((error) => {
    // 统一错误上报
    reportError({ action: name, args, error });
  });
});

// stores/cart.js
import { defineStore } from 'pinia';
import { useUserStore } from './user';
import { useProductStore } from './product';

export const useCartStore = defineStore('cart', {
  state: () => ({ items: [] }),
  getters: {
    total() {
      const userStore = useUserStore();
      const productStore = useProductStore();

      const subtotal = this.items.reduce((sum, item) => {
        const product = productStore.getProductById(item.productId);
        return sum + (product?.price || 0) * item.quantity;
      }, 0);

      return userStore.isVip ? subtotal * 0.9 : subtotal;
    }
  }
});

<script setup>
import { useUserStore } from '@/stores/user';
import { useCartStore } from '@/stores/cart';
import { useProductStore } from '@/stores/product';

const userStore = useUserStore();
const cartStore = useCartStore();
const productStore = useProductStore();

// 真实场景：未登录先登录，再加购
const buyProduct = async (productId) => {
  if (!userStore.user) {
    await userStore.login({ username: 'guest', password: 'guest' });
  }
  const product = productStore.getProductById(productId);
  cartStore.addItem({ productId, quantity: 1 });
};
</script>

npm install pinia-plugin-persistedstate

// main.js
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);

const app = createApp(App);
app.use(pinia);

export const useUserStore = defineStore('user', {
  state: () => ({ user: null, token: '' }),
  persist: {
    key: 'user-store',   // localStorage 键名
    storage: localStorage, // 也可用 sessionStorage
    paths: ['token']     // 只持久化 token，避免存整个 user 对象
  }
});

export const useUserStore = defineStore('user', {
  state: () => ({ user: null, token: '' }),
  actions: {
    login(credentials) {
      this.token = 'new-token';
      localStorage.setItem('token', this.token); // 写入
    },
    init() {
      const token = localStorage.getItem('token'); // 恢复
      if (token) this.token = token;
    }
  }
});

// plugins/logger.js
export function loggerPlugin({ store, options }) {
  // 给每个 store 注入一个公共属性
  store.createdAt = new Date();

  // 订阅每个 store 的状态变化
  store.$subscribe((mutation, state) => {
    console.log(`[${store.$id}] 状态变化:`, mutation.type);
  });

  // 也可以返回对象来添加属性（会被 Devtools 追踪）
  return { secret: 'shared-value' };
}

// main.js
pinia.use(loggerPlugin);

// stores/user.ts
import { defineStore } from 'pinia';

interface User {
  id: number;
  name: string;
  email: string;
}

interface UserState {
  user: User | null;
  token: string;
}

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    user: null,
    token: ''
  }),
  getters: {
    isLoggedIn: (state): boolean => !!state.token,
    userName: (state): string => state.user?.name ?? 'Guest'
  },
  actions: {
    async login(credentials: { username: string; password: string }) {
      const response = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify(credentials)
      });
      const data: { user: User; token: string } = await response.json();
      this.user = data.user;
      this.token = data.token;
    }
  }
});

// stores/counter.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export const useCounterStore = defineStore('counter', () => {
  // ref → state
  const count = ref(0);
  const name = ref('Pinia');

  // computed → getters
  const doubleCount = computed(() => count.value * 2);
  const upperName = computed(() => name.value.toUpperCase());

  // function → actions
  function increment() {
    count.value++;
  }
  function incrementBy(amount: number) {
    count.value += amount;
  }
  function reset() {
    count.value = 0; // Setup Store 需手动实现 reset
  }

  // 必须 return 需要暴露的内容，否则外部访问不到
  return { count, name, doubleCount, upperName, increment, incrementBy, reset };
});

// stores/auth.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

interface User {
  id: number;
  name: string;
  roles: string[];
}

export const useAuthStore = defineStore('auth', () => {
  const user = ref<User | null>(null);
  const token = ref('');
  const loading = ref(false);

  const isLoggedIn = computed(() => !!token.value);
  const isAdmin = computed(() => user.value?.roles.includes('admin') ?? false);

  async function login(username: string, password: string) {
    loading.value = true;
    try {
      const res = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify({ username, password })
      });
      if (!res.ok) throw new Error('用户名或密码错误');
      const data = await res.json();
      user.value = data.user;
      token.value = data.token;
      localStorage.setItem('token', data.token);
    } finally {
      loading.value = false;
    }
  }

  function logout() {
    user.value = null;
    token.value = '';
    localStorage.removeItem('token');
  }

  // 应用启动时恢复登录态
  async function restore() {
    const saved = localStorage.getItem('token');
    if (!saved) return;
    token.value = saved;
    const res = await fetch('/api/me', {
      headers: { Authorization: `Bearer ${saved}` }
    });
    if (res.ok) {
      user.value = await res.json();
    } else {
      logout(); // token 失效则清理
    }
  }

  return { user, token, loading, isLoggedIn, isAdmin, login, logout, restore };
});

stores/
├── user.ts          # 用户相关状态
├── cart.ts          # 购物车相关状态
├── product.ts       # 产品相关状态
├── settings.ts      # 设置相关状态
└── index.ts         # 统一导出

// 简化版 defineStore 原理示意
function defineStore(id, setup) {
  function useStore() {
    // 从当前 pinia 实例的缓存里取，取不到才创建
    const pinia = getActivePinia();
    if (!pinia._stores.has(id)) {
      createSetupStore(id, setup, pinia); // 首次调用才创建
    }
    return pinia._stores.get(id);
  }
  useStore.$id = id;
  return useStore;
}

import { effectScope, ref, computed } from 'vue';

// effectScope 的作用演示
const scope = effectScope();

scope.run(() => {
  const count = ref(0);
  // 这个 computed 归属于 scope
  const double = computed(() => count.value * 2);
  // watch 也归属于 scope
  watch(count, () => console.log('changed'));
});

// 一行清理作用域内所有副作用
scope.stop();

import { reactive, toRefs } from 'vue';

const state = reactive({ count: 0, name: '张三' });

// 错误：解构后 count 只是数字 0，不再响应式
const { count } = state;
// count 永远是 0，state.count 变了它也不变

// 正确：toRefs 把每个属性转成 ref，保持响应式连接
const { count: countRef } = toRefs(state);
// countRef.value 会随 state.count 变化

// storeToRefs 就是 Pinia 版的 toRefs，且会跳过 actions（方法不需要转 ref）

// storeToRefs 简化原理
function storeToRefs(store) {
  const refs = {};
  for (const key in store) {
    const value = store[key];
    // 只对 state 和 getters 转 ref，跳过函数（actions）
    if (isRef(value) || isReactive(value)) {
      refs[key] = toRef(store, key);
    }
  }
  return refs;
}

// 写法一：Options Store（类似 Vuex/Options API，直观）
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
    history: []
  }),
  getters: {
    double: (state) => state.count * 2,
    // 访问其他 getter 用 this
    doublePlusOne() {
      return this.double + 1;
    }
  },
  actions: {
    increment() {
      this.count++;
      this.history.push(this.count);
    },
    async fetchAndAdd() {
      const res = await fetch('/api/num').then((r) => r.json());
      this.count += res.value;
    }
  }
});

// 写法二：Setup Store（类似 Composition API，灵活）
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export const useCounterStore = defineStore('counter', () => {
  // ref/reactive → state
  const count = ref(0);
  const history = ref([]);

  // computed → getters
  const double = computed(() => count.value * 2);
  const doublePlusOne = computed(() => double.value + 1);

  // function → actions
  function increment() {
    count.value++;
    history.value.push(count.value);
  }

  async function fetchAndAdd() {
    const res = await fetch('/api/num').then((r) => r.json());
    count.value += res.value;
  }

  // 必须显式返回所有要暴露的内容
  return { count, history, double, doublePlusOne, increment, fetchAndAdd };
});

export const useSearchStore = defineStore('search', () => {
  const results = ref([]);
  // 私有状态：不 return，外部无法访问，仅内部逻辑使用
  const _cache = new Map();
  let _requestId = 0;

  async function search(keyword) {
    if (_cache.has(keyword)) {
      results.value = _cache.get(keyword);
      return;
    }
    const currentId = ++_requestId;
    const res = await fetch(`/api/search?q=${keyword}`).then((r) => r.json());
    // 防止竞态：只接受最新请求的结果
    if (currentId === _requestId) {
      results.value = res;
      _cache.set(keyword, res);
    }
  }

  // 只暴露 results 和 search，_cache 和 _requestId 对外隐藏
  return { results, search };
});

export const useFormStore = defineStore('form', () => {
  const getInitialState = () => ({ name: '', email: '', age: 0 });
  const form = ref(getInitialState());

  function $reset() {
    form.value = getInitialState();
  }

  return { form, $reset };
});

const store = useUserStore();

// 方式一：传对象（适合简单字段更新）
store.$patch({
  name: '李四',
  age: 30,
  isVip: true
});

// 方式二：传函数（适合数组操作、依赖旧值的复杂更新）
store.$patch((state) => {
  state.items.push({ id: 1, name: '商品' });
  state.total = state.items.reduce((sum, i) => sum + i.price, 0);
  state.count++;
});

const cartStore = useCartStore();

// 订阅 state 变化
const unsubscribe = cartStore.$subscribe((mutation, state) => {
  // mutation.type: 'direct'(直接改) | 'patch object' | 'patch function'
  // mutation.storeId: store 的 id
  console.log('变更类型:', mutation.type);
  console.log('store:', mutation.storeId);

  // 典型用途：自动持久化到 localStorage
  localStorage.setItem('cart', JSON.stringify(state.items));
}, {
  detached: true // 组件卸载后仍保持订阅（默认组件卸载会自动取消）
});

// 手动取消订阅
// unsubscribe();

const store = useUserStore();

store.$onAction(({
  name,    // action 名称
  store,   // store 实例
  args,    // 传给 action 的参数
  after,   // 钩子：action 成功返回后（Promise 也会 resolve 后）
  onError  // 钩子：action 抛错时
}) => {
  const startTime = Date.now();
  console.log(`开始执行 action: ${name}，参数:`, args);

  after((result) => {
    console.log(`${name} 执行成功，耗时 ${Date.now() - startTime}ms，返回:`, result);
  });

  onError((error) => {
    console.error(`${name} 执行失败:`, error);
    // 可在此统一上报错误
  });
});

const store = useCounterStore();

// $reset：把 state 重置为初始值（仅 Options Store 内置）
store.$reset();

// $state：直接读取或整体替换整个 state
console.log(store.$state);
store.$state = { count: 100, name: '重置' }; // 整体替换

// $dispose：停止 store 的响应式作用域并从 pinia 中移除
store.$dispose();

// 迁移前：Vuex
const store = {
  namespaced: true,
  state: () => ({ count: 0 }),
  getters: {
    double: (state) => state.count * 2
  },
  mutations: {
    // Vuex 必须通过 mutation 改 state
    INCREMENT(state, payload) {
      state.count += payload;
    }
  },
  actions: {
    async fetchAndAdd({ commit }) {
      const res = await api.getNum();
      commit('INCREMENT', res.value); // 提交 mutation
    }
  }
};
// 组件里：this.$store.commit('module/INCREMENT', 1)
// this.$store.dispatch('module/fetchAndAdd')

// 迁移后：Pinia（省去了 mutation 这层样板代码）
export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: (state) => state.count * 2
  },
  actions: {
    increment(payload) {
      this.count += payload; // 直接改，无需 mutation
    },
    async fetchAndAdd() {
      const res = await api.getNum();
      this.increment(res.value); // 直接调用其他 action
    }
  }
});
// 组件里：const store = useCounterStore();
// store.increment(1); store.fetchAndAdd();

import { defineStore } from 'pinia';

interface UserInfo {
  id: number;
  name: string;
  roles: string[];
}

export const useUserStore = defineStore('user', {
  state: () => ({
    // 初始为 null 的字段必须断言类型，否则被推断为 null
    userInfo: null as UserInfo | null,
    token: '',
    // 空数组要标注元素类型
    permissions: [] as string[]
  }),
  getters: {
    // 返回值类型自动推导为 boolean
    isLoggedIn: (state) => !!state.token,
    // 复杂返回值可显式标注
    userName(state): string {
      return state.userInfo?.name ?? '游客';
    }
  },
  actions: {
    setUser(info: UserInfo) {
      this.userInfo = info;
      this.permissions = info.roles;
    }
  }
});

import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import type { Ref } from 'vue';

interface CartItem {
  id: number;
  name: string;
  price: number;
  quantity: number;
}

export const useCartStore = defineStore('cart', () => {
  // 显式标注 ref 泛型
  const items: Ref<CartItem[]> = ref([]);

  const totalPrice = computed(() =>
    items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
  );

  const totalCount = computed(() =>
    items.value.reduce((sum, item) => sum + item.quantity, 0)
  );

  function addItem(item: Omit<CartItem, 'quantity'>) {
    const existing = items.value.find((i) => i.id === item.id);
    if (existing) {
      existing.quantity++;
    } else {
      items.value.push({ ...item, quantity: 1 });
    }
  }

  function removeItem(id: number) {
    items.value = items.value.filter((i) => i.id !== id);
  }

  return { items, totalPrice, totalCount, addItem, removeItem };
});

import type { useCartStore } from '@/stores/cart';

// 提取 store 实例的类型
type CartStore = ReturnType<typeof useCartStore>;

// 工具函数接收 store 实例
function logCart(store: CartStore) {
  console.log(`购物车共 ${store.totalCount} 件，总价 ${store.totalPrice} 元`);
}

import 'pinia';

declare module 'pinia' {
  // 扩展 store 实例属性
  export interface PiniaCustomProperties {
    $now: number;             // 插件注入的属性
    $router: Router;
  }
  // 扩展 store 的 options（用于自定义 option）
  export interface DefineStoreOptionsBase<S, Store> {
    debounce?: Partial<Record<keyof Store, number>>;
  }
}

// 错误：state 是对象，所有请求共享同一份，多用户数据串号
// state: { count: 0 }

// 正确：state 是函数，每次调用返回全新对象，请求间隔离
export const useStore = defineStore('main', {
  state: () => ({ count: 0 }) // 每个请求独立
});

# 安装 Nuxt 模块
npm install @pinia/nuxt pinia

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  pinia: {
    // 自动导入 storeToRefs 等
    storesDirs: ['./stores/**']
  }
});

<!-- Nuxt 页面中使用（无需手动 import useStore，自动导入） -->
<script setup>
const store = useCounterStore();

// useAsyncData 在服务端预取数据，状态自动脱水注水到客户端
await useAsyncData('user', async () => {
  await store.fetchUserInfo();
  return store.userInfo;
});
</script>

// 服务端：渲染完成后把 pinia 状态序列化注入 HTML
// window.__pinia = pinia.state.value

// 客户端：初始化时用服务端状态填充，避免二次请求和闪烁
const pinia = createPinia();
if (window.__pinia) {
  pinia.state.value = window.__pinia; // 注水
}

// counter.spec.js
import { describe, it, expect, beforeEach } from 'vitest';
import { setActivePinia, createPinia } from 'pinia';
import { useCounterStore } from '@/stores/counter';

describe('Counter Store', () => {
  beforeEach(() => {
    // 每个测试前创建全新 pinia，保证测试隔离
    setActivePinia(createPinia());
  });

  it('初始 count 为 0', () => {
    const store = useCounterStore();
    expect(store.count).toBe(0);
  });

  it('increment 使 count 加一', () => {
    const store = useCounterStore();
    store.increment();
    expect(store.count).toBe(1);
  });

  it('double getter 返回两倍', () => {
    const store = useCounterStore();
    store.count = 5;
    expect(store.double).toBe(10);
  });
});

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { setActivePinia, createPinia } from 'pinia';
import { useUserStore } from '@/stores/user';
import * as authApi from '@/api/auth';

describe('User Store 登录', () => {
  beforeEach(() => setActivePinia(createPinia()));

  it('login 成功后保存 token 和用户信息', async () => {
    // Mock API
    vi.spyOn(authApi, 'login').mockResolvedValue({ token: 'abc123' });
    vi.spyOn(authApi, 'getUserInfo').mockResolvedValue({
      id: 1, name: '张三', roles: ['admin']
    });

    const store = useUserStore();
    await store.login({ username: 'admin', password: '123456' });

    expect(store.token).toBe('abc123');
    expect(store.userInfo.name).toBe('张三');
    expect(store.isLoggedIn).toBe(true);
  });
});

import { mount } from '@vue/test-utils';
import { createTestingPinia } from '@pinia/testing';
import { vi } from 'vitest';
import UserProfile from '@/components/UserProfile.vue';
import { useUserStore } from '@/stores/user';

it('渲染用户名并能触发登出', async () => {
  const wrapper = mount(UserProfile, {
    global: {
      plugins: [createTestingPinia({
        createSpy: vi.fn,             // action 自动被 spy
        initialState: {
          user: { userInfo: { name: '李四' } } // 预设初始状态
        }
      })]
    }
  });

  expect(wrapper.text()).toContain('李四');

  const store = useUserStore();
  await wrapper.find('button.logout').trigger('click');
  // 断言 action 被调用（默认不会真正执行）
  expect(store.logout).toHaveBeenCalledTimes(1);
});

import { markRaw } from 'vue';
import router from '@/router';

// 让所有 store 都能访问 router
export function routerPlugin({ store }) {
  // markRaw 避免 router 被响应式化（提升性能）
  store.$router = markRaw(router);
}

// main.js: pinia.use(routerPlugin);
// 之后任意 store 内可用 this.$router.push(...)

export function persistPlugin({ store, options }) {
  // 读取 store 定义时传入的 persist 配置
  const persist = options.persist;
  if (!persist) return;

  const key = persist.key || store.$id;

  // 初始化：从 localStorage 恢复
  const saved = localStorage.getItem(key);
  if (saved) {
    store.$patch(JSON.parse(saved));
  }

  // 订阅变化：自动写入
  store.$subscribe((mutation, state) => {
    // 支持 paths 精确控制持久化字段
    let toSave = state;
    if (persist.paths) {
      toSave = persist.paths.reduce((obj, path) => {
        obj[path] = state[path];
        return obj;
      }, {});
    }
    localStorage.setItem(key, JSON.stringify(toSave));
  });
}

import { cloneDeep } from 'lodash-es';

// 记录每个 store 的初始状态，提供全局 $resetAll
export function resetPlugin({ store }) {
  // 缓存初始 state
  const initialState = cloneDeep(store.$state);
  store.$reset = () => {
    store.$patch(cloneDeep(initialState));
  };
}

// 用途：用户退出登录时，一次性重置所有 store
// 遍历所有 store 调 $reset

function debounce(fn, delay) {
  let timer;
  return function (...args) {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

export function debouncePlugin({ options, store }) {
  if (options.debounce) {
    // 用防抖版本覆盖指定的 action
    return Object.keys(options.debounce).reduce((debounced, action) => {
      debounced[action] = debounce(store[action], options.debounce[action]);
      return debounced;
    }, {});
  }
}

// store 定义里：
// defineStore('search', { actions: {...}, debounce: { search: 300 } })

// stores/product.js
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { getProducts, getProductDetail } from '@/api/product';

export const useProductStore = defineStore('product', () => {
  const list = ref([]);
  const detail = ref(null);
  const loading = ref(false);
  const categoryFilter = ref('all');

  // 按分类过滤的商品列表
  const filteredList = computed(() => {
    if (categoryFilter.value === 'all') return list.value;
    return list.value.filter((p) => p.category === categoryFilter.value);
  });

  // 有货商品
  const inStockList = computed(() =>
    filteredList.value.filter((p) => p.stock > 0)
  );

  async function fetchList() {
    loading.value = true;
    try {
      list.value = await getProducts();
    } finally {
      loading.value = false;
    }
  }

  async function fetchDetail(id) {
    detail.value = await getProductDetail(id);
  }

  function setCategory(category) {
    categoryFilter.value = category;
  }

  return {
    list, detail, loading, categoryFilter,
    filteredList, inStockList,
    fetchList, fetchDetail, setCategory
  };
});

// stores/cart.js
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { useCouponStore } from './coupon';

export const useCartStore = defineStore('cart', () => {
  const items = ref([]);

  // 商品总数
  const totalCount = computed(() =>
    items.value.reduce((sum, item) => sum + item.quantity, 0)
  );

  // 商品原价小计
  const subtotal = computed(() =>
    items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
  );

  // 跨 store 协作：结合优惠券计算最终价格
  const finalTotal = computed(() => {
    const couponStore = useCouponStore();
    const discount = couponStore.calculateDiscount(subtotal.value);
    return Math.max(0, subtotal.value - discount);
  });

  // 已选中的商品（用于结算）
  const checkedItems = computed(() =>
    items.value.filter((item) => item.checked)
  );

  const isAllChecked = computed(() =>
    items.value.length > 0 && items.value.every((item) => item.checked)
  );

  // 添加商品（已存在则数量+1）
  function addToCart(product) {
    const existing = items.value.find((item) => item.id === product.id);
    if (existing) {
      if (existing.quantity < product.stock) {
        existing.quantity++;
      } else {
        throw new Error('库存不足');
      }
    } else {
      items.value.push({
        id: product.id,
        name: product.name,
        price: product.price,
        image: product.image,
        stock: product.stock,
        quantity: 1,
        checked: true
      });
    }
  }

  // 更新数量
  function updateQuantity(id, quantity) {
    const item = items.value.find((i) => i.id === id);
    if (!item) return;
    if (quantity <= 0) {
      removeFromCart(id);
    } else if (quantity <= item.stock) {
      item.quantity = quantity;
    }
  }

  function removeFromCart(id) {
    items.value = items.value.filter((item) => item.id !== id);
  }

  function toggleCheck(id) {
    const item = items.value.find((i) => i.id === id);
    if (item) item.checked = !item.checked;
  }

  function toggleCheckAll() {
    const target = !isAllChecked.value;
    items.value.forEach((item) => (item.checked = target));
  }

  function clearCart() {
    items.value = [];
  }

  return {
    items, totalCount, subtotal, finalTotal, checkedItems, isAllChecked,
    addToCart, updateQuantity, removeFromCart,
    toggleCheck, toggleCheckAll, clearCart
  };
}, {
  // 持久化购物车，刷新不丢
  persist: { key: 'shop-cart', paths: ['items'] }
});

// stores/coupon.js
import { defineStore } from 'pinia';
import { ref } from 'vue';

export const useCouponStore = defineStore('coupon', () => {
  const available = ref([]);      // 可用优惠券
  const selected = ref(null);     // 当前选中的优惠券

  // 根据金额计算优惠额（供 cart store 调用）
  function calculateDiscount(amount) {
    if (!selected.value) return 0;
    const { type, value, threshold } = selected.value;
    // 未达到使用门槛
    if (amount < threshold) return 0;
    if (type === 'fixed') return value;              // 满减
    if (type === 'percent') return amount * value;   // 折扣
    return 0;
  }

  function selectCoupon(coupon) {
    selected.value = coupon;
  }

  return { available, selected, calculateDiscount, selectCoupon };
});

// stores/order.js
import { defineStore } from 'pinia';
import { ref } from 'vue';
import { createOrder } from '@/api/order';
import { useCartStore } from './cart';
import { useCouponStore } from './coupon';
import { useUserStore } from './user';

export const useOrderStore = defineStore('order', () => {
  const submitting = ref(false);
  const orderList = ref([]);

  async function submitOrder(address) {
    const cartStore = useCartStore();
    const couponStore = useCouponStore();
    const userStore = useUserStore();

    if (!userStore.isLoggedIn) {
      throw new Error('请先登录');
    }
    if (cartStore.checkedItems.length === 0) {
      throw new Error('请选择要购买的商品');
    }

    submitting.value = true;
    try {
      const order = await createOrder({
        items: cartStore.checkedItems.map((i) => ({
          productId: i.id,
          quantity: i.quantity
        })),
        couponId: couponStore.selected?.id ?? null,
        totalAmount: cartStore.finalTotal,
        address
      });

      // 下单成功后移除已购买商品
      cartStore.checkedItems.forEach((item) => {
        cartStore.removeFromCart(item.id);
      });
      couponStore.selectCoupon(null);
      orderList.value.unshift(order);

      return order;
    } finally {
      submitting.value = false;
    }
  }

  return { submitting, orderList, submitOrder };
});

<script setup>
import { storeToRefs } from 'pinia';
import { useCartStore } from '@/stores/cart';
import { useOrderStore } from '@/stores/order';

const cartStore = useCartStore();
const orderStore = useOrderStore();

// 解构响应式数据用 storeToRefs，方法直接从 store 取
const { items, subtotal, finalTotal, isAllChecked, totalCount } = storeToRefs(cartStore);
const { submitting } = storeToRefs(orderStore);

async function handleCheckout() {
  try {
    const order = await orderStore.submitOrder({ city: '北京', detail: '...' });
    alert(`下单成功，订单号：${order.id}`);
  } catch (e) {
    alert(e.message);
  }
}
</script>

<template>
  <div class="cart">
    <div class="cart-header">
      <input type="checkbox" :checked="isAllChecked" @change="cartStore.toggleCheckAll" />
      全选（共 {{ totalCount }} 件）
    </div>

    <div v-for="item in items" :key="item.id" class="cart-item">
      <input type="checkbox" :checked="item.checked" @change="cartStore.toggleCheck(item.id)" />
      <img :src="item.image" :alt="item.name" />
      <span>{{ item.name }}</span>
      <span>￥{{ item.price }}</span>
      <div class="quantity">
        <button @click="cartStore.updateQuantity(item.id, item.quantity - 1)">-</button>
        <span>{{ item.quantity }}</span>
        <button @click="cartStore.updateQuantity(item.id, item.quantity + 1)">+</button>
      </div>
      <button @click="cartStore.removeFromCart(item.id)">删除</button>
    </div>

    <div class="cart-footer">
      <span>小计：￥{{ subtotal }}</span>
      <span>应付：￥{{ finalTotal }}</span>
      <button :disabled="submitting" @click="handleCheckout">
        {{ submitting ? '提交中...' : '去结算' }}
      </button>
    </div>
  </div>
</template>

import { defineStore } from 'pinia';
import { ref, shallowRef, markRaw } from 'vue';

export const useDataStore = defineStore('data', () => {
  // 大型只读数据用 shallowRef，避免深层响应式转换的性能开销
  const bigTableData = shallowRef([]);

  // 第三方实例（图表、地图）用 markRaw，跳过响应式代理
  let chartInstance = null;
  function setChart(instance) {
    chartInstance = markRaw(instance);
  }

  // 更新 shallowRef 需整体替换才触发更新
  function updateTable(newData) {
    bigTableData.value = newData; // 替换而非 push
  }

  return { bigTableData, updateTable, setChart };
});

export const useStatsStore = defineStore('stats', () => {
  const records = ref([]);

  // 昂贵的计算，getter 会缓存，依赖不变时不重复算
  const expensiveStats = computed(() => {
    console.log('重新计算统计...'); // 只在 records 变化时打印
    return records.value.reduce((acc, r) => {
      acc.total += r.value;
      acc.max = Math.max(acc.max, r.value);
      return acc;
    }, { total: 0, max: -Infinity });
  });

  return { records, expensiveStats };
});
// 组件多次读 store.expensiveStats 只计算一次

src/
├── stores/
│   ├── modules/
│   │   ├── user.ts          # 用户认证
│   │   ├── permission.ts    # 权限路由
│   │   ├── cart.ts          # 购物车
│   │   ├── product.ts       # 商品
│   │   └── settings.ts      # 应用设置
│   ├── plugins/
│   │   ├── persist.ts       # 持久化插件
│   │   └── logger.ts        # 日志插件
│   └── index.ts             # 创建 pinia、注册插件、统一导出
├── api/                     # 接口层
└── types/                   # 类型定义

// stores/index.ts
import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
import { loggerPlugin } from './plugins/logger';

const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);
pinia.use(loggerPlugin);

export default pinia;

// 统一导出所有 store，便于按需引入
export * from './modules/user';
export * from './modules/cart';
export * from './modules/product';

// stores/notification.js
import { defineStore } from 'pinia';
import { ref, watch } from 'vue';
import { useUserStore } from './user';
import { useCartStore } from './cart';

export const useNotificationStore = defineStore('notification', () => {
  const messages = ref([]);

  const userStore = useUserStore();
  const cartStore = useCartStore();

  // 监听购物车变化，自动提示
  watch(
    () => cartStore.totalCount,
    (newCount, oldCount) => {
      if (newCount > oldCount) {
        addMessage(`已加入购物车，当前 ${newCount} 件`);
      }
    }
  );

  // 监听登录状态
  watch(
    () => userStore.isLoggedIn,
    (loggedIn) => {
      addMessage(loggedIn ? '登录成功' : '已退出登录');
    }
  );

  function addMessage(text) {
    const id = Date.now();
    messages.value.push({ id, text });
    // 3 秒后自动移除
    setTimeout(() => {
      messages.value = messages.value.filter((m) => m.id !== id);
    }, 3000);
  }

  return { messages, addMessage };
});

import { defineStore, acceptHMRUpdate } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++;
    }
  }
});

// 开启 HMR：修改 store 时热更新，保留当前状态
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot));
}

export const useUserStore = defineStore('user', () => {
  const userInfo = ref(null);

  async function login(credentials) {
    // Devtools 会自动记录这个 action 的调用
    const res = await loginApi(credentials);
    userInfo.value = res.user;
    // 状态变更会出现在 timeline，可回放
  }

  return { userInfo, login };
});

// stores/plugins/logger.js
export function loggerPlugin({ store }) {
  // 只在开发环境启用
  if (!import.meta.env.DEV) return;

  store.$subscribe((mutation, state) => {
    console.group(`[${store.$id}] state 变更`);
    console.log('变更类型:', mutation.type);
    console.log('最新 state:', { ...state });
    console.groupEnd();
  });

  store.$onAction(({ name, args, after, onError }) => {
    console.log(`[${store.$id}] 调用 action: ${name}`, args);
    after((result) => console.log(`[${store.$id}] ${name} 完成`, result));
    onError((err) => console.error(`[${store.$id}] ${name} 出错`, err));
  });
}

// stores/auth.js
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { login as loginApi, refreshToken as refreshApi, getUserInfo } from '@/api/auth';

export const useAuthStore = defineStore('auth', () => {
  const accessToken = ref('');
  const refreshTokenValue = ref('');
  const userInfo = ref(null);
  const roles = ref([]);
  const permissions = ref([]);

  let refreshTimer = null;

  const isLoggedIn = computed(() => !!accessToken.value);
  const isAdmin = computed(() => roles.value.includes('admin'));

  async function login(credentials) {
    const res = await loginApi(credentials);
    accessToken.value = res.accessToken;
    refreshTokenValue.value = res.refreshToken;
    // 登录后拉取用户信息并启动刷新定时器
    await loadUserInfo();
    scheduleRefresh(res.expiresIn);
  }

  async function loadUserInfo() {
    const info = await getUserInfo();
    userInfo.value = info;
    roles.value = info.roles;
    permissions.value = info.permissions;
  }

  // 在 token 过期前自动刷新
  function scheduleRefresh(expiresIn) {
    clearTimeout(refreshTimer);
    // 提前 1 分钟刷新
    const delay = (expiresIn - 60) * 1000;
    refreshTimer = setTimeout(async () => {
      await doRefresh();
    }, delay);
  }

  async function doRefresh() {
    try {
      const res = await refreshApi(refreshTokenValue.value);
      accessToken.value = res.accessToken;
      scheduleRefresh(res.expiresIn);
    } catch {
      logout(); // 刷新失败则登出
    }
  }

  function hasPermission(perm) {
    return permissions.value.includes(perm);
  }

  function logout() {
    clearTimeout(refreshTimer);
    accessToken.value = '';
    refreshTokenValue.value = '';
    userInfo.value = null;
    roles.value = [];
    permissions.value = [];
  }

  return {
    accessToken, refreshTokenValue, userInfo, roles, permissions,
    isLoggedIn, isAdmin,
    login, loadUserInfo, doRefresh, hasPermission, logout
  };
}, {
  // 只持久化 token，用户信息每次重新拉取，保证最新
  persist: { key: 'auth', paths: ['accessToken', 'refreshTokenValue'] }
});

// main.js 或 App.vue setup
import { useAuthStore } from '@/stores/auth';

async function bootstrap() {
  const authStore = useAuthStore();
  // 持久化恢复了 token，但用户信息需要重新拉取
  if (authStore.accessToken) {
    try {
      await authStore.loadUserInfo();
    } catch {
      authStore.logout(); // token 已失效
    }
  }
}

router.beforeEach((to) => {
  const authStore = useAuthStore();

  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
    return { path: '/login', query: { redirect: to.fullPath } };
  }

  // 校验页面所需权限
  if (to.meta.permission && !authStore.hasPermission(to.meta.permission)) {
    return { path: '/403' };
  }

  return true;
});