DeepTrace

技术栈与开发方式

技术栈

• 前端框架: React 19.1.0
• UI 库: Ant Design 5.25.4
• 构建工具: Umi Max 4.3.24
• 开发语言: TypeScript 5.6.3
• 样式方案: antd-style 3.7.0
• 图表库: @ant-design/plots 2.6.0
• 地图库: @antv/l7 2.22.7, @antv/l7-react 2.4.3
• 国际化: 支持多语言（zh-CN, en-US, zh-TW, ja-JP, pt-BR, id-ID, fa-IR, bn-BD）

开发方式

• 依赖管理: 使用 npm 或 yarn
• 代码质量: 使用 Biome 进行代码 lint
• Git 钩子: 使用 Husky 管理 git 钩子
• 测试: 使用 Jest 进行单元测试
• API 管理: 支持 OpenAPI 规范
• 构建方式: 使用 Umi Max 进行构建和优化

构建方式分析

构建工具

• Umi Max: 基于 Umi 的企业级前端构建方案，提供了完整的构建、部署和开发体验
• TypeScript 支持: 内置 TypeScript 编译和类型检查
• Webpack: 底层使用 Webpack 进行资源打包和优化

构建流程

1. 依赖分析: 分析项目依赖，生成依赖图
2. 代码编译: 编译 TypeScript、Less 等文件
3. 资源处理: 处理图片、字体等静态资源
4. 代码分割: 自动进行代码分割，优化首屏加载速度
5. Tree-shaking: 移除未使用的代码，减少包体积
6. 代码压缩: 压缩 JavaScript、CSS 等文件
7. 生成产物: 生成最终的构建产物到 dist 目录

构建优化策略

• 按需加载: 支持路由级别的代码分割，实现按需加载
• 缓存策略: 生成带有 hash 值的文件名，优化浏览器缓存
• CDN 支持: 支持配置 CDN 路径，加速静态资源加载
• 性能分析: 提供构建产物分析工具，帮助识别性能瓶颈
• 多环境构建: 支持不同环境的构建配置（开发、测试、生产）

构建配置

• 配置文件: config/config.ts 是主要的构建配置文件
• 环境变量: 支持通过环境变量控制构建行为
• 自定义插件: 支持通过插件扩展构建功能

启动方法

环境准备

安装依赖：

npm install

或

yarn

开发环境

启动开发服务器：

npm start

或

npm run dev

构建项目

构建生产版本：

npm run build

构建配置

• 构建工具: 使用 Umi Max 进行构建
• 构建产物: 生成在 dist 目录中
• 构建优化: 自动进行代码分割、tree-shaking 和压缩
• 环境变量: 根据 NODE_ENV 自动切换环境配置

预览构建

构建并预览生产版本：

npm run preview

预览配置

• 预览端口: 默认使用 8000 端口
• 预览服务器: 使用 max preview 命令启动本地预览服务器

构建分析

分析构建产物大小：

npm run analyze

分析工具

• 使用 rollup-plugin-visualizer 生成构建产物分析报告
• 报告将显示各个模块的大小和依赖关系

部署

构建并部署到 GitHub Pages：

npm run deploy

部署流程

1. 执行 npm run build 构建生产版本
2. 执行 gh-pages -d dist 将构建产物部署到 GitHub Pages

代码检查

检查代码风格：

npm run lint

运行测试

运行单元测试：

npm test

通用方法

请求方法

项目使用 Umi 的 request 方案进行 API 请求，封装在 services 目录中：

基础 API 封装

• 文件: services/ant-design-pro/api.ts
• 功能: 封装了常用的 API 接口，包括：
  • currentUser(): 获取当前用户信息
  • outLogin(): 退出登录
  • login(body): 登录接口
  • getNotices(): 获取通知列表
  • rule(params): 获取规则列表
  • updateRule(options): 更新规则
  • addRule(options): 新建规则
  • removeRule(options): 删除规则

登录相关 API

• 文件: services/ant-design-pro/login.ts
• 功能: 处理登录相关的 API 调用

Swagger 生成的 API 客户端

• 目录: services/swagger/
• 功能: 根据 Swagger 规范自动生成的 API 客户端，支持 pet、store、user 等模块

使用示例

import { currentUser, login } from '@/services/ant-design-pro/api';

// 获取当前用户信息
const userInfo = await currentUser();

// 登录
const loginResult = await login({ username: 'admin', password: 'password' });

钩子方法

项目自定义了一些 React Hooks，位于 src/hooks 目录：

核心 Hooks

• useMemo: 对 React.useMemo 的封装，用于优化性能
• useCallback: 对 React.useCallback 的封装，用于缓存函数引用

实现示例

import { useMemo, useCallback } from '@/hooks';

// 使用 useMemo 缓存计算结果
const expensiveValue = useMemo(() => {
  // 执行昂贵的计算
  return calculateExpensiveValue(a, b);
}, [a, b]);

// 使用 useCallback 缓存函数
const handleClick = useCallback(() => {
  // 处理点击事件
}, [dependencies]);

渲染方法

项目采用现代 React 渲染方式，支持多种样式方案：

React 函数组件

• 使用 ES6 箭头函数和函数声明创建组件
• 支持 TypeScript 类型定义
• 组件示例：

  const HeaderDropdown: React.FC<HeaderDropdownProps> = ({
    overlayClassName: cls,
    ...restProps
  }) => {
    const { styles } = useStyles();
    return (
      <Dropdown
        overlayClassName={classNames(styles.dropdown, cls)}
        {...restProps}
      />
    );
  };

CSS-in-JS 样式方案

• 使用 antd-style 库的 createStyles 方法创建样式
• 支持主题变量和响应式设计
• 样式示例：

  const useStyles = createStyles(({ token }) => {
    return {
      dropdown: {
        [`@media screen and (max-width: ${token.screenXS}px)`]: {
          width: '100%',
        },
      },
    };
  });

Less 样式文件

• 支持传统的 Less 样式文件
• 用于全局样式和复杂样式定义
• 示例文件：src/global.less、各页面的 .less 文件

类名处理

• 使用 classNames 库处理条件类名
• 支持动态类名组合
• 示例：

  <Dropdown
    overlayClassName={classNames(styles.dropdown, cls)}
    {...restProps}
  />

目录结构

new-deeptrace/
├── config/                # 项目配置
│   ├── config.ts          # 主配置文件
│   ├── defaultSettings.ts # 默认设置
│   ├── oneapi.json        # OneAPI 配置
│   ├── proxy.ts           # 代理配置
│   └── routes.ts          # 路由配置
├── mock/                  # 模拟数据
│   ├── analysis.mock.ts   # 分析页面模拟数据
│   ├── listTableList.ts   # 列表页模拟数据
│   ├── monitor.mock.ts    # 监控页面模拟数据
│   ├── notices.ts         # 通知模拟数据
│   ├── requestRecord.mock.js # 请求记录模拟数据
│   ├── route.ts           # 路由模拟
│   ├── user.ts            # 用户模拟数据
│   └── workplace.mock.ts  # 工作台模拟数据
├── public/                # 静态资源
│   ├── icons/             # 图标
│   ├── scripts/           # 脚本
│   ├── CNAME              # CNAME 文件
│   ├── favicon.ico        # 网站图标
│   ├── logo.svg           # 网站 Logo
│   └── pro_icon.svg       # Pro 图标
├── src/                   # 源代码
│   ├── components/        # 公共组件
│   ├── hooks/             # 自定义 Hooks
│   ├── locales/           # 国际化资源
│   ├── pages/             # 页面
│   │   ├── account/       # 账户相关页面
│   │   ├── dashboard/     # 仪表盘
│   │   ├── exception/     # 异常页面
│   │   ├── form/          # 表单页面
│   │   ├── list/          # 列表页面
│   │   ├── profile/       # 个人资料
│   │   ├── result/        # 结果页面
│   │   ├── table-list/    # 表格列表
│   │   └── user/          # 用户相关页面
│   ├── services/          # API 服务
│   ├── access.ts          # 权限配置
│   ├── app.tsx            # 应用入口
│   ├── global.less        # 全局样式
│   ├── global.style.ts    # 全局样式（CSS-in-JS）
│   ├── global.tsx         # 全局配置
│   ├── loading.tsx        # 加载组件
│   ├── manifest.json      # PWA 配置
│   ├── requestErrorConfig.ts # 请求错误配置
│   ├── service-worker.js  # Service Worker
│   └── typings.d.ts       # 类型定义
├── tests/                 # 测试文件
│   └── setupTests.jsx     # 测试设置
├── types/                 # 类型定义
│   ├── cache/             # 缓存类型
│   └── index.d.ts         # 全局类型定义
├── .commitlintrc.js       # Commitlint 配置
├── .editorconfig          # Editor 配置
├── .gitignore             # Git 忽略文件
├── .lintstagedrc          # Lint-staged 配置
├── .npmrc                 # NPM 配置
├── README.md              # 项目说明
├── biome.json             # Biome 配置
├── jest.config.ts         # Jest 配置
├── package.json           # 项目依赖
└── tsconfig.json          # TypeScript 配置