在 Vue3 中如何实现四种全局状态数据的统一管理？

[zhennann]

四种全局状态数据

在实际开发当中，会遇到四种全局状态数据：异步数据（一般来自服务端）、同步数据。同步数据又分为三种：localstorage、cookie、内存。在传统的 Vue3 当中，分别采用不同的机制来处理这些状态数据，而在 Zova 中只需要采用统一的Model机制

状态数据	传统的 Vue3	Zova
异步数据	Pinia	Model
localstorage	Pinia + Localstorage	Model
cookie	Pinia + Cookie	Model
内存	Pinia	Model

采用 Model 机制统一管理这些全局状态数据，就可以提供一些通用的系统能力，比如，内存优化、持久化和SSR 支持等等，从而规范数据使用方式，简化代码结构，提升代码的可维护性

特性 1. 支持异步数据和同步数据

Zova Model 的基座是TanStack Query。TanStack Query 提供了强大的数据获取、缓存和更新能力。如果你没有使用过类似 TanStack Query 的数据管理机制，那么强烈建议了解一下，相信你一定会受到思想的洗礼 但是，TanStack Query 的核心是对异步数据（一般来自服务端）进行管理。Zova Model 在 TanStack Query 的基础上做了扩展，因此也支持同步数据的管理。换而言之，以下所述所有特性和能力同时适用于异步数据和同步数据

特性 2. 自动缓存

对获取的异步数据进行本地缓存，避免重复获取。对于同步数据，会自动针对 localstorage 或者 cookie 进行读写操作

特性 3. 自动更新

提供数据过期策略，在合适的时机自动更新

特性 4. 减少重复请求

在程序的多个地方同时访问数据，将只调用一次服务端 api 。如果是同步数据，也只针对 localstorage 或者 cookie 调用一次操作

特性 5. 内存优化

通过 Zova Model 管理的数据，虽然是全局范围的状态，但是并不总是占用内存，而是提供了内存释放与回收的机制。具体而言，就是在创建 Vue 组件实例时根据业务的需要创建缓存数据，当 Vue 组件实例卸载时释放对缓存数据的引用，到达约定的过期时间如果仍然没有其他 Vue 组件引用，就会触发回收机制(GC)，完成对内存的释放，从而节约内存占用。这对于大型项目，用户需要长时间进行界面交互的场景，具有显著的好处

特性 6. 持久化

本地缓存可以持久化，当页面刷新时可以自动恢复，避免服务端调用。如果是异步数据，就会自动持久化到 IndexDB 中，从而满足大数据量的存储需要。如果是同步数据，就会自动持久化到 localstorage 或者 cookie

内存优化与持久化配合发挥作用，对于大型项目效果更佳明显。比如，第一次从服务端获取的数据，会生成本地缓存，并自动持久化。当页面不再使用并且过期时，会自动销毁本地缓存，从而释放内存。当再次访问该数据时，会自动从持久化中恢复本地缓存数据，而不是再次从服务端获取数据

特性 7. SSR 支持

不同类型的状态数据，在 SSR 模式下也会有不同的实现机制。Zova Model 把这些状态数据的差异进行抹平，并且采用统一的机制进行水合，从而让 SSR 的实现更加自然、直观，显著降低了心智负担

特性 8. 自动命名空间隔离

Zova 通过 Model Bean 来管理数据。而 Bean 本身有唯一的标识，可以作为数据的命名空间，从而自动保证了 Bean 内部状态数据命名的唯一性，避免数据冲突

• 参见：Bean 标识

如何创建一个 Model Bean

Zova 提供了 VS Code 插件，通过右键菜单可以非常便利的创建一个 Model Bean

右键菜单 - [模块路径]: Zova Create/Bean: Model

依据提示输入 model bean 的名称，比如todo，VSCode 插件会自动添加 model bean 的代码骨架

比如，在 demo-todo 模块中创建一个 Model Bean todo

demo-todo/src/bean/model.todo.ts

import { Model } from 'zova';
import { BeanModelBase } from 'zova-module-a-model';

@Model()
export class ModelTodo extends BeanModelBase {}

• 使用 @Model 装饰器
• 继承自基类 BeanModelBase

异步数据

TanStack Query 的核心是对服务端数据进行管理。为简化起见，这里仅展示 select 方法的定义与使用:

• 完整代码示例，请参见：demo-todo

如何定义

@Model()
export class ModelTodo {
  select() {
    return this.$useQueryExisting({
      queryKey: ['select'],
      queryFn: async () => {
        return this.scope.service.todo.select();
      },
    });
  }
}

• 调用$useQueryExisting 创建 Query 对象
  • 为何不使用$useQuery方法？因为异步数据一般是在需要时才进行异步加载。因此我们需要确保在多次调用select方法时始终返回同一个 Query 对象，所以必须使用$useQueryExisting方法
• 传入 queryKey ，确保本地缓存的唯一性
• 传入 queryFn ，在合适的时机调用此函数获取服务端数据
  • service.todo.select：参见Api 服务

如何使用

demo-todo/src/page/todo/controller.ts

import { ModelTodo } from '../../bean/model.todo.js';

export class ControllerPageTodo {
  @Use()
  $$modelTodo: ModelTodo;
}

• 注入 Model Bean 实例：$$modelTodo

demo-todo/src/page/todo/render.tsx

export class RenderTodo {
  render() {
    const todos = this.$$modelTodo.select();
    return (
      <div>
        <div>isLoading: {todos.isLoading}</div>
        <div>
          {todos.data?.map(item => {
            return <div>{item.title}</div>;
          })}
        </div>
      </div>
    );
  }
}

• 调用 select 方法获取 Query 对象
  • render 方法会多次执行，重复调用 select 方法返回的是同一个 Query 对象
• 直接使用 Query 对象中的状态和数据
  • 参见：TanStack Query: Queries

如何支持 SSR

在 SSR 模式下，我们需要这样使用异步数据：在服务端加载状态数据，然后通过 render 方法渲染成 html 字符串。状态数据和 html 字符串会同时发送到客户端，客户端在进行水合时仍然使用此相同的状态数据，从而保持状态的一致性

要实现以上逻辑，在 Zova Model 中只需要执行一个步骤：

demo-todo/src/page/todo/controller.ts

import { ModelTodo } from '../../bean/model.todo.js';

export class ControllerPageTodo {
  @Use()
  $$modelTodo: ModelTodo;

  protected async __init__() {
    const queryTodos = this.$$modelTodo.select();
    await queryTodos.suspense();
    if (queryTodos.error) throw queryTodos.error;
  }
}

• 只需要在__init__方法中调用suspense等待异步数据加载完成

同步数据: localstorage

由于服务端不支持window.localStorage，因此 localstorage 状态数据不参与 SSR 的水合过程

下面演示把用户信息存入 localstorage ，当页面刷新时也会保持状态

如何定义

export class ModelUser extends BeanModelBase {
  user?: ServiceUserEntity;

  protected async __init__() {
    this.user = this.$useQueryLocal({
      queryKey: ['user'],
    });
  }
}

• 与异步数据定义不同，同步数据直接在初始化方法__init__中定义
• 调用$useQueryLocal 创建 Query 对象
• 传入 queryKey ，确保本地缓存的唯一性

如何使用

直接像常规变量一样读取和设置数据

const user = this.user;
this.user = newUser;

同步数据: cookie

在服务端会自动使用Request Header中的 Cookies ，在客户端会自动使用document.cookie，因此会自动保证 SSR 水合过程中 cookie 状态数据的一致性

下面演示把用户 Token 存入 cookie ，当页面刷新时也会保持状态。这样，在 SSR 模式下，客户端和服务端都可以使用相同的jwt token访问后端 API 服务

如何定义

export class ModelUser extends BeanModelBase {
  token?: string;

  protected async __init__() {
    this.token = this.$useQueryCookie({
      queryKey: ['token'],
    });
  }
}

• 与异步数据定义不同，同步数据直接在初始化方法__init__中定义
• 调用$useQueryCookie 创建 Query 对象
• 传入 queryKey ，确保本地缓存的唯一性

如何使用

直接像常规变量一样读取和设置数据

const token = this.token;
this.token = newToken;

同步数据: 内存

在 SSR 模式下，服务端定义的全局状态数据会同步到客户端，并自动完成水合

下面演示基于内存的全局状态数据

如何定义

zova-ui-quasar/src/suite-vendor/a-quasar/modules/quasar-adapter/src/bean/model.theme.ts

export class ModelTheme extends BeanModelBase {
  cBrand: string;

  protected async __init__() {
    this.cBrand = this.$useQueryMem({
      queryKey: ['cBrand'],
    });
  }
}

• 与异步数据定义不同，同步数据直接在初始化方法__init__中定义
• 调用$useQueryMem 创建 Query 对象
• 传入 queryKey ，确保本地缓存的唯一性

如何使用

直接像常规变量一样读取和设置数据

const cBrand = this.cBrand;
this.cBrand = newValue;

结语

Zova 是一款支持 IOC 容器的 Vue3 框架，在代码风格上结合了 Vue/React/Angular 的优点，同时规避他们的缺点，让我们的开发体验更加优雅，减轻心智负担。Zova 已经内置了大量实用、有趣的功能特性，Model 机制仅仅是其中一个

Zova 框架已经开源，欢迎关注，参与共建：https://github.com/cabloy/zova。可添加我的微信，入群交流：yangjian2025