详解 dva Model 结构：state、reducers 与 effects 写法指南

一、dva Model 架构拓扑与数据流动机制

dva 是阿里开源的一款基于 Redux 和 Redux-Saga 的轻量级状态管理框架。在传统的 Redux 体系中，开发者需要分散维护 actionTypes、actionCreator、reducer 和 saga 文件，而在 dva 中，一个业务领域的所有状态逻辑都被高内聚地封装在单个 Model 对象中。

一个标准的 dva Model 包含以下核心要素：

• namespace：Model 的唯一命名空间，作为全局 Redux 状态树的分支节点名称。
• state：当前命名空间下的初始数据快照，存储纯净的业务数据。
• reducers：处理同步状态变更的纯函数集合，也是唯一具有修改 state 权限的地方。
• effects：基于 ES6 Generator 与 redux-saga 的异步副作用处理器，负责执行 HTTP 请求、异步调度与复杂业务编排。
• subscriptions（可选）：用于监听路由变化、键盘事件或 WebSocket 消息的事件订阅源。

如上图所示，dva 遵循严格的单向数据流原则：React UI 组件通过派发（dispatch）携带特定 type 的 Action。若 Action 对应同步变更，直接命中 Reducers 生成新 State 并触发视图刷新；若涉及服务端请求等副作用，则命中 Effects，由 Effects 执行异步拉取后，再通过 put 算子调用 Reducers 将新数据写入 State。

二、State 的设计规范与不可变性原则

state 是业务数据的基石。在 dva 中，每个 Model 的 state 会被挂载到全局状态树对应 namespace 的节点上。设计良好且扁平的 state 结构能够极大降低后续更新逻辑的复杂度。

1. 初始状态定义模式

定义 state 时，务必为每个属性提供类型明确的初始默认值，避免在组件挂载初期因读取 undefined 引发解构报错。

// models/user.js 初始状态规范定义
export default {
  namespace: 'user',
  state: {
    // 列表数据预设空数组，避免 .map 抛出异常
    list: [],
    // 分页结构保持扁平化
    total: 0,
    page: 1,
    pageSize: 10,
    // 实体详情对象赋予初始结构
    currentUser: {
      id: null,
      name: '',
      roles: []
    }
  },
  // ... reducers & effects
};

三、Reducers：同步状态变更写法指南

Reducers 承载了 Redux 理念的核心：纯函数（Pure Function）。它接收当前 state 和传入的 action，通过确定性的计算返回全新的 state 对象。

1. 核心约束与纯函数规则

编写 Reducer 必须严格遵守以下三条红线：

1. 绝对不能产生副作用：禁止在 Reducer 中调用接口、写入 localStorage、启动定时器或发起任何网络 I/O。
2. 相同输入必须产生相同输出：禁止在 Reducer 中调用 Math.random() 或 new Date() 等具有不确定性的方法。
3. 严禁原地修改（Mutation）现有 state 引用：必须返回新的对象副本，否则 React 浅比较（Shallow Compare）机制会误判状态未发生改变，导致页面不发生重渲染。

2. 常用 Reducer 编写模式

在实际业务中，最推荐封装通用保存方法与专门的重置方法：

// models/user.js 中的 reducers 规范实现
reducers: {
  /**
   * 1. 通用更新属性方法：将 payload 中的键值浅合并至 state
   */
  save(state, { payload }) {
    return {
      ...state,
      ...payload,
    };
  },

  /**
   * 2. 分页追加更新模式：列表追加或覆盖
   */
  appendList(state, { payload }) {
    return {
      ...state,
      list: [...state.list, ...payload.items],
      total: payload.total,
    };
  },

  /**
   * 3. 状态重置模式：登出或页面卸载时恢复初态
   */
  resetState(state) {
    return {
      ...state,
      list: [],
      total: 0,
      currentUser: { id: null, name: '', roles: [] }
    };
  }
}

四、Effects：异步副作用与 Redux-Saga 实操

当业务逻辑涉及从后端接口加载数据、表单提交校验、多请求串行编排或读取跨模块状态时，必须交由 effects 处理。dva 的 effects 基于 Redux-Saga 实现，采用 ES6 Generator 函数语法（以星号 * 声明）。

1. 常用 Saga 操作符详解

每个 Effect 函数的第二个参数是一个对象，注入了常用的 Saga Effect 算子，最核心的包括三个：

• call(fn, ...args)：执行阻塞式异步调用。通常将请求 API 函数及其参数传给 call，Saga 中间件会自动等待其返回的 Promise resolve，并将解析后的值赋给变量。
• put(action)：发起一个 Action。在 Effect 内部，put 用于触发 Reducer 更新 state，或触发另一个 Effect。
• select(selector)：从全局 Redux State 树中提取数据，无需通过 UI 层逐层传递参数。

2. 实战范例：包含错误处理与状态提取的完整 Effect

以下代码演示了从读取当前状态的 token、发起分页查询，到异常捕获并调用 Reducer 的标准写法：

import { queryUserList, updateUserProfile } from '@/services/user';

export default {
  namespace: 'user',
  state: { list: [], total: 0, pageSize: 10 },
  effects: {
    /**
     * 加载用户列表：演示 select、call、put 链式配合
     */
    *fetchList({ payload }, { call, put, select }) {
      try {
        // 1. 从当前 model 获取已存的分页大小
        const pageSize = yield select(state => state.user.pageSize);

        // 2. 使用 call 调用异步请求服务
        const response = yield call(queryUserList, {
          page: payload?.page || 1,
          pageSize,
          ...payload
        });

        // 3. 请求成功，通过 put 派发至 reducers 进行同步保存
        if (response && response.code === 200) {
          yield put({
            type: 'save', // 同一 model 内部无需添加 'user/' 前缀
            payload: {
              list: response.data.list,
              total: response.data.total,
              page: payload?.page || 1
            }
          });
        }
      } catch (error) {
        console.error('Fetch list failed:', error);
        // 可在此处发起全局 notification 或降级处理
      }
    },

    /**
     * 更新资料并刷新当前列表：演示跨 Effect 调度
     */
    *updateAndRefresh({ payload }, { call, put }) {
      const res = yield call(updateUserProfile, payload);
      if (res && res.success) {
        // 执行完毕后触发当前 model 的 fetchList 重新拉取最新数据
        yield put({ type: 'fetchList', payload: { page: 1 } });
      }
    }
  }
};

五、Reducers 与 Effects 的机制差异对比

在 dva 开发中，最核心的原则就是明确 Reducers 只做同步纯计算，Effects 负责一切异步与业务调度。为了让概念边界一目了然，我们从底层机制到使用限制进行系统对照。

六、组件调用与 dva-loading 优雅实践

在 React 组件中接入 Model，需要利用 dva 提供的 connect 高阶函数将全局状态与派发方法注入组件的 props。

import React, { useEffect } from 'react';
import { connect } from 'dva';
import { Table, Button } from 'antd';

const UserManagement = ({ dispatch, userList, total, loading }) => {
  // 组件初次挂载时派发异步 Action 请求列表
  useEffect(() => {
    dispatch({
      type: 'user/fetchList',
      payload: { page: 1 }
    });
  }, [dispatch]);

  return (
    <div>
      <Table
        dataSource={userList}
        loading={loading}
        rowKey="id"
      />
    </div>
  );
};

// 映射全局 state 至组件 Props，推荐结合 dva-loading 自动获取加载态
export default connect((state) => ({
  userList: state.user.list,
  total: state.user.total,
  // 自动检测 user/fetchList 的执行挂起状态，无需在 state 维护 loading: boolean
  loading: state.loading.effects['user/fetchList'] || false,
}))(UserManagement);

七、开发流程规范与高频避坑自查

在实际项目迭代中，规范的开发自查步骤能拦截 90% 以上的数据流异常。按照“确定 State 结构 → 编写纯 Reducer → 编排异步 Effect → 绑定 UI”这一标准路径开发，能够确保代码逻辑清晰有序。

高频踩坑问题与排查清单