Skip to content

STACK_MIGRATION.md

Latest commit

 

History

History
147 lines (119 loc) · 3.47 KB

STACK_MIGRATION.md

File metadata and controls

147 lines (119 loc) · 3.47 KB

seq-fetch-web 技术栈迁移建议

当前状态

  • 框架: React 18.2.0
  • 语言: JavaScript
  • UI 库: Bootstrap 5.3.1 + react-bootstrap
  • 状态管理: Zustand
  • 数据获取: @tanstack/react-query
  • 路由: react-router-dom v6

问题诊断

网页空白原因

  1. 服务器进程不稳定 - start-dev.sh 启动的进程容易停止
  2. 可能的浏览器缓存问题
  3. 可能的 JavaScript 运行时错误

验证方法

# 检查服务器是否运行
curl http://localhost:3000/static/js/bundle.js -o /dev/null -w "Size: %{size_download} bytes\n"

# 正常应该返回约 7.8MB

方案 A: 迁移到 Vue 3 + TypeScript (推荐)

技术栈

{
  "framework": "Vue 3.4+",
  "language": "TypeScript 5+",
  "build": "Vite 5+",
  "ui": "Element Plus 2+",
  "state": "Pinia",
  "http": "Axios",
  "router": "Vue Router 4"
}

项目结构

frontend/
├── src/
│   ├── api/           # API 客户端
│   ├── components/    # 可复用组件
│   ├── composables/   # Composition API
│   ├── layouts/       # 布局组件
│   ├── router/        # 路由配置
│   ├── stores/        # Pinia stores
│   ├── types/         # TypeScript 类型
│   ├── views/         # 页面组件
│   ├── App.vue
│   └── main.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

优势

  1. 类型安全 - TypeScript 提供编译时检查
  2. 更好的 IDE 支持 - 自动补全、错误提示
  3. 更清晰的代码组织 - 单文件组件 (SFC)
  4. 更小的打包体积 - Vite 构建更快
  5. 中文友好 - 文档和社区支持好

迁移步骤

  1. 创建新的 Vue 3 项目
  2. 定义 TypeScript 类型（基于 seq-fetch API）
  3. 逐步迁移组件
  4. 测试并部署

方案 B: 升级到 React + TypeScript

技术栈

{
  "framework": "React 18+",
  "language": "TypeScript 5+",
  "build": "Vite 5+ / CRA",
  "ui": "Bootstrap 5 + react-bootstrap",
  "state": "Zustand",
  "http": "@tanstack/react-query + Axios"
}

优势

  1. 保留现有代码 - 只需添加类型
  2. 学习曲线低 - 团队已熟悉 React
  3. 生态成熟 - 大量库支持

方案对比

特性 React + JS (当前) React + TS Vue 3 + TS
类型安全 ❌ ✅ ✅
学习曲线 中 中 低
打包体积 大 中 小
构建速度 慢 中 快
开发体验 中 好 很好
迁移成本 - 低 中

推荐

推荐方案：Vue 3 + TypeScript

理由：

  1. seq-fetch 是 Python 库，前端用 TypeScript 可以更好地定义 API 类型
  2. Vue 3 的 Composition API 与 React Hooks 类似，但更简洁
  3. Element Plus 的组件质量优于 react-bootstrap
  4. Vite 构建速度远快于 webpack

快速开始 Vue 3 + TypeScript

# 创建新项目
npm create vite@latest frontend -- --template vue-ts
cd frontend

# 安装依赖
npm install vue-router pinia axios @element-plus/icons-vue

# 安装 Element Plus
npm install element-plus

# 启动开发服务器
npm run dev

当前问题修复

如果暂时不迁移，先修复当前问题：

  1. 确保服务器运行
cd seq-fetch-web
./start-dev.sh
  1. 清除浏览器缓存
  • Ctrl+Shift+R (Windows/Linux)
  • Cmd+Shift+R (Mac)
  1. 检查浏览器控制台错误
  • F12 打开开发者工具
  • 查看 Console 标签