项目结构分析.md 10 KB
Label Studio Web 前端项目结构分析
项目概述
这是 Label Studio 的纯前端 Web 项目，基于 NX Monorepo 架构，使用 React + TypeScript 技术栈。项目已移除后端、Docker 等配置，专注于前端开发。
技术栈
- 构建工具: NX (Monorepo 管理)
- 前端框架: React 18.3.1
- 语言: TypeScript 5.8.3
- 状态管理:
- MobX + mobx-state-tree (编辑器核心)
- Jotai (应用层状态管理)
- UI 组件库:
- Ant Design 4.x
- Radix UI (现代化组件)
- Shadcn/ui (基于 Radix UI)
- 样式方案:
- Tailwind CSS 3.4.3
- SCSS Modules
- 打包工具: Webpack 5
- 测试框架:
- Jest (单元测试)
- Cypress (E2E 测试)
- 代码质量:
- Biome (代码检查和格式化)
- Stylelint (样式检查)
项目结构
web/
├── apps/ # 应用层
│ ├── labelstudio/ # 主应用
│ ├── labelstudio-e2e/ # E2E 测试
│ └── playground/ # 独立演示应用
├── libs/ # 共享库
│ ├── editor/ # 标注编辑器核心
│ ├── datamanager/ # 数据管理器
│ ├── ui/ # UI 组件库
│ ├── core/ # 核心工具库
│ ├── app-common/ # 应用通用模块
│ ├── frontend-test/ # 测试工具库
│ └── storybook/ # Storybook 配置
├── tools/ # 构建工具
├── dist/ # 构建输出
└── 配置文件
核心应用 (Apps)
1. apps/labelstudio - 主应用
用途: Label Studio 的完整前端应用
特点:
- 集成所有功能库和组件
- 包含完整的用户界面、路由、页面管理
- 需要配合后端 API 使用（通过环境变量配置）
- 构建输出:
dist/apps/labelstudio/
启动命令:
yarn ls:dev # 开发模式（支持 HMR）
yarn ls:watch # 监听模式
yarn ls:build # 生产构建
2. apps/playground - 独立演示应用
用途: 标注编辑器的独立测试和演示环境
特点:
- 完全独立运行（standalone 模式）
- 无需后端支持
- 主要用于测试和演示标注编辑器功能
- 可通过 URL 参数加载配置
启动命令:
yarn playground:serve # 开发服务器
yarn playground:build # 生产构建
3. apps/labelstudio-e2e - E2E 测试
用途: 端到端测试套件
特点:
- 基于 Cypress
- 测试主应用的完整工作流
运行命令:
yarn ls:e2e # 运行 E2E 测试
共享库 (Libs)
1. libs/editor - 标注编辑器核心 ⭐
功能: 数据标注的核心功能库
技术栈:
- React + mobx-state-tree
- Konva (画布渲染)
- Ant Design (UI 组件)
特点:
- 可独立使用和嵌入到其他应用
- 支持多种数据类型标注：
- 图像（矩形、多边形、关键点、分割等）
- 音频（区域标注、分类）
- 文本（NER、分类、关系抽取）
- 视频（时间轴标注）
- 时间序列数据
- 包含标注工具、画布、控件等完整功能
- 可通过 XML 配置定义标注界面
开发命令:
yarn lsf:watch # 监听构建
yarn lsf:serve # 独立运行
yarn lsf:unit # 单元测试
yarn lsf:integration # 集成测试
yarn lsf:e2e # E2E 测试
2. libs/datamanager - 数据管理器
功能: 数据探索和管理工具
特点:
- 数据列表展示（虚拟滚动优化）
- 高级过滤和排序
- 批量操作支持
- 数据可视化
- 与编辑器深度集成
技术栈:
- React + MobX
- react-window (虚拟滚动)
- @tanstack/react-table (表格)
开发命令:
yarn dm:watch # 监听构建
yarn dm:unit # 单元测试
3. libs/ui - UI 组件库 ⭐
功能: 共享的 UI 组件库
特点:
- 基于 Radix UI 和 Tailwind CSS
- 包含 Shadcn/ui 组件
- 设计令牌系统（从 Figma 自动生成）
- 完整的 Storybook 文档
- 支持深色模式
组件类型:
- 基础组件（Button, Input, Select 等）
- 布局组件（Dialog, Popover, Tabs 等）
- 数据展示组件（Table, Toast 等）
开发命令:
yarn ui:serve # 启动 Storybook
yarn design-tokens # 重新生成设计令牌
4. libs/core - 核心工具库
功能: 跨应用的通用工具和类型定义
特点:
- 工具函数集合
- TypeScript 类型定义
- 常量和配置
- 无 UI 依赖
5. libs/app-common - 应用通用模块
功能: 应用级别的共享代码
特点:
- 跨应用的页面级组件
- 共享的业务逻辑
- 可以依赖其他 libs，但不能被其他 libs 依赖
6. libs/frontend-test - 测试工具库
功能: 测试辅助工具和 Helpers
特点:
- Cypress 测试 Helpers
- 测试工具函数
- Mock 数据生成
7. libs/storybook - Storybook 配置
功能: Storybook 的全局配置和插件
特点:
- 统一的 Storybook 配置
- 自定义插件和装饰器
- 主题配置
依赖关系图
apps/labelstudio
├── libs/editor (标注编辑器)
├── libs/datamanager (数据管理)
├── libs/ui (UI 组件)
├── libs/core (核心工具)
└── libs/app-common (应用通用)
apps/playground
├── libs/editor (标注编辑器)
├── libs/ui (UI 组件)
└── libs/core (核心工具)
libs/app-common
├── libs/ui
├── libs/core
└── libs/editor
libs/datamanager
├── libs/ui
└── libs/core
libs/editor
├── libs/ui
└── libs/core
libs/ui
└── libs/core
依赖规则:
apps/可以导入任何libs/libs/不能导入apps/libs/app-common可以导入其他libs/- 其他
libs/不能导入libs/app-common - 避免循环依赖
开发工作流
启动开发环境
# 1. 安装依赖
yarn install --frozen-lockfile
# 2. 启动主应用（开发模式）
yarn dev
# 或
yarn ls:dev
# 3. 启动 Storybook（UI 组件开发）
yarn ui:serve
# 4. 启动 Playground（编辑器测试）
yarn playground:serve
构建生产版本
# 构建主应用
yarn build
# 或
yarn ls:build
# 构建 Playground
yarn playground:build
# 构建 Storybook
yarn storybook:build
测试
# 运行所有单元测试
yarn test:unit
# 运行特定模块测试
yarn ls:unit # 主应用
yarn lsf:unit # 编辑器
yarn dm:unit # 数据管理器
# 运行集成测试
yarn lsf:integration
# 运行 E2E 测试
yarn test:e2e
yarn ls:e2e # 主应用 E2E
yarn lsf:e2e # 编辑器 E2E
# 测试覆盖率
yarn test:unit:coverage
代码质量检查
# 代码检查和自动修复
yarn lint
# SCSS 检查和自动修复
yarn lint-scss
# 生成文档
yarn docs
配置文件说明
核心配置
nx.json: NX 工作区配置package.json: 项目依赖和脚本tsconfig.base.json: TypeScript 基础配置webpack.config.js: Webpack 构建配置tailwind.config.js: Tailwind CSS 配置biome.json: Biome 代码检查配置.stylelintrc.json: Stylelint 样式检查配置
设计令牌
design-tokens.json: 从 Figma 导出的设计令牌components.json: Shadcn/ui 组件配置
测试配置
jest.config.ts: Jest 测试配置jest.preset.js: Jest 预设配置cypress.config.ts: Cypress E2E 测试配置
独立性分析
✅ 可以独立运行的部分
Playground 应用 (完全独立)
- 无需后端支持
- 可通过 URL 参数加载配置
- 适合演示和测试标注功能
Editor 库 (可嵌入)
- 可作为独立库嵌入到其他项目
- 支持 standalone 模式
- 可通过 npm 包方式使用
UI 组件库 (完全独立)
- 通过 Storybook 独立开发和预览
- 可作为独立组件库使用
扩展和定制
创建新应用
# 使用 NX 生成器创建新应用
nx generate @nx/react:application my-app --style=scss --bundler=webpack
创建新库
# 创建新的共享库
nx generate @nx/react:library my-lib --style=scss --unitTestRunner=jest
添加新组件
# 在 UI 库中添加新组件
nx generate @nx/react:component my-component --project=ui --style=scss
环境变量配置
开发环境 HMR 配置
创建 .env 文件（可选）:
# 启用热模块替换
FRONTEND_HMR=true
# HMR 服务器地址（默认: http://localhost:8010）
FRONTEND_HOSTNAME=http://localhost:8010
# Django 后端地址（默认: http://localhost:8080）
DJANGO_HOSTNAME=http://localhost:8080
DataManager 自定义配置
参考 libs/datamanager/.env.example:
# API 网关地址
NX_API_GATEWAY=http://localhost:8080/api/dm
# Label Studio 访问令牌
LS_ACCESS_TOKEN=your_access_token
性能优化
构建优化
- 使用 NX 缓存加速构建
- Webpack 代码分割
- Tree-shaking 移除未使用代码
- CSS 压缩和优化
运行时优化
- React.memo 减少重渲染
- 虚拟滚动处理大数据集
- 懒加载路由和组件
- 图片和资源优化
常见问题
1. 如何连接后端 API？
主应用需要配置后端 API 地址，通常通过环境变量或构建时配置。
2. 如何独立使用编辑器？
使用 Playground 应用或将 @humansignal/editor 作为 npm 包引入你的项目。
3. 如何添加新的标注类型？
在 libs/editor 中扩展标注工具和控件，参考现有实现。
4. 如何自定义 UI 主题？
修改 design-tokens.json 和 Tailwind 配置，重新生成设计令牌。
5. 如何运行测试？
yarn test:unit # 所有单元测试
yarn test:integration # 集成测试
yarn test:e2e # E2E 测试
总结
这是一个现代化的前端 Monorepo 项目，具有以下特点：
- ✅ 模块化架构: 清晰的应用和库分离
- ✅ 可复用性: 核心功能可独立使用
- ✅ 类型安全: 完整的 TypeScript 支持
- ✅ 现代工具链: NX + Webpack + Biome
- ✅ 完善的测试: 单元测试 + 集成测试 + E2E 测试
- ✅ 组件文档: Storybook 支持
- ✅ 设计系统: 基于 Figma 的设计令牌
项目专注于前端开发，可以独立开发和测试，也可以与后端 API 集成使用。