Vue 3 Pinia 状态管理实战用 JSDoc 类型体系驾驭 JavaScript 版 Storevue-expert-js 技能指南【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills导读本文基于 vue-expert-js 技能 的核心参考文档 state-management.md系统讲解如何在纯 JavaScript JSDoc 类型标注的 Vue 3 项目中落地 Pinia 状态管理。你将掌握 Options Store 与 Setup Store 两种写法的选型、storeToRefs解构保活、跨 Store 组合、localStorage 持久化与 Vitest 单元测试的完整链路并理解它与同仓库 TypeScript 版技能vue-expert在实现细节上的差异。背景为什么需要一个JavaScript 版的 Vue 状态管理方案在 claude-skills 仓库中vue-expert技能面向 TypeScript 生态vue-expert-js则是一条明确的技术路线只用 JavaScript 构建 Vue 3 应用用 JSDoc 注释typedef、param、returns、type替代 TS 编译器实现类型覆盖。该技能的约束见 SKILL.md非常清晰MUST DO使用script setup组合式 API、所有公共函数标注param/returns、跨文件共享的复杂对象使用typedef、响应式变量使用type注解MUST NOT DO禁止使用script setup langts、禁止.ts文件扩展名、禁止在 Vue 文件中使用 CommonJSrequire()。状态管理恰好是最容易暴露类型丢失问题的场景——store 里的ref、computed一旦在组件中解构响应式连接就会断裂。因此这份 state-management.md 参考文档的核心任务就是在 JSDoc 的约束下写出类型可追踪、可测试、可组合的 Pinia store。对于需要快速原型、团队偏好原生 JS 或.mjs模块的项目SKILL.md 中列出的触发场景这套方案让你在不上 TypeScript 的前提下依然拥有接近 TS 的 IDE 提示质量。一、安装与初始化Pinia 的接入方式与 TypeScript 版完全一致Pinia 通过 Vue 插件机制注册到应用实例。以main.js为例// main.js import { createApp } from vue import { createPinia } from pinia import App from ./App.vue createApp(App).use(createPinia()).mount(#app)关键点在于createPinia()创建的是一个 Pinia 实例而非全局单例它负责维护所有 store 实例的注册表为每个 store 生成唯一的$id在组件卸载、热更新等场景下统一管理 store 生命周期。从源码结构看createPinia()的返回值被app.use()消费后组件内部通过useStore()调用即可拿到全局唯一的 store 实例这正是组件间共享状态的基础。二、Options StoreVuex 风格的传统写法Pinia 保留了类似 Vuex 的 Options 写法适合从旧项目迁移或团队熟悉度优先的场景。参考 counter.js 示例// stores/counter.js import { defineStore } from pinia export const useCounterStore defineStore(counter, { state: () ({ count: 0, name: Counter }), getters: { doubleCount: (state) state.count * 2, // Getter with parameter countPlusN: (state) (n) state.count n }, actions: { increment() { this.count }, /** param {number} amount */ incrementBy(amount) { this.count amount } } })几个容易踩坑的细节state 必须是返回对象而非对象字面量的函数。这是为了每次调用都生成独立的初始状态避免 SSR 场景下的状态串扰getter 返回函数即可获得带参数 getter。countPlusN本质上是一个返回闭包的 getter调用方式是store.countPlusN(5)需要注意它不会像普通 getter 那样被缓存action 中通过this访问 state 与 getter。由于 Pinia 对 store 做了reactive代理this.count天然具备响应式更新能力action 参数需要 JSDoc。上面的/** param {number} amount */正是 vue-expert-js 技能强调的类型覆盖实践——没有 TS 编译器时IDE 靠这条注释推断调用方传入的参数类型。Options 与 Setup 的取舍维度Options StoreSetup Store风格类 Vuex字段分节state/getters/actions类组合式函数逻辑天然聚合类型推断state 由state()返回值推导由ref/computed的 JSDoc 类型推导组织方式按能力类型切分按业务域切分相关代码相邻适用场景迁移旧 Vuex 项目新项目、逻辑内聚、推荐优先同仓库 TypeScript 版技能 vue-expert 的 state-management 参考 明确将 Setup Store 标注为RECOMMENDED这条建议在 JavaScript 版同样成立Setup Store 与组合式 API 的心智模型一致且更容易复用 composable 层面的模式详见 composables-patterns.md。三、Setup Store组合式 API 写法与 JSDoc 类型体系Setup Store 把 state/getters/actions 统一收敛到一个函数体内用ref当 state、computed当 getter、普通函数当 action。参考 user.js 示例// stores/user.js import { defineStore } from pinia import { ref, computed } from vue /** * typedef {Object} User * property {number} id * property {string} name * property {string} email */ export const useUserStore defineStore(user, () { // State /** type {import(vue).RefUser | null} */ const currentUser ref(null) const isLoading ref(false) const error ref(null) // Getters const isLoggedIn computed(() currentUser.value ! null) const userName computed(() currentUser.value?.name ?? Guest) // Actions async function login(email, password) { isLoading.value true error.value null try { const res await fetch(/api/login, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ email, password }) }) currentUser.value (await res.json()).user return true } catch (e) { error.value e.message return false } finally { isLoading.value false } } function logout() { currentUser.value null } return { currentUser, isLoading, error, isLoggedIn, userName, login, logout } })这段代码体现了 vue-expert-js 状态管理的三个核心模式1.typedef定义领域模型User这种跨 store、跨组件复用的对象形状用typedef定义一次即可全局引用。该技能还提供了更细的共享类型规范见 jsdoc-typing.md把类型集中到types.js用export const Types {}让 IDE 能够识别导入组件内通过/** typedef {import(./types.js).User} User */引入。2.type锁定响应式变量的类型/** type {import(vue).RefUser | null} */告诉编辑器这是一个可能为空的Ref。这样后续.value访问时IDE 能提示出User的属性并且currentUser.value?.name的可选链用法会被类型检查认可。3. 异步 action 的 loading/error 三段式isLoading/error与业务状态currentUser分离用try/catch/finally保证finally中一定会复位 loading。这种模式在 jsdoc-typing.md 的 Pinia 章节 中有几乎同构的实现返回值标注为returns {Promiseboolean}可以直接对照学习更完整的注释写法。迁移提示该技能的 composables-patterns.md 还给出了模块级ref实现单例共享状态的替代方案useNotifications示例。对于多组件共享但不需要全局 debug 工具的轻量状态composable 单例比 Pinia store 更简单而需要 devtools、插件、持久化、跨页面一致性时Pinia 是更稳的选择。四、组件内使用 StorestoreToRefs是响应式的保命符这是最常见的错误源头直接解构 store 会导致响应式丢失。正确的做法如下参考 state-management.md 的 Using Stores 章节script setup import { useUserStore } from /stores/user import { storeToRefs } from pinia const userStore useUserStore() // Use storeToRefs for reactive state/getters const { currentUser, isLoggedIn, isLoading } storeToRefs(userStore) // Actions can be destructured directly const { login, logout } userStore /script template div v-ifisLoadingLoading.../div div v-else-ifisLoggedIn Welcome, {{ currentUser?.name }} button clicklogoutLogout/button /div /template原理拆解store 本身是reactive对象把它整体暴露给模板时一切正常storeToRefs()逐个把 store 上的属性转成Ref后返回因此解构出来的currentUser/isLoading依旧是响应式引用模板中的v-ifisLoading能正确触发更新action 是普通函数不涉及响应式代理可以直接const { login, logout } userStore解构这也是 TS 版参考文档 vue-expert 的 storeToRefs 章节 明确强调的规则。注意一个区别Options Store 中getter 通过storeToRefs()解构后可直接使用doubleCount在模板里是doubleCount而非doubleCount.value因为模板自动解包而 Setup Store 中如果你把computed返回对象的一部分同样适用。两条路线在此行为一致。五、Store Composition跨 Store 协作与购物车实战Pinia 允许在 store 内调用其他 store 的 hook形成自然的组合关系。参考 cart.js 示例// stores/cart.js import { defineStore } from pinia import { ref, computed } from vue import { useProductsStore } from ./products import { useUserStore } from ./user export const useCartStore defineStore(cart, () { const items ref([]) // [{ productId, quantity }] // Access other stores const productsStore useProductsStore() const userStore useUserStore() const total computed(() items.value.reduce((sum, item) { const product productsStore.items.find(p p.id item.productId) return sum (product?.price ?? 0) * item.quantity }, 0) ) function addItem(productId, quantity 1) { const existing items.value.find(i i.productId productId) if (existing) existing.quantity quantity else items.value.push({ productId, quantity }) } async function checkout() { if (!userStore.isLoggedIn) throw new Error(Must be logged in) await fetch(/api/checkout, { method: POST, body: JSON.stringify({ userId: userStore.currentUser.id, items: items.value }) }) items.value [] } return { items, total, addItem, checkout } })要点Setup Store 中可以在函数体顶层调用其他 store hook。这与在组件script setup顶层调用 composable 的规则一致Pinia 会自动完成依赖注册total是一个联动 getter当items或productsStore.items变化时computed会重新求值模板中{{ cartStore.total }}自动更新action 内通过另一个 store 的 state 做业务决策checkout前校验登录态体现了store 即领域服务的组合式设计对比同仓库 TS 版 vue-expert 的跨 Store 访问章节 可以看到两版在结构上完全对应只是 JS 版以注释形式标注了items的元素形状// [{ productId, quantity }]TS 版则用interface CartItem声明。补充说明Options Store 中访问其他 store 需要在 action 内部调用 hook不能用于 state/getter 顶层这也是两份参考文档 Quick Reference 表中 Use in actions 与 Call at setup top level 两行的含义。六、状态持久化localStorage watch的最小实现不依赖第三方插件、零依赖地实现持久化核心思路是初始化时读、变更时写。参考 settings.js 示例// stores/settings.js import { defineStore } from pinia import { ref, watch } from vue const STORAGE_KEY app-settings function loadFromStorage() { try { return JSON.parse(localStorage.getItem(STORAGE_KEY)) ?? {} } catch { return {} } } export const useSettingsStore defineStore(settings, () { const saved loadFromStorage() const theme ref(saved.theme ?? light) const language ref(saved.language ?? en) watch([theme, language], () { localStorage.setItem(STORAGE_KEY, JSON.stringify({ theme: theme.value, language: language.value })) }) return { theme, language } })三个工程细节值得注意loadFromStorage用try/catch包裹JSON.parselocalStorage 数据可能被用户手动改动或跨版本不兼容解析失败时回退到空对象避免整个 store 初始化崩溃saved.theme ?? light的兜底既处理了key不存在返回{}也处理了解析出的值缺失的情况watch([theme, language], ...)多源监听任一设置变化即写回实现读时幂等、写时增量。与之对比TypeScript 版技能通过pinia-plugin-persistedstate插件实现persist: true或persist: { key, storage, paths }见 vue-expert 的 Persistence 章节。JS 版选择手写watch的原因在于在纯 JS JSDoc 的项目里插件引入带来的类型推断收益有限手写方案依赖面更小、逻辑透明。如果项目希望用插件方式两种方案可并行但需注意paths白名单只持久化指定字段的用法更可控。七、Store 单元测试setActivePinia隔离测试环境Pinia store 是可纯逻辑测试的单元。参考 counter.test.js 示例// stores/__tests__/counter.test.js import { describe, it, expect, beforeEach } from vitest import { setActivePinia, createPinia } from pinia import { useCounterStore } from ../counter describe(Counter Store, () { beforeEach(() setActivePinia(createPinia())) it(increments count, () { const store useCounterStore() store.increment() expect(store.count).toBe(1) }) it(computes double count, () { const store useCounterStore() store.count 5 expect(store.doubleCount).toBe(10) }) })测试要点beforeEach中setActivePinia(createPinia())是必不可少的隔离手段——每个用例都拿到全新的 Pinia 实例杜绝用例间状态泄漏。这也是 vue-expert 的 Store Testing 章节 采用完全相同的模式直接给 store 赋值store.count 5即可构造前置状态无需走 action让测试更聚焦由于 store 不依赖 DOM这些用例可以在 Node 环境的 Vitest 中直接跑无需 jsdom。当测试目标是组件与 store 的联动时该技能的 testing-patterns.md 提供了pinia/testing的createTestingPinia({ initialState })方案先注入初始 state再断言组件渲染与 action 调用expect(useCartStore().checkout).toHaveBeenCalled()。建议把纯 store 逻辑测试与组件集成测试分层前者保证领域逻辑正确后者保证视图绑定无误。八、快速参考表Options vs Setup 一图速查FeatureOptions SyntaxSetup SyntaxStatestate: () ({})const x ref()Gettergetters: { x: (state) }const x computed()Actionactions: { fn() {} }function fn() {}Use in componentstoreToRefs()for stateSameReset statestore.$reset()Manual reset functionSubscribestore.$subscribe((mutation, state) {})SameOther storesUse in actionsCall at setup top level对表格的补充说明结合源码与两版文档重置状态Options Store 的store.$reset()会回到state()的初始值Setup Store 没有内置 reset需要手写一个reset()action 逐一复位ref。如需自动化可结合store.$patch({ count: 0 })批量更新订阅机制store.$subscribe在两种语法下行为一致回调收到的mutation包含typedirect/patch object/patch function与payload适合做日志、埋点或联动持久化$patch批量更新是另一个在表格外的常用 APIstore.$patch({ count: store.count 1 })或函数形式store.$patch((s) s.count)前者适合简单赋值后者适合复杂派生逻辑TS 版 Quick Reference 中将其列为独立一行JS 版同样适用跨 store 访问的差异Options Store 规定只能在 actions 中使用而 Setup Store 允许在 setup 顶层调用——因为 Setup Store 的函数体本质就是一个组合式上下文。九、从这份参考文档反推的完整技能工作流这份 state-management 参考只是 vue-expert-js 技能的五条支柱之一。根据 SKILL.md 定义的核心工作流当 Agent 被要求给 Vue JS 项目加上购物车状态时完整链路是设计架构确定 store 拆分user/products/cart用typedef规划领域模型参考 jsdoc-typing.md实现用script setup Setup Store 写出本文第三、五节的代码形态所有 public API 带 JSDoc校验运行带eslint-plugin-jsdoc的 ESLint确认每个param/returns齐全测试按第七节用 Vitest 覆盖 store 的 action 与 getter若失败则回到对应 store 修正。这种参考文档 校验闭环的设计使得即使没有 TypeScript团队也能在 CI 中保证状态管理代码的类型完整性与逻辑正确性。对于恰好处于想用 Pinia 又不想引入 TS的项目这套方案就是开箱即用的最佳实践模板。十、结论与使用边界归纳起来本参考文档给出的 JS 版 Pinia 状态管理方案五步全覆盖初始化createPinia→ 定义Options/Setup 双语法→ 消费storeToRefs→ 组合跨 store 调用→ 加固持久化 测试类型不失真用typedef/type/param三个 JSDoc 原语把 TS 的interface/RefT/函数签名完整映射到纯 JS 上配合 ESLint JSDoc 插件形成可验证的类型护栏实践边界文中所有代码均为仓库参考文档的原创示例state-management.md而非第三方库的转载插件化持久化、pinia/testing组件测试、模块级ref单例等进阶能力在技能的其他参考文档testing-patterns.md、composables-patterns.md以及 TS 版 vue-expert 状态管理参考 中可继续深挖两版技能共享相同的核心模式可互为印证。当你的项目因为团队偏好、原型速度或交付约束而选择JavaScript only时这份文档就是你在 Vue 3 里把全局状态写得既健壮又清晰的完整答案。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考