从FastAPI到TypeScript:TechSpar后端完整迁移实施记录与兼容策略
从FastAPI到TypeScript:TechSpar后端完整迁移实施记录与兼容策略
TechSpar 是一个持续进化的面试训练系统,它刚刚完成了一次教科书式的后端整体迁移:从 Python/FastAPI 全面切换到 TypeScript + Bun + Hono,并同步落地 Electron 桌面端。对很多前端背景的团队来说,「FastAPI 迁移到 TypeScript」听起来大胆,但 TechSpar 给出了完整答案——62 个路径、71 个 HTTP 操作全部保持兼容,旧数据直接可用,前端几乎无感。本文完整记录这次迁移的架构决策、目录设计和兼容策略,帮你理解如何安全地重写一个生产级后端。
一、为什么放弃 FastAPI?迁移不是逐文件翻译
很多团队重构后端的误区,是把 backend/*.py 逐个翻译成 .ts。TechSpar 在 docs/typescript-backend-architecture.md 中明确写下决策:迁移不是逐文件翻译,而是要借机解决一批结构性问题:
- HTTP、SSE、WebSocket 与业务逻辑纠缠在一起;
- 用户身份靠
ContextVar隐式传递,难以追踪; - SQLite、文件、LLM、ASR 等外部依赖不可替换、不可测试;
- 长任务不可恢复、不可幂等重试;
- Web 服务与未来的桌面端无法共享同一套业务契约。
迁移目标一句话概括:在保持旧数据和接口完全兼容的前提下,建立可测试、可替换、可恢复的新结构。
二、总体架构:模块化单体 + 六边形架构
TechSpar 保持了单体部署,没有引入微服务、消息中间件或分布式事务,而是采用「模块化单体 + 六边形架构」,整体分为四层:
| 层 | 职责 | 对应代码 |
|---|---|---|
| Hosts 宿主层 | Web 服务与桌面端组装入口 | apps/api/、apps/desktop/ |
| Inbound 入站适配器 | REST 路由、SSE 路由、WebSocket 网关 | apps/api/src/routes/ |
| Core 核心模块 | 领域类型、用例、状态机、端口 | packages/core/src/ |
| Outbound 出站适配器 | SQLite、文件、LLM、ASR、对象存储 | packages/db/、packages/providers/ |
依赖方向只能向内:core 不依赖 Hono、Drizzle、Bun 或 Electron;contracts 只定义协议(Zod schema、OpenAPI、SSE 事件、错误码),不承载业务决策。这样 Web 和桌面端可以复用同一套用例,Electron 的 IPC 也能直接使用相同的 Zod schema。
核心业务按能力拆成 8 个模块:account(账号)、provider(模型配置与配额)、knowledge(知识库)、personal-agent(个人文档与记忆)、interview(面试训练)、profile(画像与复习)、recording(录音复盘)、copilot(实时面试助手)。模块之间不允许直接读对方的表,跨模块协作只能通过公开的用例接口,例如 interview 调用 KnowledgeQuery 而不是导入 knowledge 的数据库 repository。
三、关键兼容策略:让旧客户端完全无感
1. OpenAPI 契约逐一对照
迁移前,团队把 FastAPI 的 OpenAPI 基线保存在 tests-ts/contracts/fastapi-openapi.json,然后写了 tests-ts/contracts/openapi-parity.test.ts 做自动化比对:
- 旧版 62 个路径、71 个操作在新版中一个不能少;
- 每个操作的 Bearer 鉴权、请求体是否必填、
422校验错误响应必须与旧版一致; - 共 67 个操作带鉴权、28 个操作要求必填请求体、51 个操作返回
422结构,全部用断言固定。
前端类型也不靠手写:frontend/src/api/schema.d.ts 由 bun run gen:api 从当前 OpenAPI 自动生成,保证前后端类型永不漂移。
2. SSE 与 WebSocket 事件语义保留
实时链路是面试训练系统的灵魂,迁移中三条流都保留了原有事件语义:
/api/interview/chat/stream:token、error、done 事件;/api/settings/rebuild-index:索引重建的逐步进度事件;/ws/copilot/:session_id:二进制 PCM 音频输入、ASR、回答建议与风险提醒事件。
3. 数据与认证平滑接管
- SQLite 与
data/users/{user_id}文件布局原样兼容,旧库直接可读写; - 保留 bcrypt 密码与 HS256 JWT 行为,老用户无需重新注册;
- Python 时代的个人归档(
tarfilePAX/GNU 格式)可以被新后端安全导入,同时保留路径、链接、checksum 检查; - 向量索引、知识图谱等派生数据被明确定义为「可重建」,丢了可以重算,不进入兼容承诺。
四、长任务与实时链路的重构
旧 Python 版的长任务(录音转写、索引重建、Copilot prep)状态散落在内存里。迁移后统一为持久化任务状态机:queued → running → succeeded/failed,支持取消与幂等重试。每个任务落库保存 taskId、userId、status、progress、idempotencyKey 等字段,配合数据库租约与 owner fencing,防止多实例重复执行——这是旧架构完全不具备的能力。
Copilot 实时会话也被拆成三块:纯状态机的 CopilotSession、协调 ASR/VAD/声纹/LLM 的 RealtimeOrchestrator、处理背压与关闭码的 WebSocketGateway。音频 chunk 先转成内部事件再映射为对外协议,意味着整套状态机可以在无网络条件下用录制 PCM 测试——这正是迁移带来的可测试性红利。
五、自动守卫:用 CI 阻止架构腐化
迁移最怕「迁移完一天,耦合回一车」。TechSpar 用两道自动化防线锁死边界:
- 架构边界检查:scripts/check-boundaries.ts 递归扫描
packages/core/src与packages/contracts/src,一旦发现导入 Hono、Bun、Electron、Drizzle 或Bun.*全局对象,直接退出码 1 让 CI 失败; - 响应契约分层测试:围绕 OpenAPI 对照、SSE 形状、HTTP 边界写成的契约测试集中在 tests-ts/contracts/,配合
bun run test:contracts全量跑。
此外,core 层显式传递 RequestContext(requestId / userId / AbortSignal),禁止「当前用户」全局变量;取消信号必须一路传到 LLM、Embedding 和 ASR 调用。
六、迁移结果与验收证据
迁移按大块原子提交直接进入 main 分支,旧版本则固定在 legacy/python-backend 分支(73d1a7c)作为历史归档,见 docs/legacy-python-backend.md。最终验收数据(完整记录在 docs/typescript-migration-closeout.md):
| 验收项 | 结果 |
|---|---|
| 旧 OpenAPI 契约对照 | 62 路径 / 71 操作全部兼容 |
| 后端测试 | 108 个测试、688 次断言全部通过 |
| 前端回归 | 3 个测试通过,Lint 0 error |
| 类型检查 | Bun 与 Node 双运行时通过 |
| 打包 | API bundle、Vite 生产构建、Electron 主进程、darwin-arm64 侧车全部通过 |
| 本地 Embedding | sentence-transformers/PyTorch 由 Transformers.js + ONNX 替代 |
回滚策略也很清晰:任何回滚必须停止新版、恢复迁移前数据副本、再启动旧版——禁止两个版本同时写同一份 SQLite。
七、给想做类似迁移团队的 5 条经验
- 先固定契约再动手:把旧后端的 OpenAPI 快照成基线文件,用自动化测试逐一比对路径、鉴权、请求体与错误码,而不是凭记忆迁移;
- 兼容不等于冻结:迁移期保持旧接口形状,但把「有意破坏性变更」作为独立版本工作处理;
- 派生数据大胆重建:索引、图谱、缓存标记为可重建,兼容承诺只留给用户事实数据;
- 用 CI 锁架构边界:依赖方向、全局变量、跨模块直读表,全部写成可执行的检查脚本;
- 保留旧分支做归档:旧代码固定 commit 只读保留,随时可查可回滚,但绝不接收新功能。
从 FastAPI 到 TypeScript,TechSpar 这次迁移证明:语言切换从来不是目的,用契约和测试守护住每一个兼容承诺才是。对于正在考虑重写后端的团队,这份 docs/hono-typescript-migration.md 的完整实施记录值得细读——它把每一步取舍、验证证据和踩坑都摊开在了桌面上。





