一套代码三端运行：运行时 Adapter

问题的观点是。多一个网站，多一倍麻烦

假设你写了一个聊天应用。React 前端，Electron 桌面壳。跑起来了产品说：出个手机版。

再开一个仓库，React Native 重写一套 UI。界面长得差不多，网络请求抄一遍，两三周出个能用的版本。

痛点：每个月都要在不同网站重复实现同一功能，导致认知负担指数级增长；遗漏导致使用者投诉，定位时间远超修复时间。

矛盾这方面，一份代码，但底层不同

Electron 的前端和后端之间用 IPC。而手机 App 和 Web 浏览器只能用 HTTP 请求。若把判断写在每个组件里：

// 不要这样写
function ConversationList {
if {
data = ipc.invoke
} else {
data = fetch
}
}

每个 API 调用点都要写一次 if改动需要在所有地方同步修改——这比两套代码还糟。

方案这方面。Adapter 模式

GoF 在《设计模式》中提出 Adapter，把差异关在一个房间里不让它跑出来。业务层只与统一接口对话，适配层内部判断网站并转发请求。

// 统一调用入口
transport.invoke
// 内部根据 isElectron / isMobile / isWeb 决定走 IPC / HTTP / WebSocket

再看实战，Halo 如何撑起三个网站

文件 src/renderer/api/transport.ts 集中检测网站；src/renderer/api/index.ts 中每个 API 都遵循同一模式：

// src/renderer/api/index.ts
listConversations: async => {
if ) return window.halo.listConversations
return httpRequest
}。

痛点缓解：业务组件只调用 api.listConversations根本不关心底层走的是 IPC 还是 HTTP，避免了网站差异散落全项目。

再看关键抉择。运行时检测 vs 编译时分支

• 编译时分支：#ifdef 类似做法产出多份产物，建立配置复杂、易炸。
• 运行时检测：只编译一份代码。多一个 if 的开销可以忽略，却省去三条 CI 流水线和三套版本号。

痛点：If 团队只有一个人或缺少专职建立工程师，维护多条管线几乎不可能；运行时检测让“只写一次代码”成为现实。

代价这方面。差异集中在适配层

Ada­pt 并不消除网站差异，只是把它们集中管理。例如移动端需要先测试服务器连通性再持久化地址，这类细节全部放在 transport.ts 中。如果遗漏，仅表现为 UI 无响应或错误状态，定位成本仍然很高。

声明式能力边界

问题的观点是。 谁能调什么

E​lectron 默认开启 nodeIntegration，使渲染进程可以直接调用 Node.js API。这在加载外部网页时会导致 XSS 漏洞直接变程序入侵。

两种开洞方式

• A）分散检查：
• B）白名单声明：{@link contextBridge} 在 preload 脚本中一次性声明所有可暴露的方法。

再看实战。Halo 的白名单实现

// src/preload/index.ts
const api: HaloAPI = {
listConversations: => ipcRenderer.invoke,sendMessage: => ipcRenderer.invoke,//…200+ 方法
}
contextBridge.exposeInMainWorld

Pain Point: 如果忘记在此文件中注册某方法。渲染进程根本看不到对应函数，无声失效极难排查。说起来，

Synchronization Cost & Mitigation Levels

1. Simplified规范约束：

模块组织与分层

按业务划分 Handler 文件夹结构

Main 进程下的 /src/main/ipc/​。每个文件对应业务领域，便于 AI 定位入口并快速插入新功能。

局部重复 vs 全局 DRY

I​PC 与 HTTP 路由几乎相同。但强行抽象会引入额外适配层，使阅读成本上升。实际工程中保持“局部重复但易读”往往比盲目 DRY 更稳妥。

SPLIT LAYERS & DEPENDENCY DIRECTION

Pain Point：单点故障蔓延

If UI 层直接 import 数据库模块，一旦数据库返回结构变化 UI 会崩溃。这说明缺乏明确的层级隔离。

SINGLE‑DIRECTION DEPENDENCY DESIGN

UI
↓ Service
↓ Platform
↓ Shared
# 上层只能依赖下层。下层绝不可依赖上层

• Pain Point: AI 编码倾向于“最快完成任务”，若未明确禁止跨层依赖，它会直接跨越 Service 层调用 Platform API，从而破坏隔离。
• SOLUTION: 将依赖方向规则写入 AI 可读取的指令文件，如 .claude.md: “src/platform/** 不得 import src/service/**”。不过，AI 会严格遵守这些硬性禁令。
• PRACTICAL ISOLATION: Renderer 与 Main 在不同进程中运行。本身就是物理上的层级隔离，比 lint 更可靠。

PREFIXED PERFORMANCE – BUDGET。LAZY LOAD & WORKER ISOLATION

Pain Point：功能堆叠导致启动慢

A​pp 从首月几秒启动膨胀到数十秒，仅因为没有设定启动预算和阶段划分。使用者体验骤降却难以定位根因。

设计思想的观点是，预算约束

• 事前设定“启动时间 ≤ 500 ms”。任何新功能必须回答：“是否首屏必需？”否则延迟到后续阶段或懒加载.

---