从FastAPI到TypeScript:TechSpar后端完整迁移实施记录与兼容策略

原创2026-10-15 10:26:181,386 阅读

从FastAPI到TypeScript:TechSpar后端完整迁移实施记录与兼容策略

TechSpar 是一个持续进化的面试训练系统,它刚刚完成了一次教科书式的后端整体迁移:从 Python/FastAPI 全面切换到 TypeScript + Bun + Hono,并同步落地 Electron 桌面端。对很多前端背景的团队来说,「FastAPI 迁移到 TypeScript」听起来大胆,但 TechSpar 给出了完整答案——62 个路径、71 个 HTTP 操作全部保持兼容,旧数据直接可用,前端几乎无感。本文完整记录这次迁移的架构决策、目录设计和兼容策略,帮你理解如何安全地重写一个生产级后端。

TechSpar 面试轨迹闭环:专项训练、简历面试、JD备面、录音复盘与实时Copilot五大模块

一、为什么放弃 FastAPI?迁移不是逐文件翻译

很多团队重构后端的误区,是把 backend/*.py 逐个翻译成 .ts。TechSpar 在 docs/typescript-backend-architecture.md 中明确写下决策:迁移不是逐文件翻译,而是要借机解决一批结构性问题:

  • HTTP、SSE、WebSocket 与业务逻辑纠缠在一起;
  • 用户身份靠 ContextVar 隐式传递,难以追踪;
  • SQLite、文件、LLM、ASR 等外部依赖不可替换、不可测试;
  • 长任务不可恢复、不可幂等重试;
  • Web 服务与未来的桌面端无法共享同一套业务契约。

迁移目标一句话概括:在保持旧数据和接口完全兼容的前提下,建立可测试、可替换、可恢复的新结构。

TechSpar 个人画像页:43次录音分析与17次完整面试沉淀的练习统计与弱点信号

二、总体架构:模块化单体 + 六边形架构

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。

TechSpar JD 定向备面工作台:岗位解析、简历联动与准备流程

核心业务按能力拆成 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 时代的个人归档(tarfile PAX/GNU 格式)可以被新后端安全导入,同时保留路径、链接、checksum 检查;
  • 向量索引、知识图谱等派生数据被明确定义为「可重建」,丢了可以重算,不进入兼容承诺。

TechSpar 录音复盘工作台:双人对话与单人录音两种复盘模式的输入与分析设置

四、长任务与实时链路的重构

旧 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 调用。

TechSpar 实时 Copilot 与问题图谱:面试轨迹的统一保存与长期记忆引擎

六、迁移结果与验收证据

迁移按大块原子提交直接进入 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 条经验

  1. 先固定契约再动手:把旧后端的 OpenAPI 快照成基线文件,用自动化测试逐一比对路径、鉴权、请求体与错误码,而不是凭记忆迁移;
  2. 兼容不等于冻结:迁移期保持旧接口形状,但把「有意破坏性变更」作为独立版本工作处理;
  3. 派生数据大胆重建:索引、图谱、缓存标记为可重建,兼容承诺只留给用户事实数据;
  4. 用 CI 锁架构边界:依赖方向、全局变量、跨模块直读表,全部写成可执行的检查脚本;
  5. 保留旧分支做归档:旧代码固定 commit 只读保留,随时可查可回滚,但绝不接收新功能。

TechSpar 知识库页面:面试训练系统持续进化的记忆底座

从 FastAPI 到 TypeScript,TechSpar 这次迁移证明:语言切换从来不是目的,用契约和测试守护住每一个兼容承诺才是。对于正在考虑重写后端的团队,这份 docs/hono-typescript-migration.md 的完整实施记录值得细读——它把每一步取舍、验证证据和踩坑都摊开在了桌面上。

登录后查看全文
TechSpar