完整剖析 better-douyin Open Shell：Mock Bridge 与 Mock Backend 是如何设计的

better-douyin 是一款支持作者级下载、播放、点赞收藏、私信和 AI 控制的抖音桌面工具。它的公开源码是一个 Open Shell（开源壳）：界面与完整交互流程都可用，但底层完全由Mock Bridge（前端演示数据桥）与Mock Backend（本地演示服务）驱动，不访问真实平台。本文带你剖析这两层 Mock 的设计思路。

一、先搞懂 Open Shell：完整的外壳，不公开的引擎

Open Shell 的意思是：仓库给你一套可完整运行的 UI 壳，但刻意不含真实平台连接器、签名、Cookie 处理、下载解析等内容。

这样做的直接好处是：

• 安全边界清晰：敏感实现不入库，协作者和 AI 工具拿到的是干净上下文
• 前端契约先行：所有页面只依赖一套稳定的函数契约，真实后端和 Mock 后端可互相替换
• 本地即可开发：npm run demo一条命令，就能在浏览器里体验全部页面

策略细节见 OPEN_SOURCE.md 与 SECURITY_BOUNDARY.md。

二、整体架构：UI、桥接层、数据层三层解耦

页面组件 / hooks / stores ↓ 只调用统一契约 frontend/src/lib/tauri.ts（Mock Bridge，演示数据 + 内存状态 + 事件） ↓ 契约定义 frontend/src/lib/contracts.ts（前后端共享类型） backend/server.mjs（Mock Backend，独立 Node 演示服务 + 静态预览）

关键点在于：UI 从不直接碰数据源。它只调用 tauri.ts 暴露的函数，比如searchUser、getVideoDetail、downloadVideo、suggestAiInteraction。在完整发行版里，这套契约由 Rust / Tauri 桌面后端实现；在公开壳里，同一套契约由 Mock 实现兜底。

三、Mock Bridge 设计剖析：一个"假的"桌面桥接

Mock Bridge 的核心是 frontend/src/lib/tauri.ts，约 1000 行，设计上藏着四个巧思。

1. 契约式命名：函数签名与真实实现一一对应

文件开头导入了 contracts.ts 中定义的VideoInfo、AppConfig、CommentsResponse等约 40 个共享类型，每个导出函数都严格返回对应契约类型。这意味着私有版只要实现同样的函数签名，前端一行都不用改。

2. 一个内存状态机撑起全部演示

Bridge 内部维护一个state对象，包含配置、下载任务、历史记录，以及liked/collected/followed三个Set：

• 调用setVideoLiked点赞后，再调用getLikedVideos就能查到你刚"赞"过的视频
• 调用downloadVideo会通过upsertTask生成演示任务并写入历史

也就是说，Mock 不是"死数据"，而是可交互的模拟环境——点赞、收藏、关注、下载任务都能在会话内产生真实的状态变化。

3. 事件系统：用发布/订阅模拟桌面端推送

tauri-core.ts 与 socket.ts 注释中写明：事件全部走 Tauri 内建事件系统。Mock 版用emit+listeners（一个Map<string, Set<Listener>>）+ 浏览器CustomEvent实现了同样的发布/订阅语义。listenEvent返回取消函数，生命周期管理与真实实现一致，前端订阅下载进度、日志等事件时完全无感。

4. 防御式设计：把"打假"写进代码

invoke() / invokeLocal() → 直接 reject requestJson() → 抛错，拒绝发起任何 HTTP isTauriRuntime() → 恒为 false isBrowserBridgeRuntime() → 恒为 true

任何人试图在公开壳里调用桌面命令或真实 HTTP 都会立刻失败，而不是悄悄发出去。这是"边界即代码"的典型做法。

四、Mock Backend 设计剖析：238 行零依赖的演示服务

backend/server.mjs 只用 Node 内置的http/fs/path模块，零第三方依赖，却提供了完整的本地演示体验。

演示 API 一览

三个值得借鉴的工程细节

• 静态预览 + 路径安全：GET /直接服务dist/构建产物，并用candidate.startsWith(distDir)拦截路径穿越
• 请求体限流：readBody超过 1MB 立即销毁连接，防止滥用
• --check自检模式：node backend/server.mjs --check校验server.mjs、README.md、SECURITY_BOUNDARY.md是否存在，方便 CI 快速验证壳完整性

所有 JSON 响应统一携带x-open-shell: mock-backend头，一眼就能分辨"我在用演示服务"。

五、本地跑起来：一条命令体验 Open Shell

git clone https://gitcode.com/gh_mirrors/be/better-douyin cd better-douyin npm install npm --prefix frontend install npm run demo

demo脚本（见 package.json）先执行npm run build，再启动 Mock Backend，即可在浏览器中预览构建产物。开发模式npm run dev则走 Vite + Mock Bridge。

六、进阶：基于同一契约接入自己的后端

docs/adapter-boundary.md 明确划定了适配器边界：公开版本通过 tauri.ts 与数据源对话，私有版可以用不同桥接实现同一份前端契约，但绝不允许向公开边界添加真实接口端点、签名或 Cookie 逻辑。

如果你想给自己的应用接入演示数据或自有服务，只需要实现docs/adapter-boundary.md列出的契约函数：应用配置、账号、搜索与详情、列表流、评论通知、好友私信、下载任务状态。UI 层对数据来源零感知。

七、总结：Mock 不只是假数据

better-douyin 的 Open Shell 给出了一种开源协作的好范式：用契约隔离敏感实现，用可交互的 Mock 保证体验完整，用代码固化安全边界。理解了这套 Mock Bridge + Mock Backend 的设计，你也能给自己的"公开壳 + 私有引擎"项目搭出同样清晰的协作架构。