@chatbi-v/mocks

ChatBI Mock 数据模块，提供灵活的 JSON 和 SSE (Server-Sent Events) 数据模拟功能。

模块功能说明

• 响应策略管理: 支持 JSON、SSE (流式) 和 SSE-Page (分页流) 等多种响应模式。
• 数据生成器: 集成 Mock.js，支持丰富的模板语法和动态数据生成。
• 拦截器适配: 轻松接入 Axios 或其他请求库，实现无缝的本地模拟开发。
• 参数动态插值: 支持在模板中引用请求 Query 或 Body 参数。

安装和使用方法

安装

pnpm add @chatbi-v/mocks

使用示例

import { MockInterceptor } from '@chatbi-v/mocks';

const interceptor = new MockInterceptor();

// 注册 mock 规则
interceptor.register('GET /api/user', {
  type: 'json',
  responseSchema: {
    code: 200,
    data: { id: 1, name: '@cname' }
  }
});

// 在请求库中使用拦截器
// axios.interceptors.request.use(interceptor.getRequestInterceptor());

API 文档链接

请参考 Mock 模块详细文档。

开发注意事项

• 命名规范: 建议 Mock 文件以 .mock.ts 结尾。
• 数据一致性: 确保 Mock 返回的数据结构与后端 API 定义一致。
• 性能: SSE 模式下的 delay 参数不宜设置过大，以免影响开发体验。

特性

• 多种响应策略：支持 json (普通接口)、sse (流式接口)、sse-page (带分页的流式接口)。
• Mock.js 深度集成：完全支持 Mock.js 的模板语法（如 'data|8-12' 生成数组）。
• 动态模板插值：支持在 Mock 模板中使用 {{$query.param}} 引用请求参数。
• 自动扁平化：SSE 事件流自动扁平化处理，支持批量生成事件。

快速开始

1. 定义 Mock Schema

在 api/modules/chat.mock.ts 或其他 mock 文件中定义接口模拟规则：

import { SUCCESS_CODE } from '@chatbi/core';

export default {
  // 普通 JSON 接口
  getConversationList: {
    type: 'json',
    delay: 200,
    responseSchema: {
      code: SUCCESS_CODE,
      msg: 'success',
      'data|10': [{ id: '@increment', title: '@ctitle' }]
    }
  },

  // SSE 流式接口
  chat: {
    type: 'sse',
    responseSchema: {
      'data|3-5': [{
        event: 'data',
        data: { content: '@cparagraph', role: 'assistant' },
        delay: '@increment(100)'
      }]
    }
  },

  // SSE 分页接口 (适用于历史记录等场景)
  getHistory: {
    type: 'sse-page',
    responseSchema: {
      'data|8-12': [{ // 随机生成 8-12 条数据
        event: 'data',
        data: { 
          id: '@guid', 
          content: '@csentence',
          role: '@pick(["user", "assistant"])'
        },
        delay: 50
      }]
    },
    // 分页元数据事件（自动计算并在最后推送）
    pageEvent: {
      event: 'page',
      data: {
        pageNo: '{{$query.pageNo}}', // 引用请求参数
        pageSize: 20,
        total: 100,
        hasNext: true
      }
    }
  }
}

核心概念

策略类型 (type)

| 类型 | 描述 | |Data|说明| |---|---| | json | 默认类型。返回标准的 JSON 对象。 | | sse | 返回 Content-Type: text/event-stream。将 responseSchema 生成的数组扁平化后，按 delay 排序依次推送。 | | sse-page | 基于 sse，但在流的末尾会自动追加一个 page 事件，用于传递分页元数据。需要配合 pageEvent 字段使用。 |

模板增强功能

1. 数组范围生成

支持 Mock.js 的 Key 规则生成指定数量的事件。在 SSE 场景下，生成的数组会被自动展开（flatten），确保每个数组元素作为一个独立的 SSE 事件发送。

{
  'data|8-12': [ // 随机生成 8 到 12 个事件
    { event: 'data', ... }
  ]
}

2. 请求参数引用与计算

在字符串值中可以使用 {{$query.xxx}} 语法引用 URL 查询参数。支持简单的 JavaScript 表达式计算。

{
  // 假设请求 URL 为 ?pageNo=2
  pageNo: '{{$query.pageNo}}', // 结果: 2 (自动转换类型)
  offset: '{{$query.pageNo * 10}}', // 结果: 20
  desc: '当前是第 {{$query.pageNo}} 页' // 结果: "当前是第 2 页"
}

SSE 数据结构约定

为了配合前端的 StreamStrategy，SSE 事件通常遵循以下结构：

interface MockEvent {
  event: string; // 事件类型：data, log, error, page, todos
  data: any;     // 事件载荷
  delay?: number; // 延迟毫秒数（相对于流开始时间）
}