【免费下载链接】TechSpar一个持续进化的面试训练系统。在线体验地址https://techspar.cn项目地址https://gitcode.com/gh_mirrors/te/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 或 Electroncontracts 只定义协议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/streamtoken、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 层显式传递RequestContextrequestId/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 侧车全部通过本地 Embeddingsentence-transformers/PyTorch 由 Transformers.js ONNX 替代回滚策略也很清晰任何回滚必须停止新版、恢复迁移前数据副本、再启动旧版——禁止两个版本同时写同一份 SQLite。七、给想做类似迁移团队的 5 条经验先固定契约再动手把旧后端的 OpenAPI 快照成基线文件用自动化测试逐一比对路径、鉴权、请求体与错误码而不是凭记忆迁移兼容不等于冻结迁移期保持旧接口形状但把「有意破坏性变更」作为独立版本工作处理派生数据大胆重建索引、图谱、缓存标记为可重建兼容承诺只留给用户事实数据用 CI 锁架构边界依赖方向、全局变量、跨模块直读表全部写成可执行的检查脚本保留旧分支做归档旧代码固定 commit 只读保留随时可查可回滚但绝不接收新功能。从 FastAPI 到 TypeScriptTechSpar 这次迁移证明语言切换从来不是目的用契约和测试守护住每一个兼容承诺才是。对于正在考虑重写后端的团队这份 docs/hono-typescript-migration.md 的完整实施记录值得细读——它把每一步取舍、验证证据和踩坑都摊开在了桌面上。赞分享【免费下载链接】TechSpar一个持续进化的面试训练系统。在线体验地址https://techspar.cn项目地址https://gitcode.com/gh_mirrors/te/TechSpar点击查看免费下载相关推荐Archipelago版本兼容性向后兼容与迁移策略Archipelago版本兼容性向后兼容与迁移策略 概述 Archipelago作为一款多游戏随机化框架其版本兼容性策略直接影响着开发者和用户的体验。本文将游戏开发后端FastAPI 从 Pydantic v1 迁移到 Pydantic v2兼容窗口、渐进迁移策略与源码级检测机制FastAPI 从 Pydantic v1 迁移到 Pydantic v2兼容窗口、渐进迁移策略与源码级检测机制 如果你的 FastAPI 应用还停留在 Py后端Web框架API设计异步编程DocsGPT版本升级向后兼容与迁移策略DocsGPT版本升级向后兼容与迁移策略 引言 在AI技术快速迭代的今天开源项目DocsGPT作为智能文档助手平台面临着频繁的版本升级挑战。你是否曾遇到过人工智能AI 应用RAGAI Agent后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考