简介

通信服务模块。提供三种传输模式用于控制器方法路由：

• SocketServer：Socket.IO 服务，用于第三方软件通信（Go、Python 后端等），通过 WebSocket 交互
• HttpServer：基于 Koa 的 RESTful HTTP/HTTPS 服务，用于外部 API 调用
• IpcServer：Electron IPC 服务，用于主进程 ↔ 渲染进程通信，通过 ipcMain/ipcRenderer

三者共享 resolveControllerFn() 路由机制。通道格式：controller/{name}/{method}。

导入

// CJS
const {
  SocketServer,
  HttpServer,
  IpcServer,
  loadSocket,
  createSocketServer,
  createHttpServer,
  createIpcServer,
  getSocketServer,
  getHttpServer,
  getIpcServer,
  Koa,
  IoServer,
  IoClient,
} = require('ee-core/socket');

// ESM
import {
  SocketServer,
  HttpServer,
  IpcServer,
  loadSocket,
  createSocketServer,
  createHttpServer,
  createIpcServer,
  getSocketServer,
  getHttpServer,
  getIpcServer,
  Koa,
  IoServer,
  IoClient,
} from 'ee-core/socket';

SocketServer

Socket.IO 服务。为第三方软件（非 Electron 渲染进程）提供 WebSocket/HTTP 轮询通信，调用主进程控制器方法。

通信协议：

• 客户端连接并在指定通道上发送消息：{ cmd: 'controller/user/add', args: {...} }
• 服务端解析 cmd 路径并调用对应控制器方法
• 控制器执行结果通过回调返回给客户端

使用工厂模式创建（static create()），因为初始化需要异步端口获取。当配置中 enable=false 时，创建后服务不会启动。

SocketServer.create()

说明：工厂方法 — 创建并初始化 SocketServer 实例。获取可用端口，创建 Socket.IO Server 实例，并设置连接监听器。端口编号写入 process.env.EE_SOCKET_PORT 供其他模块访问。 返回值：Promise<SocketServer> — 完全初始化的 SocketServer 实例。

SocketServer.init()

说明：初始化 Socket.IO 服务。如果 config.enable === false，立即返回不启动。否则获取端口、创建 Socket.IO Server 并调用 connect()。 返回值：Promise<void>

SocketServer.connect()

说明：监听客户端连接并处理消息。客户端连接后，在配置的通道（默认 'socket-channel'）上监听。收到消息后，通过 cmd 路径路由到对应控制器方法。结果通过回调返回客户端。错误以 { __EE_ERROR__: true, message: string } 返回。 返回值：void

SocketServer.io

说明：已实例化的 Socket.IO Server 对象。 类型：Server | undefined — 初始化前或 enable=false 时为 undefined。

属性和方法遵循 Socket.IO Server API：https://socket.io/docs/v4/server-api/

关键方法：

• io.emit(eventName[, ...args]) — 广播给所有连接的客户端
• io.on(eventName, listener) — 监听服务端级事件
• io.close([callback]) — 关闭服务

SocketServer.socket

说明：通过 io.on('connection') 建立的 socket 对象。表示当前连接的客户端 socket 实例。 类型：ReturnType<Server['on']> | undefined — 客户端连接前为 undefined。

Socket.IO Socket API：https://socket.io/docs/v4/server-api#socket

SocketServer.config

说明：Socket.IO 服务配置对象。 类型：SocketServerConfig — 包含 enable、port、path、channel、cors、transports 等。

SocketServer.channelSeparator

说明：用于控制器路径路由的通道分隔符。 类型：string — 默认 '/'。

HttpServer

基于 Koa 的 HTTP/HTTPS 服务。提供 RESTful API 服务，将 HTTP 请求路由到对应控制器方法。

请求路由规则：

• URL 路径映射到控制器路径，如 /controller/user/add → controller.user.add
• GET 请求参数来自 query，POST 请求参数来自 body
• 以 'controller' 开头的路径直接使用；否则自动添加 'controller' 前缀
• filterRequest 中的 URI 直接返回指定数据，不经过控制器

中间件加载顺序：

1. 错误处理器（errorHandler）
2. 前置中间件（preMiddleware）
3. CORS 跨域中间件
4. koa-body 请求体解析中间件
5. 核心路由分发中间件（_dispatch）
6. 后置中间件（postMiddleware）

使用工厂模式创建（static create()）。当配置中 enable=false 时，创建后服务不会启动。

HttpServer.create()

说明：工厂方法 — 创建并初始化 HttpServer 实例。获取可用端口，创建带中间件的 Koa 应用，并启动 HTTP/HTTPS 监听。端口编号写入 process.env.EE_HTTP_PORT 供其他模块访问。 返回值：Promise<HttpServer> — 完全初始化的 HttpServer 实例。

HttpServer.init()

说明：初始化 HTTP 服务。如果 config.enable === false，立即返回。否则获取端口并调用 _create()。 返回值：Promise<void>

HttpServer._create()

说明：创建 Koa 应用并启动 HTTP/HTTPS 服务。按顺序加载中间件，处理 HTTPS/SSL 配置，在配置的 host 和 port 上启动监听。 返回值：Promise<void>

HttpServer._dispatch(ctx, next)

说明：核心路由分发中间件。将 HTTP 请求路径映射到控制器方法：

1. 移除路径开头的 '/'
2. 检查路径是否在过滤列表中（如 favicon.ico）
3. 确保路径以 'controller' 开头
4. 通过 resolveControllerFn 查找并调用控制器方法
5. GET 请求传递 query 参数，POST 请求传递 body 参数

错误处理：控制器方法抛出异常时返回 HTTP 500 + { error: 'Internal Server Error' }。 参数：

参数	类型	必填	说明
ctx	Koa.Context	是	Koa 请求上下文
next	Koa.Next	是	下一个中间件函数

返回值：Promise<void>

HttpServer.getHttpApp()

说明：获取 Koa 应用实例。 返回值：Koa | undefined — Koa 实例，HTTP 服务未启用时为 undefined。 示例：

import { getHttpServer } from 'ee-core/socket';
const httpApp = getHttpServer().getHttpApp();

HttpServer._setupErrorHandler(app, errorHandler)

说明：设置 Koa 错误处理器。将提供的函数注册为 Koa 'error' 事件监听器。 参数：

参数	类型	必填	说明
app	Koa	是	Koa 应用实例
errorHandler	`((err: Error) => void)	null`	是

返回值：void

HttpServer._loadMiddlewares(app, middlewares, type)

说明：加载前置/后置中间件。中间件可以是工厂函数（调用后返回 Koa 中间件）或直接中间件函数。无效中间件会被跳过并输出警告。 参数：

参数	类型	必填	说明
app	Koa	是	Koa 应用实例
middlewares	unknown[]	否	中间件数组，默认 []
type	string	否	类型标识（'pre' 或 'post'），默认 'pre'

返回值：void

HttpServer.config

说明：HTTP 服务配置对象。 类型：HttpServerConfig — 包含 enable、port、host、protocol、https、cors、body、filterRequest、koaConfig 等。

HttpServer.channelSeparator

说明：用于控制器路径路由的通道分隔符。 类型：string — 默认 '/'。

IpcServer

Electron IPC 服务。将控制器方法注册为 ipcMain 通道处理器，使渲染进程可通过 ipcRenderer 调用主进程控制器方法。

支持两种通信模型：

• send/on 模型（同步）：渲染进程使用 ipcRenderer.sendSync()，主进程通过 event.returnValue 返回结果。支持同步和异步控制器方法（Electron 的 sendSync 进入嵌套消息循环处理微任务）。
• invoke/handle 模型（异步，推荐）：渲染进程使用 ipcRenderer.invoke()，主进程通过 ipcMain.handle() 返回 Promise。支持同步和异步控制器方法。

通道命名规则：将控制器路径中的 '.' 替换为 channelSeparator（默认 '/'）。如：controller.user.add → controller/user/add。

IpcServer.constructor()

说明：创建并初始化 IpcServer 实例。从配置读取 channelSeparator，然后遍历控制器对象树注册所有 IPC 通道。 返回值：IpcServer — 初始化的实例。

IpcServer.init()

说明：初始化 — 遍历控制器树并注册所有 IPC 通道处理器。由构造函数自动调用。 返回值：void

IpcServer.loop(obj, pathname)

说明：递归遍历控制器对象树。通过 EXPORTS symbol 标记区分：

• 带 EXPORTS 标记的对象 → 叶节点（控制器方法集合），调用 register()
• 不带标记的对象 → 中间节点（目录/命名空间），继续递归 参数：

参数	类型	必填	说明
obj	Record<string, unknown>	是	当前遍历的对象
pathname	string	是	当前属性路径

返回值：void

IpcServer.register(exportObj, propertyChain)

说明：将控制器方法注册为 IPC 通道处理器。为每个方法注册两个处理器：

1. ipcMain.on（send/on 模型）：设置 event.returnValue，支持异步方法。错误以 { __EE_ERROR__: true, message: string } 返回。
2. ipcMain.handle（invoke/handle 模型）：返回 Promise。错误会导致渲染进程的 ipcRenderer.invoke() 拒绝。 参数：

参数	类型	必填	说明
exportObj	Record<string, unknown>	是	控制器方法集合对象
propertyChain	string	是	属性路径（如 'controller.user'）

返回值：void

IpcServer.channelSeparator

说明：用于 IPC 通道名生成的通道分隔符。 类型：string — 默认 '/'。

IpcServer.directory

说明：控制器目录名，用作属性路径前缀。 类型：string — 'controller'。

工厂函数

模块级函数，用于创建、获取和初始化通信服务实例。

loadSocket()

说明：加载并初始化所有通信服务。按顺序创建：SocketServer → HttpServer → IpcServer。在框架启动流程中由 Application.run() 调用。 返回值：Promise<void>参见：ps 模块 — getSocketPort() / getHttpPort() 返回此初始化过程中设置的端口。

createSocketServer()

说明：通过 SocketServer.create() 创建 SocketServer 实例并存储到模块实例注册表。 返回值：Promise<SocketServer> — 创建的 SocketServer 实例。

createHttpServer()

说明：通过 HttpServer.create() 创建 HttpServer 实例并存储到模块实例注册表。 返回值：Promise<HttpServer> — 创建的 HttpServer 实例。

createIpcServer()

说明：创建 IpcServer 实例并存储到模块实例注册表。与 SocketServer 和 HttpServer 不同，IpcServer 创建是同步的。 返回值：IpcServer — 创建的 IpcServer 实例。

getSocketServer()

说明：获取 SocketServer 实例。在 Ready 生命周期事件之前调用（即 createSocketServer() 未被调用时）抛出 Error。 返回值：SocketServer — 存储的 SocketServer 实例（非 null）。 示例：

import { getSocketServer } from 'ee-core/socket';
const server = getSocketServer();
server.io.emit('channel-name', 'data');

TIP

v5 变更：getSocketServer() 返回 SocketServer（而非 SocketServer | null）。在服务创建前调用会抛出 Error。

getHttpServer()

说明：获取 HttpServer 实例。在 Ready 生命周期事件之前调用（即 createHttpServer() 未被调用时）抛出 Error。 返回值：HttpServer — 存储的 HttpServer 实例（非 null）。 示例：

import { getHttpServer } from 'ee-core/socket';
const httpApp = getHttpServer().getHttpApp();

TIP

v5 变更：getHttpServer() 返回 HttpServer（而非 HttpServer | null）。

getIpcServer()

说明：获取 IpcServer 实例。在 Ready 生命周期事件之前调用（即 createIpcServer() 未被调用时）抛出 Error。 返回值：IpcServer — 存储的 IpcServer 实例（非 null）。 示例：

import { getIpcServer } from 'ee-core/socket';
const ipc = getIpcServer();

TIP

v5 变更：getIpcServer() 返回 IpcServer（而非 IpcServer | null）。

重新导出的库

socket 模块重新导出底层库类，供应用代码直接使用。

Koa

说明：原始 Koa 类（import Koa from 'koa'），为方便使用而重新导出。用于添加自定义中间件或扩展 HTTP 服务时使用。 返回值：Koa 类（构造函数）。 示例：

import { Koa } from 'ee-core/socket';
const app = new Koa();

IoServer

说明：原始 Socket.IO Server 类（import { Server } from 'socket.io'），为方便使用而重新导出。用于创建额外的 Socket.IO 实例时使用。 返回值：socket.io 的 Server 类。 示例：

import { IoServer } from 'ee-core/socket';

IoClient

说明：原始 Socket.IO 客户端模块（import IoClient from 'socket.io-client'），为方便使用而重新导出。用于从外部进程连接 Socket.IO 服务时使用。 返回值：socket.io-client 模块。 示例：

import { IoClient } from 'ee-core/socket';
const socket = IoClient('http://localhost:7070');

外部参考

• Socket.IO 官方文档：https://socket.io/
• Socket.IO Server API：https://socket.io/docs/v4/server-api/
• Koa 文档：https://koajs.com/