eafonyang
262 lines
7.7 KiB
Markdown
262 lines
7.7 KiB
Markdown
# Dashboard 后端迁移计划：JS + Sequelize → TypeScript + Drizzle
|
||
|
||
## 概述
|
||
|
||
将 dashboard 后端从 JavaScript + Sequelize（CommonJS）迁移至 TypeScript + Drizzle ORM（ESM），提升类型安全性和开发体验，同时为官网 CMS 模块（`/api/www/*`）奠定技术基础。
|
||
|
||
**迁移策略**：渐进式，逐模块替换，确保每个阶段可独立验证。
|
||
|
||
---
|
||
|
||
## 现有代码清单
|
||
|
||
### Models（9 个表）
|
||
|
||
| 文件 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| Brand.js | brand | 耳机品牌 |
|
||
| Model.js | model | 耳机型号 |
|
||
| Ota.js | ota | OTA 固件 |
|
||
| OtaTargetDevice.js | ota_target_device | OTA 目标设备 |
|
||
| BlackList.js | black_list | 黑名单 |
|
||
| DashboardUser.js | dashboard_user | 后台用户 |
|
||
| ShareCodeLog.js | share_code_log | 分享码日志 |
|
||
| UserActive.js | user_active | 用户活跃记录 |
|
||
| UserDevice.js | user_device | 用户设备 |
|
||
|
||
### Routes（9 个路由模块）
|
||
|
||
| 文件 | 体量 | 复杂度 | 迁移优先级 |
|
||
|------|------|--------|-----------|
|
||
| auth.js | 3.6KB | ⭐ | P1（先迁） |
|
||
| shareCodeLogs.js | 2.7KB | ⭐ | P1 |
|
||
| brands.js | 4.8KB | ⭐ | P1 |
|
||
| blacklist.js | 6.6KB | ⭐⭐ | P2 |
|
||
| users.js | 6.2KB | ⭐⭐ | P2 |
|
||
| otaTargetDevice.js | 7.8KB | ⭐⭐ | P2 |
|
||
| dashboard.js | 9.5KB | ⭐⭐ | P2 |
|
||
| ota.js | 9.9KB | ⭐⭐⭐ | P3 |
|
||
| models.js | 26.1KB | ⭐⭐⭐ | P3（最后） |
|
||
|
||
### Services（6 个）
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| curveClient.js | 频响曲线 API 客户端 |
|
||
| eqCacheStorage.js | Redis EQ 缓存 |
|
||
| measurementStorage.js | S3 测量文件存储 |
|
||
| otaStorage.js | OTA 固件存储 |
|
||
| squiglink.js | Squiglink 数据服务 |
|
||
| userBootstrap.js | 超级管理员初始化 |
|
||
|
||
### 其他
|
||
|
||
| 模块 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| validators/ | 5 个 | 已使用 Zod，迁移成本极低 |
|
||
| middleware/ | auth.js, bodyLimit.js | JWT 鉴权 + 请求体限制 |
|
||
| config/ | database.js, env.js, loadEnv.js, logger.js, redis.js | 基础配置 |
|
||
| utils/ | 3 个 | 工具函数 |
|
||
|
||
---
|
||
|
||
## 迁移阶段
|
||
|
||
### Phase 1：搭建 TypeScript 基础设施
|
||
|
||
**目标**：项目能运行 TS，新旧代码可共存。
|
||
|
||
- [ ] 安装依赖：`typescript`、`tsx`、`drizzle-orm`、`drizzle-kit`、`@types/express`、`@types/cors`
|
||
- [ ] 移除依赖：`sequelize`（Phase 4 最后移除）
|
||
- [ ] 创建 `tsconfig.json`
|
||
|
||
```jsonc
|
||
{
|
||
"compilerOptions": {
|
||
"target": "ES2022",
|
||
"module": "ESNext",
|
||
"moduleResolution": "bundler",
|
||
"esModuleInterop": true,
|
||
"strict": true,
|
||
"outDir": "dist",
|
||
"rootDir": "src",
|
||
"skipLibCheck": true,
|
||
"resolveJsonModule": true,
|
||
"declaration": true,
|
||
"paths": { "@/*": ["./src/*"] }
|
||
},
|
||
"include": ["src/**/*.ts"],
|
||
"exclude": ["node_modules", "dist"]
|
||
}
|
||
```
|
||
|
||
- [ ] 创建 `drizzle.config.ts`
|
||
|
||
```ts
|
||
import { defineConfig } from 'drizzle-kit';
|
||
|
||
export default defineConfig({
|
||
schema: './src/schemas/index.ts',
|
||
out: './drizzle',
|
||
dialect: 'mysql',
|
||
dbCredentials: {
|
||
host: process.env.DATABASE_HOST || 'localhost',
|
||
port: Number(process.env.DATABASE_PORT || 3306),
|
||
user: process.env.DATABASE_USER || 'root',
|
||
password: process.env.DATABASE_PASSWORD || '',
|
||
database: process.env.DATABASE_NAME || 'audio',
|
||
},
|
||
});
|
||
```
|
||
|
||
- [ ] 更新 `package.json` scripts：
|
||
|
||
```json
|
||
{
|
||
"type": "module",
|
||
"scripts": {
|
||
"dev": "tsx watch src/app.ts",
|
||
"build": "tsc",
|
||
"start": "node dist/app.js",
|
||
"db:generate": "drizzle-kit generate",
|
||
"db:migrate": "drizzle-kit migrate",
|
||
"db:push": "drizzle-kit push",
|
||
"db:studio": "drizzle-kit studio"
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] 创建 `src/config/database.ts`（Drizzle 连接）
|
||
|
||
```ts
|
||
import { drizzle } from 'drizzle-orm/mysql2';
|
||
import mysql from 'mysql2/promise';
|
||
import * as schema from '../schemas';
|
||
|
||
const pool = mysql.createPool({
|
||
host: process.env.DATABASE_HOST || 'localhost',
|
||
port: Number(process.env.DATABASE_PORT || 3306),
|
||
user: process.env.DATABASE_USER || 'root',
|
||
password: process.env.DATABASE_PASSWORD || '',
|
||
database: process.env.DATABASE_NAME || 'audio',
|
||
charset: 'utf8mb4',
|
||
waitForConnections: true,
|
||
connectionLimit: 10,
|
||
});
|
||
|
||
export const db = drizzle(pool, { schema, mode: 'default' });
|
||
```
|
||
|
||
**验证**：`tsx src/app.ts` 能正常启动（此时仍用旧 JS 代码）。
|
||
|
||
---
|
||
|
||
### Phase 2：迁移 Models → Drizzle Schema
|
||
|
||
**目标**：所有表定义用 Drizzle schema 表达，生成初始迁移。
|
||
|
||
- [ ] 创建 `src/schemas/` 目录
|
||
- [ ] 逐表编写 Drizzle schema：
|
||
|
||
```ts
|
||
// src/schemas/brand.ts
|
||
import { mysqlTable, int, varchar, datetime } from 'drizzle-orm/mysql-core';
|
||
import { sql } from 'drizzle-orm';
|
||
|
||
export const brands = mysqlTable('brand', {
|
||
id: int('id').primaryKey().autoincrement(),
|
||
name: varchar('name', { length: 100 }).notNull(),
|
||
// ...
|
||
});
|
||
```
|
||
|
||
- [ ] 创建 `src/schemas/index.ts` 统一导出
|
||
- [ ] 运行 `drizzle-kit generate` 生成初始迁移（与现有表结构对齐）
|
||
- [ ] 验证：`drizzle-kit studio` 能正确读取现有数据
|
||
|
||
**注意**：现有表已存在，首次迁移使用 `drizzle-kit push`（同步 schema 到数据库而不执行 SQL），或生成迁移后标记为已执行。
|
||
|
||
---
|
||
|
||
### Phase 3：逐个迁移 Routes
|
||
|
||
**目标**：将路由处理函数中的 Sequelize 查询替换为 Drizzle。
|
||
|
||
**迁移顺序**（从简到繁）：
|
||
|
||
| 批次 | 路由 | 原因 |
|
||
|------|------|------|
|
||
| 第 1 批 | auth.ts, shareCodeLogs.ts, brands.ts | 逻辑简单，CRUD 为主 |
|
||
| 第 2 批 | blacklist.ts, users.ts, otaTargetDevice.ts, dashboard.ts | 中等复杂度 |
|
||
| 第 3 批 | ota.ts, models.ts | 最复杂，涉及文件上传/外部服务 |
|
||
|
||
**每个路由的迁移步骤**：
|
||
|
||
1. 重命名 `.js` → `.ts`
|
||
2. `require()` → `import`
|
||
3. Sequelize 查询 → Drizzle 查询：
|
||
|
||
```ts
|
||
// Before (Sequelize)
|
||
const brands = await Brand.findAll({ where: { name: { [Op.like]: `%${keyword}%` } } });
|
||
|
||
// After (Drizzle)
|
||
const result = await db.select().from(brands).where(like(brands.name, `%${keyword}%`));
|
||
```
|
||
|
||
4. 添加请求/响应类型（配合 Zod validator）
|
||
5. 验证接口行为不变
|
||
|
||
---
|
||
|
||
### Phase 4：迁移 Services + 清理
|
||
|
||
**目标**：全部代码 TS 化，移除 Sequelize。
|
||
|
||
- [ ] 迁移 6 个 service 文件（主要是加类型标注，逻辑不变）
|
||
- [ ] 迁移 middleware（auth.ts, bodyLimit.ts）
|
||
- [ ] 迁移 config（env.ts, logger.ts, redis.ts）
|
||
- [ ] 迁移 utils
|
||
- [ ] 迁移入口 `app.js` → `app.ts`
|
||
- [ ] 删除所有旧 `.js` 文件
|
||
- [ ] 卸载 `sequelize` 依赖
|
||
- [ ] 全量 `tsc --noEmit` 通过
|
||
- [ ] 更新 Dockerfile（构建步骤改为 `tsc && node dist/app.js`）
|
||
|
||
---
|
||
|
||
### Phase 5：新增官网 CMS 模块
|
||
|
||
**目标**：在迁移完成的基础上，开发 `/api/www/*` 接口。
|
||
|
||
- [ ] 设计 CMS 数据表（pages、sections、banners、products、news、faq、site_settings 等）
|
||
- [ ] 编写 Drizzle schema + 迁移
|
||
- [ ] 实现前台接口 `/api/www/*`（公开）
|
||
- [ ] 实现管理接口 `/api/admin/www/*`（JWT 鉴权）
|
||
- [ ] dashboard 前端新增「官网管理」菜单
|
||
|
||
---
|
||
|
||
## 风险与注意事项
|
||
|
||
| 风险 | 应对 |
|
||
|------|------|
|
||
| 迁移期间线上服务中断 | 渐进式迁移，新旧代码共存，逐模块切换 |
|
||
| Sequelize 隐式行为（如自动时间戳） | 现有配置已关闭 timestamps，影响小 |
|
||
| `sequelize.sync()` 自动建表 → 手动迁移 | Phase 2 完成后用 drizzle-kit 管理，不再自动 sync |
|
||
| CommonJS → ESM 兼容问题 | 部分依赖（如 multer）可能需要 `esModuleInterop` 或动态 import |
|
||
| models.js 路由 26KB 过大 | 迁移时拆分为 models + measurements 两个路由文件 |
|
||
|
||
---
|
||
|
||
## 预计工时
|
||
|
||
| 阶段 | 预计时间 |
|
||
|------|----------|
|
||
| Phase 1：TS 基础设施 | 0.5 天 |
|
||
| Phase 2：Schema 迁移 | 0.5 天 |
|
||
| Phase 3：Routes 迁移 | 1~1.5 天 |
|
||
| Phase 4：Services + 清理 | 0.5 天 |
|
||
| Phase 5：CMS 模块 | 另计（属于新功能开发） |
|
||
| **合计（不含 Phase 5）** | **2.5~3 天** |
|