Vuex 应用结构用三条高层原则组织可维护、可扩展的模块化 Store【免费下载链接】vuex️ Centralized State Management for Vue.js.项目地址: https://gitcode.com/gh_mirrors/vu/vuexVuex 本身不强制任何目录模板而是通过三条高层原则约束状态管理的边界应用级状态集中在 Store、状态只能通过同步的Mutation变更、异步逻辑封装并组合于Action。本文以 docs/ja/guide/structure.md 为骨架讲解在遵守这些原则的前提下如何拆分文件、如何借助模块Module应对非平凡应用并对照仓库中的 Shopping Cart 完整示例给出可直接复用的目录设计。Vuex 不限制结构只约束三条原则很多状态管理库会规定你必须把代码放进某个固定目录Vuex 恰恰相反——它把怎么排版代码的决定权完全交给你只强制三条更高层的原则应用级状态集中在 Store 中整个应用共享的唯一数据源single source of truth放在一个 store 对象里组件不各自维护散落的状态副本改变状态的唯一方式是提交commitMutationMutation 是同步事务所有状态变更都有迹可循、可被 devtools 追踪异步逻辑必须封装在 Action 中Action 内部可以做任意异步操作请求、延时、组合其他 action但最终仍然通过 commit mutation 来真正修改状态。这三条原则正是 docs/guide/mutations.md 与 docs/guide/actions.md 展开论述的核心Mutation 处理同步变更、Action 处理异步与编排。只要守住这三条边界Store 内部的组织方式单一文件还是多文件、是否拆模块完全由项目规模和团队习惯决定。从单文件到多文件Store 变大的第一步拆分对于小应用把 state、getters、mutations、actions 全部写在一个 store 文件里完全合理。当 store 文件开始变得臃肿时原文档给出的建议非常直接把 actions、mutations、getters 分别切到独立文件。这是最轻量的演进路径——不需要引入模块机制只是把根级root的四个部分按职责拆文件每个文件导出对应对象再在store/index.js中汇总// store/index.js —— 汇总并导出 store import { createStore } from vuex import actions from ./actions // 根级 actions import mutations from ./mutations // 根级 mutations import getters from ./getters // 根级 getters按需 export default createStore({ state () { return { /* 根状态 */ } }, getters, mutations, actions })这种拆分纯粹是文件组织层面的重构不改变任何运行语义——createStore只关心传入的选项对象结构不关心这些对象来自哪个文件。Vuex 4 的入口实现 src/store.js 通过 ModuleCollection 收集模块树把传入的 state/getters/mutations/actions 统一安装到内部_modules上因此文件的切分方式对运行时完全透明。推荐目录结构非平凡应用的模块化模板原文档明确表示只要遵循这些规则项目如何结构取决于你而对于任何非平凡non-trivial的应用我们很可能需要借助模块。 并给出了一个经典的项目结构模板├── index.html ├── main.js ├── api │ └── ... # 抽象 API 调用 ├── components │ ├── App.vue │ └── ... └── store ├── index.js # 汇总模块并导出 store ├── actions.js # 根级 actions ├── mutations.js # 根级 mutations └── modules ├── cart.js # cart 模块 └── products.js # products 模块这个结构的几个设计要点api/独立于 store网络请求的细节URL、参数、序列化被隔离在api目录store 的 action 只调用api暴露的函数拿到数据后 commit mutation。这样 store 里没有fetch/axios噪音便于测试时 mockstore/index.js是唯一出口所有模块在这里组装main.js只import store并app.use(store)组件不感知模块内部布局store/modules/按业务域划分每个业务域一个文件文件内自含该域的 state、getters、mutations、actions形成内聚单元根级 actions/mutations 保留跨模块共享或不属于任何业务域的根级逻辑放在 store 根与模块树并存。从模块系统的实现看src/module/module.js 把每个模块包括根模块建模为包含state、getters、mutations、actions、children的节点module-collection.js 负责递归注册嵌套模块——这正是store/modules/目录可以无限嵌套、每个模块文件内部再声明modules子模块的底层依据详见 docs/guide/modules.md。实战参考Shopping Cart 示例的完整解剖原文档末尾指向了 Shopping Cart 示例。在当前仓库中它有两个版本经典选项式 API 版 examples/classic/shopping-cart 与 Composition API 版 examples/composition/shopping-cart。以 classic 版为例它完整实现了上文推荐的结构。目录与文件的对应关系examples/classic/shopping-cart/ ├── api/ │ └── shop.js # mock 的 API 抽象 ├── components/ │ ├── App.vue │ ├── ProductList.vue │ └── ShoppingCart.vue ├── store/ │ ├── index.js # 组装模块、导出 store │ └── modules/ │ ├── cart.js # 购物车模块含嵌套模块 nested │ ├── nested.js # 嵌套子模块示例 │ └── products.js # 商品模块 ├── app.js # 创建应用并 app.use(store) ├── currency.js └── index.html组装入口store/index.jsexamples/classic/shopping-cart/store/index.js 是目录结构的核心——它把模块汇总进createStore并展示了两个非常实用的生产配置import { createStore, createLogger } from vuex import cart from ./modules/cart import products from ./modules/products const debug process.env.NODE_ENV ! production export default createStore({ modules: { cart, products }, strict: debug, // 非生产环境开启严格模式 plugins: debug ? [createLogger()] : [] // 非生产环境挂载日志插件 })这里体现了两条值得沿用的实践严格模式strict与 logger 插件只在开发环境开启。strict模式下任何绕过 mutation 的状态直接赋值都会抛出错误强制团队遵守唯一变更途径是 commit mutation的原则createLogger则把每次 mutation 前后的状态快照打到控制台。二者在NODE_ENV ! production时启用、生产构建自动剔除零成本换取开发体验。业务模块的自我包含cart.js 与 products.jscart 模块 与 products 模块 都采用同样的四件套结构这正是原文档推荐目录结构的模块粒度state 使用函数返回state: () ({ items: [], checkoutStatus: null })避免模块被复用或 SSR 时共享同一个状态对象模块复用问题的详细讨论见 docs/guide/modules.md 的 Module Reuse 一节getters 负责派生数据例如cartProducts把购物车中的{ id, quantity }与rootState.products.all中的商品详情合并cartTotalPrice计算总价——组件只需读 getter无需关心数据拼装逻辑actions 承载异步与编排async checkout({ commit, state }, products)演示了完整的异步事务流程——先清空购物车、调用shop.buyProducts(products)、成功则提交setCheckoutStatus(successful)失败则回滚到保存的快照。这就是异步逻辑封装在 action原则的活教材mutations 只做同步变更pushProductToCart、incrementItemQuantity、setCheckoutStatus全部是纯同步的状态修改action 通过commit调用它们。两个模块都声明了namespaced: true因此 action 与 mutation 的类型名自动带上前缀cart 模块的addProductToCart在组件中通过dispatch(cart/addProductToCart)或mapActions(cart, [addProductToCart])调用products 模块同理。cart 模块还通过commit(products/decrementProductInventory, { id }, { root: true })提交其他命名空间下的 mutation演示了跨模块协作的标准姿势。此外cart 模块内部还嵌套了 nested.jsmodules: { nested }这是一个极简的嵌套模块示例——它继承了父模块的cart/命名空间getter 类型名为cart/twoBars。这印证了模块系统分形递归、可任意嵌套的特性目录结构深度与模块嵌套深度一一对应。API 抽象层api/shop.jsapi/shop.js 用 mock 数据模拟客户端-服务器交互getProducts()延时 100ms 返回商品列表buyProducts()以 50% 概率模拟结算失败并抛出Checkout error。这正是api/目录存在的意义——action 只依赖有一个能返回 Promise 的 API 函数至于它背后是真实 HTTP 请求还是本地 mock对 store 完全透明。真实项目中把这个文件替换成 axios/fetch 封装即可store 代码一行不用改。组件如何接入app.js 展示了入口的接入方式createApp(App)创建应用后app.use(store)完成注入。组件侧ProductList.vue 用mapState({ products: state state.products.all })读取 products 模块状态、...mapActions(cart, [addProductToCart])绑定带命名空间的 action、在created()中dispatch(products/getAllProducts)触发初始化。整个调用链严格单向组件 → action可能调 API→ mutation → 状态 → 组件渲染。命名空间让模块自包含、可复用非命名空间模块的 actions/mutations 默认注册在全局命名空间多个模块可以响应同一个 action/mutation 类型但 getters 同名会报错。要让模块更自包含、可复用在模块上声明namespaced: true即可——模块内所有 getters、actions、mutations 会自动按注册路径加前缀详见 docs/guide/modules.md 的 Namespacing 一节。命名空间带来的配套能力包括局部化上下文命名空间模块内的 getters/actions 收到的是局部化的getters、dispatch、commit模块内部写代码时无需前缀访问全局资源通过 getter 的第 3、4 个参数rootState、rootGetters或dispatch/commit的第 3 个参数{ root: true }访问全局Shopping Cart 中commit(products/decrementProductInventory, { id }, { root: true })就是这一用法的实例绑定辅助函数mapState(cart, ...)、mapGetters、mapActions可以接收命名空间字符串作为第一个参数也可以使用createNamespacedHelpers(cart)生成预绑定命名空间的 helper减少组件中的样板代码。模块化的进阶能力动态注册与模块复用原文档的目录模板只是起点docs/guide/modules.md 还补充了三个非平凡应用几乎必然会用到的模块能力它们与结构主题直接相关动态注册模块store.registerModule(a, module)可在 store 创建后按需挂载模块如按路由懒加载业务模块配合store.unregisterModule与store.hasModule使用嵌套模块路径要传数组[nested, myModule]。registerModule还支持{ preserveState: true }保留既有状态如 SSR 水合场景模块复用同一个模块被多个 store 使用、或在同一 store 注册多次时必须用函数形式声明 statestate: () ({...})否则状态对象按引用共享会造成污染——这与 Vue 组件data必须用函数是同一个道理Shopping Cart 各模块均已遵循插件开发的命名空间陷阱插件若向用户 store 提供模块用户可能把它挂在命名空间模块下因此插件应通过选项接收 namespace 值再拼接类型名docs/guide/plugins.md 有更完整的插件开发说明。小结结构是手段原则是底线回到原文档的结论Vuex 把如何组织代码的自由留给开发者但用三条原则框定了底线——状态集中、变更走 mutation、异步走 action。在这条底线之上小应用可以直接单文件文件变大时先按 actions/mutations/getters 拆文件非平凡应用引入store/modules/按业务域拆模块必要时叠加命名空间与动态注册推荐将api/与store/分离让网络细节不进状态层直接对照仓库中的 classic 版 或 composition 版 Shopping Cart 示例落地。这套结构不依赖特定构建工具或框架版本既适用于选项式 API也适用于 docs/guide/composition-api.md 描述的 Composition API 用法——它解决的是状态层如何组织的问题与组件层的写法正交。【免费下载链接】vuex️ Centralized State Management for Vue.js.项目地址: https://gitcode.com/gh_mirrors/vu/vuex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
