企业官网建设流程全解析

1. 为什么“Shared API”是Electron项目里最容易被忽视的命门

Electron开发者常陷入一个典型误区：把主进程当成“后台服务”，把渲染进程当成“前端页面”，然后用ipcRenderer.send和ipcMain.on像发微信消息一样来回传数据。我见过太多项目，初期跑得飞快，三个月后一加新功能就卡顿、内存暴涨、IPC调用堆成山——最后排查发现，80%的性能瓶颈和逻辑混乱，根源不在UI渲染，而在于共享API的设计失当。

“Shared API”这个词在Electron官方文档里没有独立章节，但它真实存在于每个中大型项目的底层骨架中。它不是指某个具体API，而是指主进程与渲染进程之间，那些本该被统一定义、类型约束、生命周期可控、错误可追溯的跨进程调用契约。它解决的从来不是“能不能通信”，而是“怎么让通信不变成技术债的温床”。

举个真实场景：某跨平台桌面工具需要读取本地配置文件、监听USB设备、调用系统级打印服务。如果每个渲染进程页面都各自写一遍ipcRenderer.invoke('read-config')，再在主进程中零散地注册ipcMain.handle('read-config', ...)，那么当配置格式变更、权限模型升级、或需要增加缓存策略时，你得同时改5个地方——3个渲染进程入口、1个preload脚本、1个主进程handler，还可能漏掉某个异步回调里的兜底逻辑。

这就是Shared API缺失的代价：表面是IPC调用，实质是分布式系统中最难啃的协调问题。它要求你提前思考：哪些能力必须由主进程垄断？哪些数据可以安全缓存在渲染进程？错误发生时，该由哪一侧做重试？超时该由谁判定？日志该打在哪一层？

关键词“Shared API”背后，其实是Electron架构中一个被长期低估的分层设计命题：进程边界不是网络边界，但它的治理复杂度不亚于微服务通信。它不涉及加密、负载均衡或服务发现，却直面更棘手的问题——JavaScript单线程模型下，如何让两个隔离的V8实例，在无共享内存、无直接引用的前提下，达成语义一致、行为可靠、调试友好的协作。

所以这篇指南不讲“如何用IPC”，而是带你从零构建一套可维护、可测试、可演进的Shared API体系。它不依赖任何第三方库，全部基于Electron原生能力，但每一步都踩过坑、验过真——比如preload脚本里contextIsolation: true开启后，为什么window.api会突然变undefined；比如ipcRenderer.invoke返回Promise，但主进程handler里throw new Error()为何在渲染进程捕获不到堆栈；再比如，当多个渲染窗口同时调用getSystemInfo，主进程如何避免重复执行昂贵的系统调用。

这些不是理论问题，是我在三个不同行业Electron项目里，亲手填平的坑。接下来，我们就从最基础的契约定义开始，一层层垒起这个看似简单、实则决定项目寿命的共享层。

2. Shared API的本质：不是通信管道，而是类型契约与生命周期协议

很多开发者把Shared API简单理解为“主进程暴露给渲染进程调用的一组函数”。这没错，但太浅。真正的Shared API，是主进程能力、渲染进程需求、以及二者间交互规则三者共同收敛出的精确契约。它必须同时满足三个硬性条件：

• 类型可验证：调用方（渲染进程）知道参数长什么样、返回值是什么结构、可能抛出什么错误；
• 行为可预测：同一API在不同渲染窗口、不同时间点调用，结果语义一致（比如getAppVersion()永远返回字符串，不会有时是对象有时是Promise）；
• 生命周期可管理：API调用能感知窗口关闭、进程退出等事件，避免悬空引用、内存泄漏或静默失败。

要达成这三点，不能靠口头约定或注释，必须落实到代码结构上。我们以一个实际需求切入：获取当前用户偏好设置，并支持实时更新通知。

2.1 错误示范：裸IPC调用的脆弱性

先看一段典型的“能跑就行”代码：

// 主进程 (main.js) ipcMain.on('get-preferences', (event) => { event.reply('preferences-response', loadPreferences()); }); ipcMain.on('set-preferences', (event, prefs) => { savePreferences(prefs); // 忘记通知所有窗口！ });

// 渲染进程 (renderer.js) ipcRenderer.send('get-preferences'); ipcRenderer.on('preferences-response', (event, prefs) => { renderPreferences(prefs); });

这段代码有四个致命缺陷：

1. 无类型约束：loadPreferences()返回什么？prefs参数结构是否校验？全靠开发者自觉；
2. 无错误处理：loadPreferences()抛异常，event.reply根本不会触发，渲染进程永远收不到响应；
3. 无生命周期绑定：ipcRenderer.on注册的监听器，在窗口关闭后未清理，导致内存泄漏；
4. 无状态同步：set-preferences后，其他已打开的窗口无法自动更新UI，出现状态不一致。

提示：Electron 12+ 已废弃ipcRenderer.send+event.reply模式，强制推荐invoke/handle。但即使改用invoke，若不配合类型定义和错误包装，问题依然存在。

2.2 正确范式：Shared API = TypeScript接口 + Preload封装 + 主进程Handler

我们重构为Shared API模式，核心是将通信细节完全封装，对外只暴露清晰、安全、可测试的函数签名。

第一步：定义TypeScript接口（shared-api.d.ts）

// shared-api.d.ts export interface Preferences { theme: 'light' | 'dark' | 'system'; autoUpdate: boolean; language: string; } export interface SharedAPI { // 获取偏好设置（返回Promise，类型明确） getPreferences(): Promise<Preferences>; // 设置偏好设置（返回Promise，含错误类型） setPreferences(prefs: Partial<Preferences>): Promise<void>; // 订阅偏好变更（返回取消订阅函数） onPreferencesChange(cb: (newPrefs: Preferences) => void): () => void; }

第二步：Preload脚本封装（preload.js）

// preload.js import { contextBridge, ipcRenderer } from 'electron'; // 定义SharedAPI实现 const api: SharedAPI = { getPreferences: async () => { try { // 使用 invoke，自动处理Promise链和错误 return await ipcRenderer.invoke('api:get-preferences'); } catch (error) { // 统一错误处理，避免原始Error对象跨进程丢失 throw new Error(`Failed to get preferences: ${error instanceof Error ? error.message : String(error)}`); } }, setPreferences: async (prefs) => { try { await ipcRenderer.invoke('api:set-preferences', prefs); } catch (error) { throw new Error(`Failed to set preferences: ${error instanceof Error ? error.message : String(error)}`); } }, onPreferencesChange: (cb) => { const handler = (event, newPrefs: Preferences) => cb(newPrefs); ipcRenderer.on('api:preferences-changed', handler); // 返回取消订阅函数，确保可清理 return () => { ipcRenderer.removeListener('api:preferences-changed', handler); }; } }; // 将API桥接到渲染进程全局作用域（仅在contextIsolation启用时安全） contextBridge.exposeInMainWorld('api', api);

第三步：主进程Handler（main.js）

// main.js import { app, BrowserWindow, ipcMain } from 'electron'; import { Preferences, SharedAPI } from './shared-api'; // 全局偏好存储（示例，实际应持久化） let currentPrefs: Preferences = { theme: 'system', autoUpdate: true, language: 'en' }; // 处理获取请求 ipcMain.handle('api:get-preferences', () => { return { ...currentPrefs }; // 返回副本，避免外部修改 }); // 处理设置请求 ipcMain.handle('api:set-preferences', async (event, prefs: Partial<Preferences>) => { // 类型校验（可选，但强烈建议） if (prefs.theme && !['light', 'dark', 'system'].includes(prefs.theme)) { throw new Error(`Invalid theme: ${prefs.theme}`); } Object.assign(currentPrefs, prefs); // 通知所有窗口偏好已变更 BrowserWindow.getAllWindows().forEach(win => { win.webContents.send('api:preferences-changed', { ...currentPrefs }); }); });

现在，渲染进程只需：

// renderer.ts import { Preferences } from './shared-api'; // 调用API（类型安全，IDE自动补全） const prefs = await window.api.getPreferences(); console.log(prefs.theme); // ✅ 类型推导正确 // 订阅变更（自动清理） const unsubscribe = window.api.onPreferencesChange((newPrefs) => { updateUI(newPrefs); }); // 窗口卸载时清理 window.addEventListener('beforeunload', () => { unsubscribe(); });

这个模式的价值，远不止“代码更整洁”。它把原本分散在IPC调用各处的职责，收束到三个明确位置：

• 类型定义层：定义“应该是什么”，由TypeScript保障；
• Preload封装层：定义“怎么安全调用”，处理错误、清理、上下文隔离；
• 主进程Handler层：定义“怎么做才正确”，包含业务逻辑、校验、广播。

注意：contextBridge.exposeInMainWorld是启用contextIsolation: true的前提。若跳过此步直接挂载window.api，在Electron 12+ 会报错且无法访问。这是Shared API能落地的第一道安全门槛。

3. Preload脚本：Shared API的守门人与翻译官

Preload脚本在Electron架构中扮演着“可信中介”的角色——它运行在渲染进程沙箱内，但拥有对Node.js和Electron API的有限访问权。正是这个特殊身份，让它成为Shared API不可替代的基石。很多人把它当作“加载脚本的钩子”，却忽略了它本质是主进程能力与渲染进程需求之间的语义翻译层。

3.1 Preload的核心使命：隔离、转换、加固

Preload脚本绝非简单的require转发器。它的核心任务有三层：

1. 隔离（Isolation）：阻止渲染进程直接访问require、process等危险全局对象，切断潜在攻击面；
2. 转换（Translation）：将主进程的IPC事件、异步操作、错误模型，转换为渲染进程熟悉的Promise/Event API；
3. 加固（Hardening）：注入类型检查、参数校验、调用频率限制、敏感操作白名单等防护逻辑。

我们以一个更复杂的例子说明：调用系统原生对话框（如dialog.showOpenDialog），但需限制只能打开特定目录下的文件。

裸调用风险极大：

// ❌ 危险！渲染进程直接调用 const { dialog } = require('electron'); const result = await dialog.showOpenDialog({ properties: ['openFile'] });

这违反了Electron安全最佳实践（禁用nodeIntegration），且无法控制用户选择路径。

正确做法是通过Shared API封装：

// shared-api.d.ts export interface FileOpenResult { canceled: boolean; filePaths: string[]; } export interface SharedAPI { // 安全的文件打开API openConfigFile(): Promise<FileOpenResult>; }

// preload.js import { contextBridge, ipcRenderer } from 'electron'; const api: SharedAPI = { openConfigFile: async () => { try { // 1. 转换：将IPC调用包装为Promise // 2. 加固：此处可添加前置校验（如检查当前窗口是否有权限） return await ipcRenderer.invoke('api:open-config-file'); } catch (error) { // 3. 隔离：错误信息脱敏，不泄露主进程路径 if (error instanceof Error && error.message.includes('canceled')) { return { canceled: true, filePaths: [] }; } throw new Error('Failed to open config file'); } } }; contextBridge.exposeInMainWorld('api', api);

// main.js import { app, BrowserWindow, dialog, ipcMain } from 'electron'; import * as path from 'path'; // 定义允许打开的配置目录（绝对路径） const CONFIG_DIR = path.join(app.getPath('appData'), 'MyApp', 'config'); ipcMain.handle('api:open-config-file', async () => { try { const result = await dialog.showOpenDialog({ title: 'Select Configuration File', defaultPath: CONFIG_DIR, // 强制默认路径 filters: [ { name: 'Configuration Files', extensions: ['json', 'yaml', 'yml'] } ], properties: ['openFile'] }); // 4. 加固：校验用户选择的文件是否在允许目录内 if (result.filePaths.length > 0) { const selectedPath = result.filePaths[0]; const resolvedPath = path.resolve(selectedPath); const isSafe = resolvedPath.startsWith(path.resolve(CONFIG_DIR)); if (!isSafe) { throw new Error(`Access denied: ${selectedPath} is outside allowed directory`); } } return result; } catch (error) { // 5. 转换：将主进程Error转为渲染进程可理解的结构 if (error instanceof Error && error.message === 'canceled') { return { canceled: true, filePaths: [] }; } throw error; } });

这个例子凸显Preload的不可替代性：

• 它让渲染进程无需知道dialog模块的存在，只关心“我要开一个配置文件”这一业务意图；
• 它把主进程的路径校验逻辑，转化为渲染进程的调用契约，调用方无需理解path.resolve或startsWith，只需信任API返回结果；
• 它把canceled这种底层信号，统一映射为{ canceled: true }结构，避免渲染进程因判断result === undefined还是result.canceled而产生歧义。

3.2 Preload的实战陷阱与避坑指南

Preload脚本看似简单，实操中90%的Shared API失败源于此。以下是我在多个项目中总结的硬核经验：

陷阱1：contextIsolation与worldSafeExecuteJavaScript的组合雷区

Electron 12+ 默认启用contextIsolation: true，这是安全刚需。但若同时设置worldSafeExecuteJavaScript: false（旧版兼容写法），会导致contextBridge.exposeInMainWorld失效，window.api为undefined。

正确配置（webPreferences）：

const win = new BrowserWindow({ webPreferences: { contextIsolation: true, // 必须true nodeIntegration: false, // 必须false preload: path.join(__dirname, 'preload.js'), // 必须指定 // worldSafeExecuteJavaScript: true, // Electron 14+ 默认true，无需显式设置 } });

提示：worldSafeExecuteJavaScript在 Electron 14+ 已默认为true，显式设为false会引发严重安全漏洞，务必删除该行。

陷阱2：Preload内require的路径问题

Preload脚本的__dirname指向主进程启动目录，而非preload文件所在目录。若preload与主进程文件分离，require('./utils')会失败。

解决方案：使用path.resolve或import.meta.url

// ✅ 推荐：ESM风格，路径绝对可靠 import { resolve } from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // 现在可以安全require同目录下的模块 const utils = require(resolve(__dirname, 'utils.js'));

陷阱3：IPC事件监听器的内存泄漏

ipcRenderer.on注册的监听器，若未在窗口关闭时手动移除，会持续占用内存并接收无效事件。

Preload层自动管理方案：

// preload.js - 增强版onPreferencesChange onPreferencesChange: (cb) => { const handler = (event, newPrefs) => cb(newPrefs); ipcRenderer.on('api:preferences-changed', handler); // 关键：利用Electron的窗口生命周期事件自动清理 const cleanup = () => { ipcRenderer.removeListener('api:preferences-changed', handler); }; // 监听窗口即将关闭事件（渲染进程内） window.addEventListener('beforeunload', cleanup); // 返回清理函数，供调用方手动清理（双重保险） return cleanup; }

陷阱4：跨窗口API调用的上下文错乱

当应用有多个BrowserWindow时，ipcRenderer.invoke默认只向创建它的窗口的主进程发送请求。若主进程Handler中使用event.sender获取窗口，需注意其指向的是发起调用的窗口，而非当前活动窗口。

安全实践：主进程Handler中，始终使用event.sender进行窗口特定操作

// main.js - 安全的窗口特定通知 ipcMain.handle('api:show-notification', (event, message) => { // event.sender 是调用此API的窗口 event.sender.send('notification', message); // 若需通知所有窗口，显式遍历 // BrowserWindow.getAllWindows().forEach(win => win.webContents.send(...)); });

Preload不是胶水代码，它是Shared API的“宪法”。它定义了什么能做、什么不能做、怎么做才安全。跳过Preload，或把它写成简单的IPC转发器，等于在电子围栏上开了扇没锁的门——门还在，但防护已失效。

4. 主进程Handler：Shared API的执行引擎与状态中枢

如果说Preload是Shared API的“外交官”，那么主进程Handler就是它的“总参谋部”。它不直接面向用户，却决定了每一个API调用的成败、性能与安全性。很多开发者把Handler写成一堆零散的ipcMain.on或ipcMain.handle，结果导致逻辑碎片化、状态不一致、调试如大海捞针。真正的Shared API Handler，必须是一个有状态、可监控、可扩展、有边界的执行中枢。

4.1 Handler的分层架构：从裸调用到领域服务

一个健壮的Handler不应是“收到请求就干活”，而应遵循清晰的分层：

我们以“获取系统信息”API为例，展示分层Handler的写法：

// shared-api.d.ts export interface SystemInfo { os: string; arch: string; memoryTotal: number; // MB cpuCount: number; appVersion: string; } export interface SharedAPI { getSystemInfo(): Promise<SystemInfo>; }

// main/handlers/system-handler.ts import { app, systemPreferences, ipcMain } from 'electron'; import { logger } from '../utils/logger'; import { metrics } from '../utils/metrics'; // 服务层：纯业务逻辑，无Electron依赖，可单元测试 class SystemService { private cache: SystemInfo | null = null; private cacheTime = 0; private readonly CACHE_TTL = 30 * 1000; // 30秒缓存 async getSystemInfo(): Promise<SystemInfo> { const now = Date.now(); // 缓存命中 if (this.cache && now - this.cacheTime < this.CACHE_TTL) { return this.cache; } // 构建系统信息 const info: SystemInfo = { os: process.platform, arch: process.arch, memoryTotal: Math.round(require('os').totalmem() / (1024 * 1024)), cpuCount: require('os').cpus().length, appVersion: app.getVersion() }; this.cache = info; this.cacheTime = now; return info; } } // 基础设施层：日志与指标 const systemService = new SystemService(); // 接入层：IPC Handler ipcMain.handle('api:get-system-info', async (event) => { try { logger.debug('getSystemInfo invoked', { windowId: event.sender.id, timestamp: Date.now() }); const startTime = Date.now(); const result = await systemService.getSystemInfo(); const duration = Date.now() - startTime; metrics.histogram('api.getSystemInfo.duration', duration); metrics.increment('api.getSystemInfo.success'); return result; } catch (error) { logger.error('getSystemInfo failed', { error: error instanceof Error ? error.message : String(error), windowId: event.sender.id }); metrics.increment('api.getSystemInfo.error'); throw error; } });

这个分层结构带来三大收益：

• 可测试性：SystemService类可脱离Electron环境，用Jest直接测试缓存逻辑、数据计算；
• 可观测性：日志记录窗口ID，便于追踪问题来源；指标统计成功率与耗时，为性能优化提供依据；
• 可维护性：当需要增加“获取GPU信息”时，只需在SystemService中添加方法，Handler层复用相同日志/指标模板。

4.2 状态管理：Shared API的隐性心脏

Shared API常需维护跨窗口、跨调用的状态。例如：

• 用户登录态：多个窗口需共享同一token；
• 设备连接状态：USB设备插拔需通知所有窗口；
• 配置变更：偏好设置更新需广播。

若每个Handler都自行管理状态，必然导致不一致。正确做法是将状态提升为Shared API的顶层服务。

我们设计一个StateManager，作为所有Handler的公共状态中枢：

// main/services/state-manager.ts import { BrowserWindow } from 'electron'; interface State<T> { value: T; listeners: Array<(newValue: T) => void>; } export class StateManager { private states: Map<string, State<any>> = new Map(); // 设置状态（触发广播） setState<T>(key: string, value: T): void { const state = this.states.get(key) || { value: undefined, listeners: [] }; state.value = value; this.states.set(key, state); // 广播给所有窗口 BrowserWindow.getAllWindows().forEach(win => { win.webContents.send(`state:${key}:changed`, value); }); // 通知本地监听器 state.listeners.forEach(cb => cb(value)); } // 获取当前状态 getState<T>(key: string): T | undefined { return this.states.get(key)?.value; } // 订阅状态变更 onStateChange<T>(key: string, cb: (newValue: T) => void): () => void { const state = this.states.get(key) || { value: undefined, listeners: [] }; state.listeners.push(cb); this.states.set(key, state); // 立即触发一次当前值（避免错过初始状态） if (state.value !== undefined) { cb(state.value); } return () => { const index = state.listeners.indexOf(cb); if (index > -1) { state.listeners.splice(index, 1); } }; } } export const stateManager = new StateManager();

现在，任何Handler都可以安全地读写状态：

// main/handlers/auth-handler.ts import { ipcMain } from 'electron'; import { stateManager } from '../services/state-manager'; // 登录Handler ipcMain.handle('api:login', async (event, credentials) => { const token = await authenticate(credentials); // 将token存入全局状态 stateManager.setState('authToken', token); return { success: true }; }); // 获取用户信息Handler（依赖authToken状态） ipcMain.handle('api:get-user-info', async (event) => { const token = stateManager.getState<string>('authToken'); if (!token) throw new Error('Not authenticated'); return await fetchUserInfo(token); });

渲染进程订阅状态：

// renderer.ts import { stateManager } from './shared-api'; // 订阅登录态变更 const unsubscribe = stateManager.onStateChange<string>('authToken', (token) => { if (token) { showLoggedInUI(); } else { showLoginUI(); } }); // 窗口卸载时清理 window.addEventListener('beforeunload', unsubscribe);

注意：stateManager本身不处理持久化。若需重启后恢复状态，应在app.ready时从磁盘加载，并在状态变更时写回。这是Shared API与应用生命周期深度耦合的关键点。

4.3 错误处理：Shared API的尊严底线

Shared API的错误处理，不是“try-catch一下再throw”，而是建立统一的错误分类、标准化的消息格式、以及明确的责任归属。

Electron IPC中，主进程throw的Error对象，跨进程后会丢失堆栈和原型，渲染进程收到的只是一个普通对象{ message: 'xxx' }。这导致调试困难、错误归因模糊。

解决方案：定义共享错误类型，并在Preload层重建Error对象

// shared-api.d.ts export enum ApiErrorCode { NETWORK_ERROR = 'NETWORK_ERROR', VALIDATION_ERROR = 'VALIDATION_ERROR', PERMISSION_DENIED = 'PERMISSION_DENIED', NOT_FOUND = 'NOT_FOUND', UNKNOWN_ERROR = 'UNKNOWN_ERROR' } export interface ApiError extends Error { code: ApiErrorCode; details?: Record<string, any>; } export function createApiError( code: ApiErrorCode, message: string, details?: Record<string, any> ): ApiError { const error = new Error(message) as ApiError; error.code = code; error.details = details; return error; }

// preload.js - 错误重建 const api: SharedAPI = { getPreferences: async () => { try { return await ipcRenderer.invoke('api:get-preferences'); } catch (error) { // 重建ApiError if (error && typeof error === 'object' && 'code' in error) { const apiError = new Error(error.message) as ApiError; apiError.code = error.code; apiError.details = error.details; throw apiError; } throw new Error(`Unknown error: ${String(error)}`); } } };

// main.js - 主进程抛出标准错误 ipcMain.handle('api:get-preferences', () => { try { return loadPreferences(); } catch (error) { if (error instanceof ValidationError) { throw createApiError(ApiErrorCode.VALIDATION_ERROR, 'Invalid preferences format', { originalError: error.message }); } throw createApiError(ApiErrorCode.UNKNOWN_ERROR, 'Failed to load preferences'); } });

现在，渲染进程可以精准捕获和处理：

try { const prefs = await window.api.getPreferences(); } catch (error) { if (error.code === ApiErrorCode.VALIDATION_ERROR) { showValidationError(error.details); } else if (error.code === ApiErrorCode.PERMISSION_DENIED) { requestPermission(); } }

错误不再是模糊的“something went wrong”，而是可编程、可分类、可监控的API契约一部分。这才是Shared API成熟的标志。

5. 实战演进：从单窗口Demo到多窗口企业级应用的Shared API演进路径

Shared API的设计不是一蹴而就的静态产物，而是随项目规模、团队协作、业务复杂度动态演进的过程。我参与过的三个典型项目，展示了Shared API如何从“能用”走向“好用”再到“离不开”：

5.1 阶段一：单窗口Demo（1人开发，2周上线）

场景：内部工具，仅一个窗口，功能：读取本地JSON配置、显示、编辑后保存。

Shared API设计：

• 2个API：getSettings(),saveSettings(settings)
• Preload：简单IPC封装，无类型定义（JS编写）
• Handler：主进程内联函数，无状态管理，无日志

痛点暴露：

• 修改配置后，UI未自动刷新（无状态通知）；
• 保存失败时，错误提示笼统（“Save failed”），无法定位是磁盘满还是JSON格式错；
• 新增“导出为CSV”功能时，需在Preload和主进程各加3处代码，易遗漏。

演进动作：

• 引入TypeScript接口，定义Settings类型；
• Preload中增加onSettingsChange订阅；
• Handler中添加基础JSON校验和磁盘空间检查；
• 错误分类：VALIDATION_ERROR,IO_ERROR。

5.2 阶段二：多窗口协作（3人团队，3个月迭代）

场景：跨平台笔记应用，主窗口（编辑）、侧边栏（目录）、弹窗（标签管理），需实时同步笔记列表、标签、搜索状态。

Shared API设计：

• 扩展为7个API：getNotes(),createNote(),updateNote(),deleteNote(),getTags(),searchNotes(query),onNoteChange(cb)
• Preload：按模块拆分（note-api.js,tag-api.js），统一错误处理；
• Handler：引入NoteService、TagService，状态管理初具雏形（内存缓存）；
• 基础监控：日志记录调用频次，Prometheus指标暴露。

痛点暴露：

• 多窗口同时创建笔记，ID冲突（服务层未做分布式ID生成）；
• 搜索API无缓存，频繁输入导致CPU飙升；
• 标签变更时，侧边栏更新了，但主窗口的笔记列表未重新过滤。

演进动作：

• NoteService集成UUID生成，确保ID全局唯一；
• searchNotes增加LRU缓存（lru-cache包），最大100条；
• 状态管理升级：stateManager支持onStateChange，onNoteChange改为stateManager.onStateChange('notes', ...)；
• 增加debounce机制：searchNotes调用前等待用户停止输入300ms。

5.3 阶段三：企业级平台（8人团队，18个月演进）

场景：工业设备监控平台，5类窗口（主控台、设备详情、报警中心、历史曲线、报表生成），需对接12种硬件协议、3个云服务API、本地SQLite数据库。

Shared API设计：

• 分层架构固化：adapter（IPC接入）、service（业务逻辑）、infrastructure（DB、HTTP、硬件驱动）；
• 模块化：device-api.ts,alarm-api.ts,report-api.ts，各模块独立发布、版本管理；
• 状态中枢：stateManager升级为StateHub，支持持久化（SQLite存储）、事件溯源（记录每次状态变更）；
• 安全加固：所有API调用需accessToken校验（JWT），敏感操作（如设备重启）需二次确认；
• 全链路监控：OpenTelemetry集成，追踪从渲染进程调用到硬件驱动的完整耗时；
• 自动化测试：Jest覆盖所有Service层，Mock IPC测试Preload层。

关键演进决策：

1. API版本化：api:v1:get-device-info,api:v2:get-device-info，避免大版本升级导致所有窗口崩溃；
2. 降级策略：当云服务不可用时，getAlarmHistory自动切换到本地SQLite缓存，并返回{ data: [...], fromCache: true }；
3. 资源管理：openDeviceStream(deviceId)返回StreamHandle，调用方必须显式close()，否则主进程自动回收（防内存泄漏）；
4. 开发者体验：自动生成API文档（Swagger格式），VS Code插件提供API调用快捷键和参数提示。

这个演进过程揭示了一个核心规律：Shared API的复杂度，永远匹配业务的真实复杂度。试图用“简单方案”绕过它，只会让技术债以更隐蔽的方式爆发。从阶段一到阶段三，Shared API从“辅助工具”变成了“系统骨架”，它定义了数据流向、错误边界、性能基线和安全水位。

5.4 你的项目，现在处于哪个阶段？

判断你的Shared API健康度，可用这5个问题快速自检：

1. 类型一致性：渲染进程调用api.getUser()，返回值类型是否在TS中100%确定？IDE能否准确补全user.name？
2. 错误可追溯：当api.saveConfig()失败，日志中能否看到完整的错误堆栈、调用窗口ID、发生时间？
3. 状态可预测：在窗口A中调用api.setTheme('dark')，窗口B的onThemeChange回调是否100%触发？有无延迟或丢失？
4. 性能可监控：api.getDevices()平均耗时是多少？P95是否超过500ms？失败率是否稳定在0.1%以下？
5. 演进可持续：新增一个api.exportReport(format)，是否能在30分钟内完成Preload封装、Handler实现、测试覆盖、文档更新？

如果其中任意一项回答“否”，你的Shared API就已亮起黄灯。修复它，比修复十个UI Bug更能延长项目的生命周期。

6. 最后分享：一个让Shared API“活”起来的调试技巧

Shared API最大的挑战，不是写出来，而是看得见、摸得着、调得顺。IPC调用像黑盒，错误常发生在“看不见的地方”。我用过所有调试工具，最终沉淀出一个极简但高效的技巧：在Preload层注入实时IPC监控面板。

它不依赖外部工具，纯前端实现，一行代码接入，即可看到所有API调用的实时状态。

6.1 实现原理：劫持IPC调用，注入可视化层