Mock 目录约定

目标

这一层的目标不是“写一个很大的假接口文件”，而是让本地在没有真实 API 时，也能按模块稳定联调，并且后续容易替换成真实接口。

环境切换

全局环境由配置文件控制，不在页面里单独切换：

• 本地开发：config/dev.js
• 生产构建：config/prod.js

当前使用 API_RUNTIME_ENV 控制：

• mock：当前构建下所有接口统一走本地 Mock
• production：当前构建下所有接口统一走真实接口

目录职责

• index.js 统一入口，只做请求上下文创建、路由分发和响应包装。
• modules/*.mock.js 按业务模块定义 handler。一个 handler 对应一个接口组合：method + action + type。
• shared/ 放公共能力，例如请求解析、响应包装、handler 匹配。
• stores/*.store.js 放有状态的 mock 数据，例如“已读/未读”“新增后列表变化”这类场景。
• fixtures/*.fixture.js 放静态样本和数据工厂，不做业务状态修改。

推荐写法

1. 先放静态样本

如果只是字段模板、列表假数据，先放到 fixtures/xxx.fixture.js。

2. 需要状态变化时再加 store

如果接口会互相影响，例如：

• 详情读取后列表变已读
• 新增后列表里能看到新增项
• 删除后再次查询不再返回

这类场景再在 stores/xxx.store.js 里维护状态。

3. handler 只做路由和调用

modules/*.mock.js 里尽量保持轻量：

• 判断命中哪个接口
• 调用 store / fixture
• 用 buildMockSuccess 或 buildMockError 返回

不要把大量假数据、复杂状态、通用工具都堆到 handler 里。

新增一个模块时的顺序

1. 新建 fixtures/xxx.fixture.js
2. 如果需要状态，再新建 stores/xxx.store.js
3. 新建 modules/xxx.mock.js
4. 在 modules/index.js 注册
5. 在 src/api/ 下补对应 API 方法
6. 在页面里直接按真实接口调用方式联调

handler 示例

export const exampleMockHandlers = [
  {
    action: 'example',
    type: 'list',
    method: 'GET',
    handle: ({ requestParams }) => buildMockSuccess({
      list: [],
      page: Number(requestParams.page || 0),
    }),
  },
]

维护原则

• 模块边界优先，不要再回到“大一统 mock 文件”
• 页面不关心 mock 细节，只调用正常的 xxxAPI
• 能放 fixture 的，不要直接写进 handler
• 能放 store 的状态，不要散在多个 handler 里各自维护
• mock 字段名尽量贴近未来真实接口，避免后面页面再改一轮