makemd/docs/01_Architecture/Mock_Architecture.md

低侵入 Mock 架构设计

文档创建时间: 2026-03-19 (北京时间) 适用项目: Crawlful Hub 目标: 实现"不污染代码、AI上下文安全"的Mock方案

---

📋 目录

1. 核心原则
2. 架构概览
3. 前端Mock方案
4. 后端/BFF Mock方案
5. 目录规范
6. AI协作规范
7. 实施任务

---

核心原则

1. Mock ≠ 写死数据

❌ 错误做法: 在组件中直接写死数据

const data = [{ id: 1, name: 'Mock商品' }]

✅ 正确做法: 通过数据源抽象层获取

const data = await productDataSource.list()

2. Mock 必须"可插拔"

Mock 应该是:

• ✅ 可开启 / 可关闭
• ✅ 可替换 / 可隔离
• ✅ 环境变量控制

3. Mock 属于"数据源层"，不是"业务层"

业务代码 → DataSource抽象层 → (Mock/真实API)

---

架构概览

三层数据架构

┌─────────────────────────────────────────────────────────────┐
│                    前端 (React + Umi)                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   业务组件   │ → │ DataSource  │ → │  API/Mock   │     │
│  │             │    │   抽象层    │    │             │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              BFF 层 (服务编排层)                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Service   │ → │  Mock切换   │ → │ 真实/Mock   │     │
│  │             │    │             │    │   服务      │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    后端微服务层                               │
└─────────────────────────────────────────────────────────────┘

Mock 分布策略

层级	是否Mock	说明
前端	⚠️ 可选	推荐用MSW，保持业务代码纯净
DataSource	✅ 可切换	控制入口，环境变量驱动
BFF	✅ 主力Mock	最真实，前端无感知
后端	❌ 不建议	除非联调测试

---

前端Mock方案

方案对比

方案	侵入性	推荐度	适用场景
MSW (Mock Service Worker)	⭐ 最低	🥇 最推荐	前端开发、UI测试
DataSource抽象	⭐⭐ 低	🥈 推荐	需要自定义逻辑
本地Mock Server	⭐⭐⭐ 中	🥉 可选	团队共享Mock
硬编码	❌ 高	🚫 不推荐	绝对禁止

推荐方案: MSW + DataSource抽象

1. 目录结构

/dashboard/src
  /api                    ← 真实API封装
    product.ts
    user.ts
    order.ts
    certificate.ts
  /mock                   ← 所有Mock数据和拦截器
    /data                 ← Mock数据文件
      product.mock.ts
      user.mock.ts
      certificate.mock.ts
    msw.ts                ← MSW初始化配置
    browser.ts            ← 浏览器环境启动
    server.ts             ← Node/测试环境启动
  /services               ← 数据源抽象层
    productDataSource.ts
    userDataSource.ts
    certificateDataSource.ts
  /types                  ← 类型定义
    datasource.ts         ← DataSource接口定义

2. DataSource接口定义

// /dashboard/src/types/datasource.ts

/**
 * [MOCK-001] DataSource抽象接口
 * 所有数据源必须实现此接口
 * AI注意: 这是抽象层，不涉及具体实现
 */
export interface IDataSource<T, QueryParams = any> {
  list(params?: QueryParams): Promise<T[]>;
  detail(id: string): Promise<T | null>;
  create(data: Partial<T>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}

export interface ProductQueryParams {
  keyword?: string;
  category?: string;
  status?: string;
  page?: number;
  pageSize?: number;
}

export interface CertificateQueryParams {
  status?: string;
  type?: string;
  page?: number;
  pageSize?: number;
}

3. DataSource抽象层实现

// /dashboard/src/services/certificateDataSource.ts

import { Certificate } from '@/types/certificate';
import { IDataSource, CertificateQueryParams } from '@/types/datasource';

/**
 * [MOCK-002] 证书数据源抽象层
 * 通过环境变量自动切换Mock/真实API
 * AI注意: 这是唯一入口，业务代码必须调用此层
 */

// 真实API实现
class ApiCertificateDataSource implements IDataSource<Certificate, CertificateQueryParams> {
  async list(params?: CertificateQueryParams): Promise<Certificate[]> {
    const query = new URLSearchParams(params as any).toString();
    const response = await fetch(`/api/v1/certificate/certificates?${query}`);
    const result = await response.json();
    return result.data || [];
  }

  async detail(id: string): Promise<Certificate | null> {
    const response = await fetch(`/api/v1/certificate/certificates/${id}`);
    const result = await response.json();
    return result.data || null;
  }

  async create(data: Partial<Certificate>): Promise<Certificate> {
    const response = await fetch('/api/v1/certificate/certificates', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    const result = await response.json();
    return result.data;
  }

  async update(id: string, data: Partial<Certificate>): Promise<Certificate> {
    const response = await fetch(`/api/v1/certificate/certificates/${id}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    const result = await response.json();
    return result.data;
  }

  async delete(id: string): Promise<void> {
    await fetch(`/api/v1/certificate/certificates/${id}`, {
      method: 'DELETE',
    });
  }
}

// Mock实现 (完全独立文件)
class MockCertificateDataSource implements IDataSource<Certificate, CertificateQueryParams> {
  private mockData: Certificate[] = [
    {
      id: '1',
      name: 'CE认证证书',
      type: 'PRODUCT_CERT',
      status: 'APPROVED',
      fileUrl: '/files/ce-cert.pdf',
      fileName: 'CE-Certificate-2026.pdf',
      uploadDate: '2026-03-15',
      expiryDate: '2027-03-15',
      approvedBy: 'admin',
      approvedDate: '2026-03-16',
      productId: 'P001',
      productName: '工业温度传感器',
      notes: '欧盟市场准入认证',
    },
    // ... 更多Mock数据
  ];

  async list(params?: CertificateQueryParams): Promise<Certificate[]> {
    // 模拟网络延迟
    await new Promise(resolve => setTimeout(resolve, 300));
    
    let result = [...this.mockData];
    
    if (params?.status) {
      result = result.filter(item => item.status === params.status);
    }
    if (params?.type) {
      result = result.filter(item => item.type === params.type);
    }
    
    return result;
  }

  async detail(id: string): Promise<Certificate | null> {
    await new Promise(resolve => setTimeout(resolve, 200));
    return this.mockData.find(item => item.id === id) || null;
  }

  async create(data: Partial<Certificate>): Promise<Certificate> {
    await new Promise(resolve => setTimeout(resolve, 500));
    const newCert: Certificate = {
      id: `${Date.now()}`,
      ...data as Certificate,
      status: 'PENDING',
      uploadDate: new Date().toISOString().split('T')[0],
    };
    this.mockData.unshift(newCert);
    return newCert;
  }

  async update(id: string, data: Partial<Certificate>): Promise<Certificate> {
    await new Promise(resolve => setTimeout(resolve, 300));
    const index = this.mockData.findIndex(item => item.id === id);
    if (index === -1) throw new Error('Certificate not found');
    this.mockData[index] = { ...this.mockData[index], ...data };
    return this.mockData[index];
  }

  async delete(id: string): Promise<void> {
    await new Promise(resolve => setTimeout(resolve, 200));
    this.mockData = this.mockData.filter(item => item.id !== id);
  }
}

// 导出数据源实例 (环境变量控制)
const useMock = process.env.REACT_APP_USE_MOCK === 'true';

export const certificateDataSource: IDataSource<Certificate, CertificateQueryParams> = useMock
  ? new MockCertificateDataSource()
  : new ApiCertificateDataSource();

// 标记Mock状态 (用于调试)
export const __MOCK__ = useMock;

4. MSW配置

// /dashboard/src/mock/msw.ts

import { setupWorker, rest } from 'msw';
import { mockCertificates } from './data/certificate.mock';

/**
 * [MOCK-003] MSW Mock配置
 * 拦截HTTP请求，返回Mock数据
 * AI注意: 这是网络层拦截，业务代码完全无感知
 */

export const worker = setupWorker(
  // 证书列表
  rest.get('/api/v1/certificate/certificates', (req, res, ctx) => {
    const status = req.url.searchParams.get('status');
    const type = req.url.searchParams.get('type');
    
    let data = [...mockCertificates];
    if (status) data = data.filter(item => item.status === status);
    if (type) data = data.filter(item => item.type === type);
    
    return res(
      ctx.delay(300),
      ctx.json({
        success: true,
        data,
        total: data.length,
      })
    );
  }),

  // 证书详情
  rest.get('/api/v1/certificate/certificates/:id', (req, res, ctx) => {
    const { id } = req.params;
    const cert = mockCertificates.find(item => item.id === id);
    
    if (!cert) {
      return res(
        ctx.status(404),
        ctx.json({ success: false, error: '证书不存在' })
      );
    }
    
    return res(
      ctx.delay(200),
      ctx.json({ success: true, data: cert })
    );
  }),

  // 创建证书
  rest.post('/api/v1/certificate/certificates', async (req, res, ctx) => {
    const body = await req.json();
    const newCert = {
      id: `${Date.now()}`,
      ...body,
      status: 'PENDING',
      uploadDate: new Date().toISOString().split('T')[0],
    };
    
    return res(
      ctx.delay(500),
      ctx.json({ success: true, data: { id: newCert.id } })
    );
  }),

  // 更新证书状态
  rest.put('/api/v1/certificate/certificates/:id/status', async (req, res, ctx) => {
    const { id } = req.params;
    const { status, approvedBy } = await req.json();
    
    return res(
      ctx.delay(300),
      ctx.json({ success: true })
    );
  }),

  // 删除证书
  rest.delete('/api/v1/certificate/certificates/:id', (req, res, ctx) => {
    return res(
      ctx.delay(200),
      ctx.json({ success: true })
    );
  })
);

// /dashboard/src/mock/browser.ts
import { worker } from './msw';
export { worker };

// /dashboard/src/index.tsx (入口文件)

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

/**
 * [MOCK-004] MSW启动配置
 * 仅在REACT_APP_USE_MOCK=true时启用
 */
async function enableMocking() {
  if (process.env.REACT_APP_USE_MOCK !== 'true') {
    return;
  }
  
  const { worker } = await import('./mock/browser');
  return worker.start({
    onUnhandledRequest: 'bypass', // 未拦截的请求直接透传
  });
}

enableMocking().then(() => {
  const root = ReactDOM.createRoot(document.getElementById('root')!);
  root.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
});

5. 业务组件使用示例

// /dashboard/src/pages/Compliance/index.tsx

import { certificateDataSource } from '@/services/certificateDataSource';

const ComplianceManagement: React.FC = () => {
  const fetchData = useCallback(async () => {
    setLoading(true);
    try {
      // 调用DataSource层，完全无感知是Mock还是真实API
      const data = await certificateDataSource.list({
        status: activeStatus,
        type: activeType,
      });
      setCertificates(data);
    } catch (error) {
      message.error('获取证书列表失败');
    } finally {
      setLoading(false);
    }
  }, [activeStatus, activeType]);

  const handleUploadSubmit = async () => {
    try {
      const values = await uploadForm.validateFields();
      await certificateDataSource.create({
        name: values.name,
        type: values.type,
        expiryDate: values.expiryDate.format('YYYY-MM-DD'),
        productId: values.productId,
        productName: values.productName,
        notes: values.notes,
      });
      message.success('证书上传成功');
      fetchData();
    } catch (error) {
      message.error('上传失败');
    }
  };

  // ... 其他逻辑
};

---

后端/BFF Mock方案

架构设计

BFF层
  ├─ Service (业务逻辑)
  ├─ Mock切换器 (环境变量控制)
  ├─ 真实API客户端
  └─ Mock服务

实现示例

// /server/src/bff/services/certificateService.ts

import { CertificateService as RealCertificateService } from '../../services/CertificateService';
import { MockCertificateService } from '../mock/certificateMock';

/**
 * [MOCK-005] BFF层证书服务
 * 通过环境变量自动切换Mock/真实服务
 */

const useMock = process.env.USE_MOCK === 'true';

export const certificateService = useMock
  ? new MockCertificateService()
  : new RealCertificateService();

// 类型导出，确保调用方类型安全
export type ICertificateService = typeof certificateService;

// /server/src/bff/mock/certificateMock.ts

import { ICertificateService } from '../services/certificateService';

/**
 * [MOCK-006] BFF层Mock服务
 * 完全独立的Mock实现
 * AI注意: 这是Mock实现，不是真实业务逻辑
 */

export class MockCertificateService implements ICertificateService {
  private mockData = [
    // ... Mock数据
  ];

  async query(options: any) {
    await this.delay(300);
    return {
      items: this.mockData,
      total: this.mockData.length,
    };
  }

  async getById(id: string, tenantId: string, shopId: string) {
    await this.delay(200);
    return this.mockData.find(item => item.id === id) || null;
  }

  async create(input: any) {
    await this.delay(500);
    const id = `mock-${Date.now()}`;
    // ... 创建逻辑
    return id;
  }

  private delay(ms: number) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

---

目录规范

前端目录规范

/dashboard/src
  /mock                   ← 所有Mock相关
    /data                 ← Mock数据定义
      *.mock.ts
    msw.ts                ← MSW配置
    browser.ts            ← 浏览器入口
    server.ts             ← Node/测试入口
    README.md             ← Mock使用说明
  /services               ← DataSource抽象层
    *DataSource.ts
  /api                    ← 真实API封装
    *.ts

后端目录规范

/server/src
  /bff                    ← BFF层
    /mock                 ← Mock服务
      *.ts
    /services             ← 服务层
      *.ts
    /api                  ← API客户端
      *.ts
  /services               ← 真实服务
    *.ts

标记规范

所有Mock文件必须包含以下标记:

/**
 * [MOCK-XXX] 功能描述
 * AI注意: 这是Mock实现，不是真实业务逻辑
 * 仅在USE_MOCK=true时启用
 */

// 或者

// [MOCK] 此文件为Mock数据，AI请勿当作真实业务逻辑

---

AI协作规范

1. Mock文件识别规则

AI在分析代码时:

• ✅ 忽略 /mock 目录下所有文件
• ✅ 忽略包含 [MOCK] 标记的文件
• ✅ 忽略 __MOCK__ 变量为真的代码路径

2. 业务代码规范

AI生成业务代码时必须:

• ✅ 调用 DataSource 抽象层
• ✅ 不直接调用 API 或 Mock
• ✅ 不硬编码任何数据

3. 文档声明

## Mock使用规范

1. 所有Mock数据必须放 `/mock` 目录
2. DataSource层是唯一业务入口
3. `USE_MOCK=true` 时才启用Mock
4. AI不得将Mock数据当作真实业务逻辑
5. Mock不代表真实接口结构，仅用于UI开发

---

实施任务

任务清单

任务ID	任务描述	涉及文件	优先级	状态
MOCK-001	创建DataSource接口定义	/dashboard/src/types/datasource.ts	P0	⏳ 待实现
MOCK-002	实现证书DataSource	/dashboard/src/services/certificateDataSource.ts	P0	⏳ 待实现
MOCK-003	配置MSW拦截器	/dashboard/src/mock/msw.ts	P0	⏳ 待实现
MOCK-004	入口文件MSW启动	/dashboard/src/index.tsx	P0	⏳ 待实现
MOCK-005	BFF层Mock切换器	/server/src/bff/services/*.ts	P1	⏳ 待实现
MOCK-006	BFF层Mock服务	/server/src/bff/mock/*.ts	P1	⏳ 待实现
MOCK-007	产品模块DataSource	/dashboard/src/services/productDataSource.ts	P1	⏳ 待实现
MOCK-008	订单模块DataSource	/dashboard/src/services/orderDataSource.ts	P1	⏳ 待实现
MOCK-009	用户模块DataSource	/dashboard/src/services/userDataSource.ts	P1	⏳ 待实现
MOCK-010	库存模块DataSource	/dashboard/src/services/inventoryDataSource.ts	P1	⏳ 待实现
MOCK-011	环境变量配置	.env.development, .env.production	P0	⏳ 待实现
MOCK-012	文档完善	docs/01_Architecture/Mock_Architecture.md	P0	✅ 已完成
MOCK-013	自动选品模块Mock数据	/dashboard/src/mock/data/productSelection.mock.ts	P0	✅ 已完成
MOCK-014	自动选品DataSource	/dashboard/src/services/productSelectionDataSource.ts	P0	✅ 已完成
MOCK-015	自动选品页面Mock集成	/dashboard/src/pages/AutoProductSelection/index.tsx	P0	✅ 已完成

环境变量配置

# .env.development (开发环境)
REACT_APP_USE_MOCK=true          # 前端启用Mock
USE_MOCK=true                    # 后端启用Mock

# .env.production (生产环境)
REACT_APP_USE_MOCK=false         # 前端禁用Mock
USE_MOCK=false                   # 后端禁用Mock

快速启动命令

# 开发模式 (带Mock)
npm run dev:mock

# 开发模式 (真实API)
npm run dev

# 生产构建
npm run build

---

优势总结

特性	描述
🎯 零侵入	业务层完全不感知Mock
🔄 可切换	环境变量一键切换Mock/真实API
🤖 AI安全	Mock独立文件 + 文档规范
📦 可扩展	支持MSW、BFF Mock、本地Mock Server
🧪 可测试	统一接口便于单元测试
📝 可维护	目录清晰，职责分离

---

附录

相关文档

• 项目特定规则
• AI协作协议
• Task_Overview

更新记录

时间	版本	更新内容
2026-03-19	v1.0	初始版本，创建完整Mock架构设计

---

本文档遵循 Crawlful Hub 项目规范，所有Mock实现必须遵守"低侵入、AI安全"原则。