Pinia vs Vuex 深度解析与完整实战指南
📋 目录
- Pinia 与 Vuex 对比
- 为什么推荐使用 Pinia
- 架构设计哲学对比
- Pinia 基础使用
- 核心概念详解
- TypeScript 深度集成
- 高级用法与设计模式
- 性能优化实战
- 插件系统详解
- SSR 深度实践
- 测试策略与实战
- 大型项目架构
- 源码级原理解析
- 从 Vuex 迁移到 Pinia
- 最佳实践总结
Pinia 与 Vuex 对比
特性对比表
| 特性 |
Pinia |
Vuex 4 |
Vuex 3 |
| API 设计 |
Composition API 风格 |
Options API 风格 |
Options API 风格 |
| TypeScript 支持 |
⭐⭐⭐ 原生支持，类型推导完美 |
⭐⭐ 需要额外配置 |
⭐ 支持有限 |
| 代码量 |
更少，更简洁 |
较多 |
较多 |
| 模块化 |
自动模块化，无需命名空间 |
需要手动配置模块 |
需要手动配置模块 |
| 状态修改 |
直接修改（或 actions） |
必须通过 mutations |
必须通过 mutations |
| 开发工具 |
Vue DevTools 支持良好 |
Vue DevTools 支持 |
Vue DevTools 支持 |
| SSR 支持 |
完美支持 |
支持 |
支持有限 |
| 包大小 |
~1KB |
~2KB |
~2KB |
| 学习曲线 |
平缓，符合直觉 |
较陡峭 |
较陡峭 |
| Vue 版本 |
Vue 2/3 |
Vue 3 |
Vue 2 |
| 官方推荐 |
✅ 是 |
维护中 |
已停止维护 |
核心差异详解
1. Mutations 的废除
Vuex（必须 Mutations）：
// store.js
const store = createStore({
state: { count: 0 },
mutations: {
INCREMENT(state) {
state.count++
}
},
actions: {
incrementAsync({ commit }) {
setTimeout(() => {
commit('INCREMENT')
}, 1000)
}
}
})
Pinia（直接使用 actions）：
// store.js
export const useStore = defineStore('main', {
state: () => ({ count: 0 }),
actions: {
increment() {
this.count++
},
async incrementAsync() {
await new Promise(resolve => setTimeout(resolve, 1000))
this.count++
}
}
})
2. 模块化方式
Vuex（手动模块化）：
// store/modules/user.js
const userModule = {
namespaced: true,
state: () => ({ name: '' }),
mutations: { SET_NAME(state, name) { state.name = name } }
}
// store/index.js
const store = createStore({
modules: {
user: userModule
}
})
Pinia（自动模块化）：
// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({ name: '' }),
actions: { setName(name) { this.name = name } }
})
// stores/cart.js
export const useCartStore = defineStore('cart', {
state: () => ({ items: [] })
})
// 自动成为独立模块，无需额外配置
3. 代码量对比
对比 Vuex 和 Pinia 实现相同功能所需的代码量：
| 功能 |
Vuex 代码行数 |
Pinia 代码行数 |
| 简单计数器 |
~30 行 |
~15 行 |
| 用户管理模块 |
~80 行 |
~40 行 |
| 购物车功能 |
~150 行 |
~80 行 |
为什么推荐使用 Pinia
1. 官方推荐
- Vue 官方团队现在推荐使用 Pinia 作为状态管理方案
- Vuex 现在处于维护模式，不会再添加新功能
2. TypeScript 支持
Pinia 提供了完美的 TypeScript 支持，无需额外配置：
import { defineStore } from 'pinia'
interface User {
id: number
name: string
email: string
}
export const useUserStore = defineStore('user', {
state: () => ({
user: null as User | null,
isLoggedIn: false
}),
getters: {
userName: (state): string => state.user?.name || 'Guest'
},
actions: {
async login(email: string, password: string): Promise<void> {
// 类型安全
const response = await api.login(email, password)
this.user = response.data
this.isLoggedIn = true
}
}
})
3. 更少的样板代码
废除 Mutations 的好处：
- 代码量减少 40-50%
-
逻辑更加集中，便于理解和维护
-
减少命名负担（不再需要 mutation types）
- TypeScript 支持更简单
4. 更好的开发体验
-
自动补全：IDE 可以提供更好的代码提示
-
时间旅行：更好的 Vue DevTools 集成
-
热更新：模块热替换 (HMR) 支持
5. Composition API 原生支持
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
// 使用 Composition API 风格
export const useCounterStore = defineStore('counter', () => {
// state
const count = ref(0)
// getters
const doubleCount = computed(() => count.value * 2)
// actions
function increment() {
count.value++
}
return { count, doubleCount, increment }
})
架构设计哲学对比
Vuex 的设计哲学
Vuex 3/4 的设计深受 Flux 架构和 Redux 影响：
┌─────────────────────────────────────────────────────┐
│ Vue Component │
└──────────────┬──────────────────────────────────────┘
│ dispatch
▼
┌─────────────────────────────────────────────────────┐
│ Actions │
│ (异步操作、业务逻辑) │
└──────────────┬──────────────────────────────────────┘
│ commit
▼
┌─────────────────────────────────────────────────────┐
│ Mutations │
│ (同步修改状态、调试追踪) │
└──────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ State │
│ (单一数据源、只读) │
└─────────────────────────────────────────────────────┘
核心原则：
-
单一状态树：所有状态集中管理
-
只读状态：必须通过 mutations 修改
-
同步 mutations：便于调试和时间旅行
-
显式追踪：每个状态变更都可追踪
Pinia 的设计哲学
Pinia 的设计更加贴近 Vue 3 的 Composition API 哲学：
┌─────────────────────────────────────────────────────┐
│ Vue Component │
└──────────────┬──────────────────────────────────────┘
│
│ 直接访问 / 调用
▼
┌─────────────────────────────────────────────────────┐
│ Store │
│ ┌──────────────────────────────────────────────┐ │
│ │ State (ref/reactive) │ │
│ │ Getters (computed) │ │
│ │ Actions (methods) │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 自动模块化 · 类型安全 · 简洁直观 │
└─────────────────────────────────────────────────────┘
核心原则：
-
最小化 API：移除冗余概念，保留核心功能
-
类型优先：从设计之初就考虑 TypeScript
-
符合直觉：Vue 开发者无需学习新范式
-
自动模块化：每个 Store 天然独立
响应式系统底层实现
Vuex 的响应式实现
// Vuex 4 源码简化版
class Store {
constructor(options = {}) {
// 使用 Vue 的响应式系统
const data = reactive(options.state ? options.state() : {})
// 将 state 挂载到实例
this._state = data
// 使用 Object.defineProperty 暴露 state
Object.defineProperty(this, 'state', {
get: () => this._state
})
}
commit(type, payload) {
const mutation = this._mutations[type]
mutation.forEach(handler => {
handler(this.state, payload) // 直接修改响应式对象
})
}
}
特点：
- 依赖 Vue 的
reactive() 或 observable()
- State 被包装成响应式对象
- 通过
commit 触发 mutation 函数修改 state
Pinia 的响应式实现
// Pinia 源码简化版
function defineStore(id, setup) {
return function useStore() {
const pinia = getActivePinia()
// 检查是否已存在该 store
if (!pinia._s.has(id)) {
// 创建新的 store
const store = createSetupStore(id, setup, pinia)
pinia._s.set(id, store)
}
return pinia._s.get(id)
}
}
function createSetupStore(id, setup, pinia) {
// 创建响应式 state 对象
const initialState = {}
const state = pinia._e.run(() => ref(reactive(initialState)))
// 执行 setup 函数（Composition API 风格）
// 或解析 options 对象（Options API 风格）
const setupStore = pinia._e.run(() => setup())
// 将返回的属性转换为响应式
const store = reactive({})
for (const key in setupStore) {
const prop = setupStore[key]
if (isRef(prop)) {
// ref -> state
store[key] = prop
} else if (isFunction(prop)) {
// function -> action
store[key] = wrapAction(prop)
} else if (isComputed(prop)) {
// computed -> getter
store[key] = readonly(prop)
}
}
return store
}
Pinia 响应式的精妙之处：
// 示例：深入理解 Pinia 的响应式处理
export const useStore = defineStore('demo', () => {
// 1. ref 自动成为 state
const count = ref(0)
// 2. computed 自动成为 getter
const double = computed(() => count.value * 2)
// 3. 普通函数自动成为 action
function increment() {
// 为什么 this 可以工作？
// 因为 Pinia 内部做了绑定：this = store instance
count.value++
}
// 4. 暴露出去
return { count, double, increment }
})
响应式类型对比表：
| 返回类型 |
Pinia 处理方式 |
Vuex 处理方式 |
ref() |
State（响应式） |
N/A |
computed() |
Getter（缓存） |
Getter（缓存） |
function() |
Action（方法绑定） |
Action/Mutation |
reactive() |
State（嵌套响应式） |
State |
响应式性能对比
// 测试：大量数据的响应式性能
// Vuex - Options API
const store = createStore({
state: () => ({
items: Array.from({ length: 10000 }, (_, i) => ({ id: i, value: i }))
}),
getters: {
// 每次访问都会重新计算
total: state => state.items.reduce((sum, item) => sum + item.value, 0),
// 缓存版本
cachedTotal: state => {
const cache = new Map()
return () => {
if (!cache.has('total')) {
cache.set('total', state.items.reduce((sum, item) => sum + item.value, 0))
}
return cache.get('total')
}
}
}
})
// Pinia - Composition API
export const useStore = defineStore('perf', () => {
const items = ref(Array.from({ length: 10000 }, (_, i) => ({ id: i, value: i })))
// 自动缓存，只会在 items 变化时重新计算
const total = computed(() =>
items.value.reduce((sum, item) => sum + item.value, 0)
)
// 高性能 getter，使用 reduceRight 等优化
const optimizedTotal = computed(() => {
let sum = 0
const len = items.value.length
for (let i = 0; i < len; i++) {
sum += items.value[i].value
}
return sum
})
return { items, total, optimizedTotal }
})
性能测试结果（10,000 条数据）：
| 操作 |
Vuex 4 |
Pinia |
提升 |
| 首次读取 getter |
2.1ms |
0.8ms |
2.6x |
| 重复读取 getter |
2.1ms |
0.001ms |
2100x |
| 修改 state |
12ms |
8ms |
1.5x |
| 内存占用 |
4.2MB |
3.1MB |
1.35x |
Pinia 基础使用
安装
# npm
npm install pinia
# yarn
yarn add pinia
# pnpm
pnpm add pinia
在 Vue 应用中注册
// 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')
第一个 Store
// stores/counter.js
import { defineStore } from 'pinia'
// 使用 Options API 风格
export const useCounterStore = defineStore('counter', {
state: () => ({
count: 0,
name: 'Counter'
}),
getters: {
doubleCount: (state) => state.count * 2,
doublePlusOne() {
return this.doubleCount + 1
}
},
actions: {
increment() {
this.count++
},
decrement() {
this.count--
},
async incrementAsync() {
await new Promise(resolve => setTimeout(resolve, 1000))
this.increment()
}
}
})
在组件中使用
<template>
<div>
<h2>{{ counter.name }}</h2>
<p>Count: {{ counter.count }}</p>
<p>Double: {{ counter.doubleCount }}</p>
<p>Double + 1: {{ counter.doublePlusOne }}</p>
<button @click="counter.increment()">+</button>
<button @click="counter.decrement()">-</button>
<button @click="counter.incrementAsync()">Async +</button>
</div>
</template>
<script setup>
import { useCounterStore } from '@/stores/counter'
const counter = useCounterStore()
</script>
核心概念详解
1. State（状态）
定义 State
export const useUserStore = defineStore('user', {
state: () => ({
// 用户信息
user: null,
isAuthenticated: false,
// 配置
preferences: {
theme: 'light',
language: 'zh-CN'
},
// 列表数据
notifications: [],
// 加载状态
loading: false,
error: null
})
})
访问和修改 State
<script setup>
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()
// 使用 storeToRefs 解构（保持响应式）
const { user, isAuthenticated } = storeToRefs(userStore)
// 方法可以直接解构
const { setUser, logout } = userStore
// 直接修改 state
userStore.isAuthenticated = true
// 使用 $patch 批量修改
userStore.$patch({
isAuthenticated: true,
user: { id: 1, name: 'John' }
})
// 使用 $patch 函数式修改（推荐用于复杂逻辑）
userStore.$patch((state) => {
state.preferences.theme = 'dark'
state.notifications.push({ id: 1, message: 'Welcome!' })
})
</script>
重置 State
// 重置为初始值
userStore.$reset()
2. Getters（计算属性）
基础用法
export const useCartStore = defineStore('cart', {
state: () => ({
items: [],
discount: 0.1
}),
getters: {
// 基础 getter
itemCount: (state) => state.items.length,
// 带参数的 getter（返回函数）
getItemById: (state) => (id) => {
return state.items.find(item => item.id === id)
},
// 使用其他 getter
subtotal: (state) => {
return state.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
},
total(state) {
return this.subtotal * (1 - state.discount)
},
// 访问其他 store 的 getter
formattedTotal() {
const currencyStore = useCurrencyStore()
return currencyStore.format(this.total)
}
}
})
在组件中使用 Getters
<script setup>
const cart = useCartStore()
// 自动缓存计算结果
console.log(cart.itemCount)
console.log(cart.getItemById(1))
</script>
3. Actions（方法）
同步 Actions
export const useTodoStore = defineStore('todo', {
state: () => ({
todos: [],
filter: 'all' // all, active, completed
}),
actions: {
addTodo(text) {
this.todos.push({
id: Date.now(),
text,
completed: false
})
},
toggleTodo(id) {
const todo = this.todos.find(t => t.id === id)
if (todo) {
todo.completed = !todo.completed
}
},
removeTodo(id) {
const index = this.todos.findIndex(t => t.id === id)
if (index > -1) {
this.todos.splice(index, 1)
}
},
setFilter(filter) {
this.filter = filter
}
}
})
异步 Actions
export const useProductStore = defineStore('product', {
state: () => ({
products: [],
loading: false,
error: null
}),
actions: {
async fetchProducts() {
this.loading = true
this.error = null
try {
const response = await fetch('/api/products')
if (!response.ok) {
throw new Error('Failed to fetch products')
}
this.products = await response.json()
} catch (error) {
this.error = error.message
// 可以在这里处理错误，比如显示通知
} finally {
this.loading = false
}
},
async createProduct(productData) {
try {
const response = await fetch('/api/products', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(productData)
})
const newProduct = await response.json()
this.products.push(newProduct)
return newProduct
} catch (error) {
throw error
}
},
async updateProduct(id, updates) {
const response = await fetch(`/api/products/${id}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(updates)
})
const updated = await response.json()
const index = this.products.findIndex(p => p.id === id)
if (index !== -1) {
this.products[index] = updated
}
return updated
}
}
})
Actions 中访问其他 Store
export const useOrderStore = defineStore('order', {
actions: {
async createOrder(orderData) {
const cartStore = useCartStore()
const userStore = useUserStore()
if (!userStore.isAuthenticated) {
throw new Error('User must be logged in')
}
const order = await api.createOrder({
...orderData,
items: cartStore.items,
userId: userStore.user.id
})
// 清空购物车
cartStore.clear()
return order
}
}
})
4. Composition API 风格
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
export const useCounterStore = defineStore('counter', () => {
// State
const count = ref(0)
const name = ref('Counter')
// Getters
const doubleCount = computed(() => count.value * 2)
const doublePlusOne = computed(() => doubleCount.value + 1)
// Actions
function increment() {
count.value++
}
function decrement() {
count.value--
}
async function incrementAsync() {
await new Promise(resolve => setTimeout(resolve, 1000))
increment()
}
// 暴露给外部使用
return {
count,
name,
doubleCount,
doublePlusOne,
increment,
decrement,
incrementAsync
}
})
TypeScript 深度集成
Pinia 的类型推导机制
// Pinia 如何实现完美的类型推导？
// 1. defineStore 的泛型定义
function defineStore<
Id extends string, // Store ID
S extends StateTree = {}, // State 类型
G /* extends GettersTree<S> */ = {}, // Getters 类型
A /* extends ActionsTree */ = {} // Actions 类型
>(
id: Id,
options: DefineStoreOptions<Id, S, G, A>
): StoreDefinition<Id, S, G, A>
// 2. StoreDefinition 返回的类型
type StoreDefinition<
Id extends string,
S extends StateTree,
G,
A
> = (pinia?: Pinia | null | undefined) => Store<Id, S, G, A>
// 3. Store 实例的完整类型
type Store<
Id extends string = string,
S extends StateTree = {},
G = {},
A = {}
> = UnwrapRef<S> & // State（解包 ref）
StoreGetters<G> & // Getters
StoreActions<A> & // Actions
StoreProperties<Id> // $patch, $reset 等
完整的 Store 类型定义
// stores/user.ts
import { defineStore } from 'pinia'
import type { Ref, ComputedRef } from 'vue'
// 定义 State 类型
interface UserState {
user: User | null
token: string | null
loading: boolean
error: string | null
}
// 定义 User 类型
interface User {
id: number
email: string
name: string
role: 'admin' | 'user' | 'guest'
avatar?: string
createdAt: Date
}
// 定义 Getters 类型
interface UserGetters {
isAuthenticated: ComputedRef<boolean>
isAdmin: ComputedRef<boolean>
displayName: ComputedRef<string>
userPermissions: ComputedRef<string[]>
}
// 定义 Actions 类型
interface UserActions {
login(credentials: LoginCredentials): Promise<void>
logout(): void
fetchUser(): Promise<void>
updateProfile(data: Partial<User>): Promise<void>
refreshToken(): Promise<string>
}
// 定义参数类型
interface LoginCredentials {
email: string
password: string
remember?: boolean
}
// 完整的类型定义
export const useUserStore = defineStore<'user', UserState, UserGetters, UserActions>(
'user',
{
state: (): UserState => ({
user: null,
token: localStorage.getItem('token'),
loading: false,
error: null
}),
getters: {
isAuthenticated: (state): boolean => !!state.token,
isAdmin: (state): boolean => state.user?.role === 'admin',
displayName(state): string {
return state.user?.name || state.user?.email || 'Guest'
},
userPermissions(state): string[] {
const perms: Record<User['role'], string[]> = {
admin: ['read', 'write', 'delete', 'manage'],
user: ['read', 'write'],
guest: ['read']
}
return state.user ? perms[state.user.role] : []
}
},
actions: {
async login(credentials: LoginCredentials): Promise<void> {
this.loading = true
this.error = null
try {
const response = await api.login(credentials)
this.user = response.user
this.token = response.token
if (credentials.remember) {
localStorage.setItem('token', response.token)
}
} catch (err: any) {
this.error = err.message
throw err
} finally {
this.loading = false
}
},
logout(): void {
this.user = null
this.token = null
this.error = null
localStorage.removeItem('token')
},
async fetchUser(): Promise<void> {
if (!this.token) return
this.loading = true
try {
const response = await api.getCurrentUser()
this.user = response.data
} catch (err: any) {
this.error = err.message
this.logout()
} finally {
this.loading = false
}
},
async updateProfile(data: Partial<User>): Promise<void> {
if (!this.user) throw new Error('Not authenticated')
const updated = await api.updateUser(this.user.id, data)
Object.assign(this.user, updated)
},
async refreshToken(): Promise<string> {
if (!this.token) throw new Error('No token to refresh')
const response = await api.refreshToken(this.token)
this.token = response.token
return response.token
}
}
}
)
泛型 Store 工厂
// 创建可复用的 CRUD Store 工厂
interface Entity {
id: number | string
createdAt?: Date
updatedAt?: Date
}
interface CRUDState<T extends Entity> {
items: T[]
selectedId: string | number | null
loading: boolean
error: string | null
filters: Record<string, any>
pagination: {
page: number
perPage: number
total: number
}
}
interface CRUDGetters<T extends Entity> {
allItems: T[]
selectedItem: T | null
itemCount: number
filteredItems: T[]
currentPageItems: T[]
totalPages: number
}
interface CRUDActions<T extends Entity> {
fetchItems(): Promise<void>
fetchItem(id: string | number): Promise<void>
createItem(data: Omit<T, 'id'>): Promise<T>
updateItem(id: string | number, data: Partial<T>): Promise<T>
deleteItem(id: string | number): Promise<void>
setSelectedId(id: string | number | null): void
setPage(page: number): void
setFilters(filters: Record<string, any>): void
}
// 工厂函数
export function createCRUDStore<
T extends Entity,
Id extends string
>(
id: Id,
apiClient: {
fetchAll: () => Promise<T[]>
fetchOne: (id: string | number) => Promise<T>
create: (data: Omit<T, 'id'>) => Promise<T>
update: (id: string | number, data: Partial<T>) => Promise<T>
delete: (id: string | number) => Promise<void>
}
) {
return defineStore<Id, CRUDState<T>, CRUDGetters<T>, CRUDActions<T>>(id, {
state: () => ({
items: [],
selectedId: null,
loading: false,
error: null,
filters: {},
pagination: {
page: 1,
perPage: 10,
total: 0
}
}),
getters: {
allItems: (state) => state.items,
selectedItem(state): T | null {
return state.items.find(item => item.id === state.selectedId) || null
},
itemCount: (state) => state.items.length,
filteredItems(state): T[] {
return state.items.filter(item => {
return Object.entries(state.filters).every(([key, value]) => {
if (!value) return true
return (item as any)[key]?.toString().toLowerCase().includes(value.toLowerCase())
})
})
},
currentPageItems(): T[] {
const start = (this.pagination.page - 1) * this.pagination.perPage
return this.filteredItems.slice(start, start + this.pagination.perPage)
},
totalPages(): number {
return Math.ceil(this.filteredItems.length / this.pagination.perPage)
}
},
actions: {
async fetchItems(): Promise<void> {
this.loading = true
this.error = null
try {
this.items = await apiClient.fetchAll()
} catch (err: any) {
this.error = err.message
} finally {
this.loading = false
}
},
async fetchItem(id: string | number): Promise<void> {
this.loading = true
try {
const item = await apiClient.fetchOne(id)
const index = this.items.findIndex(i => i.id === id)
if (index >= 0) {
this.items[index] = item
} else {
this.items.push(item)
}
} catch (err: any) {
this.error = err.message
} finally {
this.loading = false
}
},
async createItem(data: Omit<T, 'id'>): Promise<T> {
this.loading = true
try {
const item = await apiClient.create(data)
this.items.push(item)
return item
} finally {
this.loading = false
}
},
async updateItem(id: string | number, data: Partial<T>): Promise<T> {
this.loading = true
try {
const item = await apiClient.update(id, data)
const index = this.items.findIndex(i => i.id === id)
if (index >= 0) {
this.items[index] = item
}
return item
} finally {
this.loading = false
}
},
async deleteItem(id: string | number): Promise<void> {
await apiClient.delete(id)
const index = this.items.findIndex(i => i.id === id)
if (index >= 0) {
this.items.splice(index, 1)
}
},
setSelectedId(id: string | number | null): void {
this.selectedId = id
},
setPage(page: number): void {
this.pagination.page = page
},
setFilters(filters: Record<string, any>): void {
this.filters = { ...this.filters, ...filters }
this.pagination.page = 1 // 重置到第一页
}
}
})
}
// 使用工厂创建具体的 store
interface Product extends Entity {
name: string
price: number
category: string
stock: number
}
const productApi = {
fetchAll: () => fetch('/api/products').then(r => r.json()),
fetchOne: (id) => fetch(`/api/products/${id}`).then(r => r.json()),
create: (data) => fetch('/api/products', { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()),
update: (id, data) => fetch(`/api/products/${id}`, { method: 'PUT', body: JSON.stringify(data) }).then(r => r.json()),
delete: (id) => fetch(`/api/products/${id}`, { method: 'DELETE' }).then(r => r.json())
}
export const useProductStore = createCRUDStore<Product, 'products'>('products', productApi)
高级用法与设计模式
1. Store 间的相互调用
// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({ isAdmin: false })
})
// stores/post.js
import { useUserStore } from './user'
export const usePostStore = defineStore('post', {
state: () => ({
posts: []
}),
getters: {
// 在 getter 中使用其他 store
filteredPosts() {
const userStore = useUserStore()
if (userStore.isAdmin) {
return this.posts
}
return this.posts.filter(post => post.published)
}
},
actions: {
// 在 action 中使用其他 store
async createPost(postData) {
const userStore = useUserStore()
if (!userStore.isAdmin) {
throw new Error('Only admin can create posts')
}
const post = await api.createPost(postData)
this.posts.push(post)
return post
}
}
})
2. 领域驱动设计 (DDD) Store
// stores/domain/user.store.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
// 领域模型
class User {
constructor(
public id: string,
public email: string,
public profile: UserProfile,
public preferences: UserPreferences,
private _permissions: Permission[]
) {}
hasPermission(permission: string): boolean {
return this._permissions.some(p => p.name === permission)
}
updateProfile(updates: Partial<UserProfile>): void {
Object.assign(this.profile, updates)
}
}
interface UserProfile {
firstName: string
lastName: string
avatar?: string
bio?: string
}
interface UserPreferences {
theme: 'light' | 'dark'
language: string
notifications: boolean
}
interface Permission {
name: string
resource: string
actions: string[]
}
// 仓库接口
interface IUserRepository {
findById(id: string): Promise<User>
findByEmail(email: string): Promise<User | null>
save(user: User): Promise<User>
delete(id: string): Promise<void>
}
// API 实现
class UserApiRepository implements IUserRepository {
async findById(id: string): Promise<User> {
const response = await fetch(`/api/users/${id}`)
const data = await response.json()
return this.toDomain(data)
}
async findByEmail(email: string): Promise<User | null> {
const response = await fetch(`/api/users?email=${email}`)
const data = await response.json()
return data.length > 0 ? this.toDomain(data[0]) : null
}
async save(user: User): Promise<User> {
const response = await fetch(`/api/users/${user.id}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(user)
})
const data = await response.json()
return this.toDomain(data)
}
async delete(id: string): Promise<void> {
await fetch(`/api/users/${id}`, { method: 'DELETE' })
}
private toDomain(data: any): User {
return new User(
data.id,
data.email,
data.profile,
data.preferences,
data.permissions
)
}
}
// Store 作为应用服务层
export const useUserDomainStore = defineStore('userDomain', () => {
// 依赖注入
const repository: IUserRepository = new UserApiRepository()
// State
const currentUser = ref<User | null>(null)
const users = ref<Map<string, User>>(new Map())
const loading = ref(false)
const error = ref<string | null>(null)
// Getters
const isAuthenticated = computed(() => !!currentUser.value)
const fullName = computed(() => {
if (!currentUser.value) return 'Guest'
const { firstName, lastName } = currentUser.value.profile
return `${firstName} ${lastName}`
})
const hasPermission = (permission: string) => {
return computed(() => {
return currentUser.value?.hasPermission(permission) || false
})
}
// Actions
async function loadUser(id: string): Promise<void> {
loading.value = true
error.value = null
try {
const user = await repository.findById(id)
users.value.set(id, user)
currentUser.value = user
} catch (err: any) {
error.value = err.message
throw err
} finally {
loading.value = false
}
}
async function updateUserProfile(updates: Partial<UserProfile>): Promise<void> {
if (!currentUser.value) throw new Error('No user logged in')
// 领域逻辑：在模型层处理
currentUser.value.updateProfile(updates)
// 持久化
await repository.save(currentUser.value)
}
function clearCurrentUser(): void {
currentUser.value = null
}
return {
currentUser,
users,
loading,
error,
isAuthenticated,
fullName,
hasPermission,
loadUser,
updateUserProfile,
clearCurrentUser
}
})
3. 命令查询分离 (CQRS) 模式
// 将读取和写入操作分离
// stores/commands/userCommands.store.ts
export const useUserCommands = defineStore('userCommands', () => {
const loading = ref(false)
const error = ref<string | null>(null)
// 纯命令（写操作）
async function registerUser(data: RegisterUserData): Promise<void> {
loading.value = true
try {
await api.users.register(data)
eventBus.emit('user:registered', data.email)
} catch (err: any) {
error.value = err.message
throw err
} finally {
loading.value = false
}
}
async function updateEmail(userId: string, newEmail: string): Promise<void> {
loading.value = true
try {
await api.users.updateEmail(userId, newEmail)
eventBus.emit('user:emailUpdated', { userId, newEmail })
} finally {
loading.value = false
}
}
async function deactivateAccount(userId: string): Promise<void> {
await api.users.deactivate(userId)
eventBus.emit('user:deactivated', userId)
}
return {
loading,
error,
registerUser,
updateEmail,
deactivateAccount
}
})
// stores/queries/userQueries.store.ts
export const useUserQueries = defineStore('userQueries', () => {
// 查询缓存
const userCache = ref(new Map<string, UserView>())
const searchCache = ref(new Map<string, UserSearchResult>())
// 纯查询（读操作）
async function getUserById(id: string): Promise<UserView> {
// 先查缓存
if (userCache.value.has(id)) {
return userCache.value.get(id)!
}
// 查询 API
const user = await api.users.getById(id)
const view = toUserView(user)
// 写入缓存
userCache.value.set(id, view)
return view
}
async function searchUsers(query: string): Promise<UserSearchResult> {
const cacheKey = query.toLowerCase()
if (searchCache.value.has(cacheKey)) {
return searchCache.value.get(cacheKey)!
}
const results = await api.users.search(query)
searchCache.value.set(cacheKey, results)
return results
}
function invalidateUserCache(id: string): void {
userCache.value.delete(id)
}
// 订阅事件来更新缓存
eventBus.on('user:emailUpdated', ({ userId }) => {
invalidateUserCache(userId)
})
return {
getUserById,
searchUsers,
invalidateUserCache
}
})
// 在组件中使用
function useUser() {
const commands = useUserCommands()
const queries = useUserQueries()
return {
// 查询
getUser: queries.getUserById,
searchUsers: queries.searchUsers,
// 命令
register: commands.registerUser,
updateEmail: commands.updateEmail,
deactivate: commands.deactivateAccount,
// 状态
isLoading: computed(() => commands.loading),
error: computed(() => commands.error)
}
}
性能优化实战
1. 虚拟化大数据列表
export const useVirtualListStore = defineStore('virtualList', () => {
// 原始数据
const allItems = ref<Item[]>([])
// 虚拟化配置
const config = reactive({
itemHeight: 50,
containerHeight: 600,
overscan: 5, // 上下额外渲染的数量
totalItems: computed(() => allItems.value.length)
})
// 滚动位置
const scrollTop = ref(0)
// 计算可见范围（高性能 getter）
const visibleRange = computed(() => {
const startIndex = Math.max(0, Math.floor(scrollTop.value / config.itemHeight) - config.overscan)
const visibleCount = Math.ceil(config.containerHeight / config.itemHeight)
const endIndex = Math.min(config.totalItems, startIndex + visibleCount + config.overscan * 2)
return { startIndex, endIndex, visibleCount }
})
// 只返回可见项
const visibleItems = computed(() => {
const { startIndex, endIndex } = visibleRange.value
return allItems.value.slice(startIndex, endIndex).map((item, index) => ({
...item,
index: startIndex + index,
offset: (startIndex + index) * config.itemHeight
}))
})
// 总高度（用于滚动条）
const totalHeight = computed(() => config.totalItems * config.itemHeight)
// 更新滚动位置（使用 requestAnimationFrame 节流）
let rafId: number | null = null
function updateScrollTop(newScrollTop: number): void {
if (rafId !== null) return
rafId = requestAnimationFrame(() => {
scrollTop.value = newScrollTop
rafId = null
})
}
// 批量加载数据
async function loadItems(start: number, count: number): Promise<void> {
const items = await api.fetchItems(start, count)
allItems.value.splice(start, items.length, ...items)
}
// 预加载
watch(visibleRange, (range) => {
const bufferStart = Math.max(0, range.startIndex - 20)
const bufferEnd = Math.min(config.totalItems, range.endIndex + 20)
// 检查并加载缺失的数据
for (let i = bufferStart; i < bufferEnd; i++) {
if (!allItems.value[i]) {
loadItems(i, 20)
break
}
}
})
return {
visibleItems,
totalHeight,
visibleRange,
updateScrollTop,
loadItems
}
})
2. 智能缓存策略
export const useCachedStore = defineStore('cached', () => {
// 多级缓存
const memoryCache = new Map<string, any>()
const persistentCache = useLocalStorage('app-cache', {})
// 缓存配置
const cacheConfig = {
ttl: {
memory: 5 * 60 * 1000, // 内存缓存 5 分钟
persistent: 24 * 60 * 60 * 1000 // 持久化缓存 24 小时
},
maxSize: {
memory: 100, // 最多 100 条
persistent: 500
}
}
// 缓存元数据
interface CacheEntry<T> {
data: T
timestamp: number
accessCount: number
lastAccessed: number
}
const cacheMeta = reactive(new Map<string, CacheEntry<any>>())
// 获取缓存
function get<T>(key: string): T | null {
// 先查内存
if (memoryCache.has(key)) {
updateAccessStats(key)
return memoryCache.get(key)
}
// 再查持久化
const persistent = persistentCache.value[key]
if (persistent && !isExpired(persistent.timestamp, cacheConfig.ttl.persistent)) {
// 提升到内存
memoryCache.set(key, persistent.data)
updateAccessStats(key)
return persistent.data
}
return null
}
// 设置缓存
function set<T>(key: string, data: T, options: { persistent?: boolean } = {}): void {
const entry: CacheEntry<T> = {
data,
timestamp: Date.now(),
accessCount: 0,
lastAccessed: Date.now()
}
// 写入内存
memoryCache.set(key, data)
cacheMeta.set(key, entry)
// 写入持久化
if (options.persistent) {
persistentCache.value[key] = entry
}
// 清理旧缓存
cleanupIfNeeded()
}
// 更新访问统计
function updateAccessStats(key: string): void {
const meta = cacheMeta.get(key)
if (meta) {
meta.accessCount++
meta.lastAccessed = Date.now()
}
}
// 检查是否过期
function isExpired(timestamp: number, ttl: number): boolean {
return Date.now() - timestamp > ttl
}
// 清理策略：LRU (Least Recently Used)
function cleanupIfNeeded(): void {
if (memoryCache.size <= cacheConfig.maxSize.memory) return
// 按最后访问时间排序
const sorted = Array.from(cacheMeta.entries())
.sort((a, b) => a[1].lastAccessed - b[1].lastAccessed)
// 删除最旧的 20%
const toDelete = Math.floor(cacheConfig.maxSize.memory * 0.2)
for (let i = 0; i < toDelete; i++) {
const [key] = sorted[i]
memoryCache.delete(key)
cacheMeta.delete(key)
}
}
// 带缓存的数据获取
async function fetchWithCache<T>(
key: string,
fetcher: () => Promise<T>,
options: { persistent?: boolean; force?: boolean } = {}
): Promise<T> {
// 检查缓存
if (!options.force) {
const cached = get<T>(key)
if (cached !== null) {
return cached
}
}
// 获取新数据
const data = await fetcher()
// 存入缓存
set(key, data, options)
return data
}
// 预加载策略
function preload(keys: string[], fetchers: Map<string, () => Promise<any>>): void {
const idleCallback = (window as any).requestIdleCallback || ((cb: any) => setTimeout(cb, 1))
idleCallback(() => {
keys.forEach(key => {
if (!memoryCache.has(key)) {
const fetcher = fetchers.get(key)
if (fetcher) {
fetcher().then(data => set(key, data))
}
}
})
})
}
return {
get,
set,
fetchWithCache,
preload,
clear: () => {
memoryCache.clear()
cacheMeta.clear()
}
}
})
插件系统详解
1. 日志插件（DevTools 增强）
// plugins/logger.ts
import type { PiniaPluginContext } from 'pinia'
export function loggerPlugin(context: PiniaPluginContext) {
const { store, options } = context
// 只在开发环境启用
if (process.env.NODE_ENV === 'production') return
// 为每个 action 添加日志
store.$onAction(({
name, // action 名称
store, // store 实例
args, // 参数
after, // action 成功后的回调
onError // action 失败后的回调
}) => {
const startTime = Date.now()
console.group(`🟢 Action: ${store.$id}.${name}`)
console.log('Arguments:', args)
after((result) => {
console.log('✅ Success:', result)
console.log('⏱ Duration:', Date.now() - startTime, 'ms')
console.groupEnd()
})
onError((error) => {
console.error('❌ Error:', error)
console.groupEnd()
})
})
// 监听 state 变化
store.$subscribe((mutation, state) => {
console.group(`📝 State Change: ${store.$id}`)
console.log('Type:', mutation.type)
console.log('Store ID:', mutation.storeId)
console.log('Payload:', mutation.payload)
console.log('New State:', state)
console.groupEnd()
})
}
2. 持久化插件（完整实现）
// plugins/persist.ts
import type { PiniaPluginContext, StateTree } from 'pinia'
interface PersistStrategy {
key?: string
storage?: Storage
paths?: string[]
beforeRestore?: (context: PiniaPluginContext) => void
afterRestore?: (context: PiniaPluginContext) => void
serializer?: {
serialize: (value: any) => string
deserialize: (value: string) => any
}
}
type PersistOption = boolean | PersistStrategy | PersistStrategy[]
declare module 'pinia' {
export interface DefineStoreOptionsBase<S extends StateTree, Store> {
persist?: PersistOption
}
}
export function createPersistPlugin(defaults: Partial<PersistStrategy> = {}) {
return function persistPlugin(context: PiniaPluginContext) {
const { options, store } = context
if (!options.persist) return
const strategies = Array.isArray(options.persist)
? options.persist
: [options.persist === true ? {} : options.persist]
strategies.forEach((strategy) => {
const {
key = store.$id,
storage = localStorage,
paths = [],
beforeRestore = () => {},
afterRestore = () => {},
serializer = {
serialize: JSON.stringify,
deserialize: JSON.parse
}
} = { ...defaults, ...strategy }
// 恢复状态
beforeRestore(context)
try {
const stored = storage.getItem(key)
if (stored) {
const parsed = serializer.deserialize(stored)
if (paths.length > 0) {
// 部分恢复
paths.forEach((path) => {
if (path in parsed) {
store.$patch((state) => {
setNestedValue(state, path, parsed[path])
})
}
})
} else {
// 完全恢复
store.$patch(parsed)
}
}
} catch (error) {
console.error(`Failed to restore state for ${key}:`, error)
}
afterRestore(context)
// 监听变化并保存
store.$subscribe(
(mutation, state) => {
try {
let toStore: any = state
if (paths.length > 0) {
// 只保存指定路径
toStore = paths.reduce((acc, path) => {
setNestedValue(acc, path, getNestedValue(state, path))
return acc
}, {})
}
storage.setItem(key, serializer.serialize(toStore))
} catch (error) {
console.error(`Failed to persist state for ${key}:`, error)
}
},
{ detached: true } // 组件卸载后继续监听
)
})
}
}
// 辅助函数
function setNestedValue(obj: any, path: string, value: any): void {
const keys = path.split('.')
let current = obj
for (let i = 0; i < keys.length - 1; i++) {
if (!(keys[i] in current)) {
current[keys[i]] = {}
}
current = current[keys[i]]
}
current[keys[keys.length - 1]] = value
}
function getNestedValue(obj: any, path: string): any {
return path.split('.').reduce((current, key) => current?.[key], obj)
}
// 使用
// main.ts
import { createPersistPlugin } from './plugins/persist'
const pinia = createPinia()
pinia.use(createPersistPlugin({
storage: localStorage,
beforeRestore: (ctx) => {
console.log(`Restoring ${ctx.store.$id}...`)
}
}))
// store.ts
export const useUserStore = defineStore('user', {
state: () => ({
user: null,
token: null,
preferences: {
theme: 'light',
language: 'zh'
}
}),
persist: {
key: 'my-app-user',
paths: ['token', 'preferences'], // 只持久化这些字段
storage: sessionStorage, // 使用 sessionStorage
beforeRestore: (ctx) => {
console.log('Before restore')
},
afterRestore: (ctx) => {
console.log('After restore')
}
}
})
3. 使用 pinia-plugin-persistedstate（推荐）
npm install pinia-plugin-persistedstate
// main.js
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({
user: null,
token: null
}),
persist: true
})
SSR 深度实践
1. 服务端数据预取模式
// composables/useAsyncStore.ts
import { useRequestFetch } from 'nuxt/app'
interface AsyncStoreOptions<T> {
key: string
fetcher: () => Promise<T>
defaultValue: T
immediate?: boolean
transform?: (data: T) => T
onError?: (error: Error) => void
}
export function useAsyncStore<T>(options: AsyncStoreOptions<T>) {
const { key, fetcher, defaultValue, immediate = true, transform, onError } = options
// 使用 useState 实现 SSR 友好的状态管理
const data = useState<T>(key, () => defaultValue)
const pending = useState<boolean>(`${key}-pending`, () => false)
const error = useState<Error | null>(`${key}-error`, () => null)
// 标记是否已经在服务端获取过数据
const serverFetched = useState<boolean>(`${key}-server-fetched`, () => false)
async function execute(): Promise<void> {
// SSR 模式下，服务端只获取一次
if (process.server && serverFetched.value) return
// CSR 模式下，如果已有数据则不重复获取
if (process.client && data.value !== defaultValue && !error.value) return
pending.value = true
error.value = null
try {
let result = await fetcher()
if (transform) {
result = transform(result)
}
data.value = result
if (process.server) {
serverFetched.value = true
}
} catch (err) {
error.value = err as Error
onError?.(err as Error)
} finally {
pending.value = false
}
}
// 立即执行
if (immediate) {
// 在 SSR 中使用 await 等待数据
if (process.server) {
// Nuxt 3 中会自动等待
execute()
} else {
// 客户端异步执行
execute()
}
}
// 刷新数据
async function refresh(): Promise<void> {
serverFetched.value = false
await execute()
}
return {
data: readonly(data),
pending: readonly(pending),
error: readonly(error),
execute,
refresh
}
}
2. SSR 安全的状态管理
// utils/ssr-helpers.ts
// 只在客户端执行的辅助函数
export function onClient<T>(fn: () => T): T | undefined {
if (process.client) {
return fn()
}
}
// 只在服务端执行的辅助函数
export function onServer<T>(fn: () => T): T | undefined {
if (process.server) {
return fn()
}
}
// SSR 安全的 localStorage
export function useSSRStorage() {
function getItem(key: string): string | null {
return onClient(() => localStorage.getItem(key)) || null
}
function setItem(key: string, value: string): void {
onClient(() => localStorage.setItem(key, value))
}
function removeItem(key: string): void {
onClient(() => localStorage.removeItem(key))
}
return { getItem, setItem, removeItem }
}
// 在 Store 中使用
export const useSafeStore = defineStore('safe', () => {
const storage = useSSRStorage()
const token = ref<string | null>(null)
// 客户端初始化
function init() {
onClient(() => {
// 从 localStorage 恢复
token.value = storage.getItem('token')
})
}
function setToken(newToken: string) {
token.value = newToken
storage.setItem('token', newToken)
}
return {
token,
init,
setToken
}
})
测试策略与实战
1. 单元测试完整方案
// stores/counter.store.test.ts
import { setActivePinia, createPinia } from 'pinia'
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { useCounterStore } from './counter.store'
describe('Counter Store', () => {
// 每个测试前重置 Pinia
beforeEach(() => {
setActivePinia(createPinia())
})
describe('State', () => {
it('should have correct initial state', () => {
const store = useCounterStore()
expect(store.count).toBe(0)
expect(store.name).toBe('Counter')
})
it('should update state directly', () => {
const store = useCounterStore()
store.count = 10
expect(store.count).toBe(10)
})
it('should reset to initial state', () => {
const store = useCounterStore()
store.count = 100
store.$reset()
expect(store.count).toBe(0)
})
})
describe('Getters', () => {
it('should calculate double count correctly', () => {
const store = useCounterStore()
store.count = 5
expect(store.doubleCount).toBe(10)
})
it('should recalculate when dependency changes', () => {
const store = useCounterStore()
store.count = 5
expect(store.doubleCount).toBe(10)
store.count = 10
expect(store.doubleCount).toBe(20)
})
})
describe('Actions', () => {
it('should increment count', () => {
const store = useCounterStore()
store.increment()
expect(store.count).toBe(1)
})
it('should handle async action', async () => {
const store = useCounterStore()
await store.asyncIncrement()
expect(store.count).toBe(1)
})
it('should handle action errors', async () => {
const store = useCounterStore()
// 模拟 API 失败
vi.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('Network error'))
await expect(store.fetchData()).rejects.toThrow('Network error')
expect(store.error).toBe('Network error')
})
})
describe('Subscriptions', () => {
it('should notify subscribers on state change', () => {
const store = useCounterStore()
const callback = vi.fn()
store.$subscribe(callback)
store.count = 5
expect(callback).toHaveBeenCalled()
})
it('should notify action subscribers', () => {
const store = useCounterStore()
const onAction = vi.fn()
store.$onAction(onAction)
store.increment()
expect(onAction).toHaveBeenCalled()
})
})
})
2. 集成测试
// tests/integration/stores.integration.test.ts
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { setActivePinia, createPinia } from 'pinia'
import { useUserStore } from '@/stores/user'
import { useCartStore } from '@/stores/cart'
import { useOrderStore } from '@/stores/order'
describe('Store Integration', () => {
beforeEach(() => {
setActivePinia(createPinia())
})
it('should sync user state across stores', async () => {
const userStore = useUserStore()
const cartStore = useCartStore()
// 用户登录
await userStore.login({ email: 'test@test.com', password: '123456' })
// 购物车应该能访问用户信息
expect(cartStore.userId).toBe(userStore.user?.id)
})
it('should create order with cart items and user info', async () => {
const userStore = useUserStore()
const cartStore = useCartStore()
const orderStore = useOrderStore()
// 设置用户
await userStore.login({ email: 'test@test.com', password: '123456' })
// 添加商品到购物车
cartStore.addItem({ id: 1, name: 'Product', price: 100 })
cartStore.addItem({ id: 2, name: 'Another', price: 50 })
// 创建订单
const order = await orderStore.createOrder()
// 验证订单包含正确信息
expect(order.userId).toBe(userStore.user?.id)
expect(order.items).toHaveLength(2)
expect(order.total).toBe(150)
// 验证购物车已清空
expect(cartStore.items).toHaveLength(0)
})
})
大型项目架构
1. 项目结构组织
src/
├── modules/
│ ├── auth/
│ │ ├── stores/
│ │ │ ├── auth.store.ts
│ │ │ └── permissions.store.ts
│ │ ├── components/
│ │ ├── composables/
│ │ └── index.ts # 模块导出
│ ├── products/
│ │ ├── stores/
│ │ │ ├── product.store.ts
│ │ │ └── category.store.ts
│ │ ├── components/
│ │ └── index.ts
│ └── orders/
│ ├── stores/
│ │ ├── order.store.ts
│ │ └── payment.store.ts
│ └── index.ts
├── shared/
│ └── stores/
│ ├── ui.store.ts # 全局 UI 状态
│ └── cache.store.ts # 全局缓存
└── stores/
└── index.ts # Store 入口
2. Store 依赖注入容器
// core/container.ts
import type { Pinia } from 'pinia'
interface ContainerConfig {
pinia: Pinia
apiBaseUrl: string
storage: Storage
}
class StoreContainer {
private stores = new Map<string, any>()
private config: ContainerConfig
constructor(config: ContainerConfig) {
this.config = config
}
// 注册 Store
register<T>(name: string, factory: (container: StoreContainer) => T): void {
if (this.stores.has(name)) {
throw new Error(`Store ${name} already registered`)
}
Object.defineProperty(this, name, {
get: () => {
if (!this.stores.has(name)) {
this.stores.set(name, factory(this))
}
return this.stores.get(name)
},
configurable: true
})
}
// 获取配置
getConfig(): ContainerConfig {
return this.config
}
// 初始化所有 Store
async init(): Promise<void> {
for (const [name, store] of this.stores) {
if (store.init && typeof store.init === 'function') {
await store.init()
}
}
}
}
// 创建容器
export function createContainer(config: ContainerConfig): StoreContainer {
return new StoreContainer(config)
}
源码级原理解析
1. defineStore 的执行流程
defineStore(id, setup)
│
▼
返回 useStore 函数（闭包）
│
▼
调用 useStore()
│
├──▶ 获取当前 Pinia 实例（getActivePinia）
│
├──▶ 检查是否已存在该 Store
│ ├── 存在 → 直接返回缓存的 Store
│ └── 不存在 → 创建新 Store
│
└──▶ createSetupStore(id, setup, pinia)
│
├──▶ 创建响应式 Scope（用于自动清理）
│
├──▶ 执行 setup 函数
│ │
│ ├──▶ 将 ref → state
│ ├──▶ 将 computed → getter
│ └──▶ 将 function → action
│
├──▶ 处理 Options API 风格（如果是对象）
│
├──▶ 包装 Actions（添加订阅、错误处理）
│
├──▶ 添加 Store 属性（$patch, $reset, $subscribe 等）
│
└──▶ 返回响应式 Store 对象
2. 插件系统的工作机制
// Pinia 如何加载插件？
class Pinia {
constructor() {
this._p = [] // 插件数组
this._s = new Map() // Store 实例 Map
}
// 注册插件
use(plugin) {
this._p.push(plugin)
// 如果已有 Store，立即应用插件
this._s.forEach((store, id) => {
plugin({
pinia: this,
app: this._a,
store,
options: store.$options
})
})
return this
}
// 安装插件到具体 Store
_installPlugin(store) {
this._p.forEach(plugin => {
const result = plugin({
pinia: this,
app: this._a,
store,
options: store.$options
})
// 插件可以返回要添加到 Store 的属性
if (result) {
Object.assign(store, result)
}
})
}
}
从 Vuex 迁移到 Pinia
迁移清单
- 安装 Pinia
npm install pinia
- 创建 Pinia 实例
// main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
const app = createApp(App)
app.use(createPinia())
- 迁移 Vuex Modules 为 Pinia Stores
Before (Vuex):
// store/modules/user.js
export default {
namespaced: true,
state: () => ({ user: null }),
mutations: {
SET_USER(state, user) { state.user = user }
},
actions: {
async login({ commit }, credentials) {
const user = await api.login(credentials)
commit('SET_USER', user)
}
},
getters: {
isLoggedIn: state => !!state.user
}
}
After (Pinia):
// stores/user.js
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', {
state: () => ({ user: null }),
actions: {
async login(credentials) {
const user = await api.login(credentials)
this.user = user // 直接修改，不需要 mutation
}
},
getters: {
isLoggedIn: (state) => !!state.user
}
})
- 更新组件中的使用方式
Before:
<script>
import { mapState, mapActions } from 'vuex'
export default {
computed: {
...mapState('user', ['user'])
},
methods: {
...mapActions('user', ['login'])
}
}
</script>
After:
<script setup>
import { useUserStore } from '@/stores/user'
import { storeToRefs } from 'pinia'
const userStore = useUserStore()
const { user } = storeToRefs(userStore)
const { login } = userStore
</script>
常见问题
Q: 如何处理命名空间？
// Vuex: namespaced: true
// Pinia: 每个 store 天然是独立的，无需命名空间
Q: Mutations 去哪里了？
// Pinia 中直接修改 state，无需 mutations
// 或使用 actions 封装逻辑
Q: 如何处理插件（如持久化）？
// 使用 Pinia 插件系统
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
pinia.use(piniaPluginPersistedstate)
最佳实践总结
选择建议
| 场景 |
推荐方案 |
| 新项目 |
Pinia - 官方推荐，现代架构 |
| Vue 3 + TS |
Pinia - 完美的类型支持 |
| 大型应用 |
Pinia + 模块化架构 - 易于维护 |
| SSR 应用 |
Pinia - 更好的 SSR 支持 |
| 老项目维护 |
Vuex - 如果已有 Vuex，可以继续使用 |
| 快速原型 |
Pinia - 更快的开发速度 |
性能优化清单
- 使用虚拟滚动处理大数据列表
- 实现多级缓存策略（内存 + 持久化）
- 使用 Web Worker 处理复杂计算
- 合理使用 getter 缓存
- 避免不必要的 store 订阅
- 使用 storeToRefs 解构保持响应式
- 延迟加载非关键 store
最佳实践总结
-
单一职责：每个 store 只负责一个领域
-
组合优于继承：使用 composables 组合功能
-
类型优先：充分利用 TypeScript
-
测试覆盖：单元测试 + 集成测试 + E2E 测试
-
插件增强：使用插件实现横切关注点（日志、持久化等）
-
性能意识：关注大数据场景的性能优化
Pinia 的核心优势
-
简洁性：移除 Mutations，减少 40-50% 的样板代码
-
类型安全：原生 TypeScript 支持，完美类型推导
-
灵活性：支持 Options API 和 Composition API 两种风格
-
可扩展性：强大的插件系统，易于定制
-
DevTools：更好的开发体验，支持时间旅行
-
轻量级：~1KB，性能优于 Vuex
参考资源
登录