Activepieces CE/EE 分层架构与 Edition Safety 规则实战:hooksFactory 扩展机制深度解析
Activepieces CE/EE 分层架构与 Edition Safety 规则实战:hooksFactory 扩展机制深度解析
本文围绕 Activepieces 仓库中 .claude/rules/edition-safety.md 这一开发规范文档展开,系统讲解 Community Edition(CE)与 Enterprise Edition(EE)两套代码层如何在同一仓库中共存、隔离与扩展:CE 代码为什么禁止 import EE 模块,以及 EE 如何通过 hooksFactory.create<T>(ceDefault) + .set(eeImpl) 的钩子机制无侵入地替换 CE 默认行为。读完本文,你将掌握 Activepieces 服务端的分层边界、edition 启动分支原理,以及如何为 CE 功能设计可被 EE 覆盖的扩展点。
一、规则文档在说什么:两条铁律
仓库 .claude/rules/edition-safety.md 全文只有两条约束,却是整个服务端分层架构的安全底线:
- CE 代码严禁 import
src/app/ee/下的任何模块——CE 与 EE 是两个独立的代码层,不允许单向依赖,更不允许反向依赖; - EE 扩展 CE 行为必须走钩子机制:在 CE 中用
hooksFactory.create<T>(ceDefault)声明扩展点并给出默认实现,然后在app.ts的 edition 分支中通过.set(eeImpl)注入 EE 实现。
这两条规则共同保证:同一份代码库可以编译出 Community、Enterprise、Cloud 三种 edition 的产物,CE 代码在编译期不感知 EE 的存在,而 EE 可以在启动时按需替换 CE 的默认行为。
二、背景:CE 与 EE 如何在同一仓库中分层
在 packages/server/api/src/app 目录下,代码按功能模块组织为两类:
- CE(Community Edition)层:即
src/app/下的常规模块,如flows/、project/、authentication/、waitpoints/、flags/、webhooks/等,是开源可用的基础能力; - EE(Enterprise Edition)层:集中在 packages/server/api/src/app/ee 目录下,包含
authentication/project-role/(RBAC)、flags/enterprise-flags.hooks.ts、platform/platform-plan/(计费与套餐)、projects/project-release/(项目发布)、piece-filtering、license-key-usage-report(许可证用量上报)等企业级能力。
CE 代码被要求不得感知 EE 目录的存在。如果 CE 模块直接 import EE 模块,会造成两层强耦合:CE 的构建产物会意外携带 EE 代码、模块初始化顺序被破坏、单测环境可能因缺少 EE 依赖而崩溃。因此规则第一条是硬性的 import 禁令。
三、扩展点基座:hooksFactory 的实现原理
EE 想要在"不触碰 CE 代码"的前提下替换行为,靠的是 hooks-factory.ts 中定义的极简工厂:
import { isNil } from '@activepieces/core-utils'
import { FastifyBaseLogger } from 'fastify'
export const hooksFactory = {
create<T>(defaultHooks: (log: FastifyBaseLogger) => T) {
let hooksCreator: (log: FastifyBaseLogger) => T
return {
set(newHooksCreator: (log: FastifyBaseLogger) => T): void {
hooksCreator = newHooksCreator
},
get(log: FastifyBaseLogger): T {
if (isNil(hooksCreator)) {
return defaultHooks(log)
}
return hooksCreator(log)
},
}
},
}
其工作方式非常直白:
create<T>(defaultHooks):CE 模块在定义扩展点时调用它,传入一个返回默认实现的工厂函数(log) => T。返回值是一个带set/get两个方法的句柄,闭包变量hooksCreator初始为空;set(newHooksCreator):EE 在应用启动阶段调用,把默认实现替换成自己的工厂函数;get(log):业务代码运行时调用。若从未被set过(CE 场景),hooksCreator为nil,回退到默认实现;若被set过(EE/Cloud 场景),返回 EE 实现。
注意一个关键设计:defaultHooks 与 EE 实现都是惰性工厂函数,真正实例化发生在 get(log) 被调用时,且 FastifyBaseLogger 作为参数传入,使钩子实现可以拿到当前请求/进程的日志器。这种"先注册、后解析"的写法让 CE 模块永远不必知道 EE 是否存在。
四、接线中枢:app.ts 的 edition 切换
规则文档提到的 ".set(eeImpl) in app.ts edition switch",对应 app.ts 中的启动逻辑:
const edition = system.getEdition()
app.log.info({ edition }, 'Activepieces Edition')
switch (edition) {
case ApEdition.CLOUD:
await app.register(adminPlatformModule)
// ... 大量企业级模块注册
setPlatformOAuthService(platformOAuth2Service(app.log))
projectHooks.set(projectEnterpriseHooks)
flagHooks.set(enterpriseFlagsHooks)
publishHooksFactory.set(eeFlowPublishHook)
billingProvider.set(autumnBillingProvider)
resumePageHooks.set((log) => ({ getTheme: (params) => appearanceHelper.getTheme({ ...params, log }) }))
flowPublishHooks.set(() => ({ assertReferencesResolve: assertAgentsResolveInProject }))
exceptionHandler.initializeSentry(system.get(AppSystemProp.SENTRY_DSN))
break
case ApEdition.ENTERPRISE:
// 注册 subset 的企业模块 + 相同的 .set(...) 注入
...
break
// case ApEdition.COMMUNITY: 不注册企业模块,不调用任何 .set(...)
}
从源码结构可以推断,ApEdition 至少包含 CLOUD、ENTERPRISE 与 COMMUNITY 三种取值(具体枚举定义见 @activepieces/shared 的 edition 类型):
- CLOUD / ENTERPRISE 分支:
app.register(...)注册一批企业级模块(如projectMemberModule、gitRepoModule、auditEventModule、scimModule、flowApprovalModule、agentModule等),并在注册完成后集中执行各个钩子的.set(...)注入 EE 实现; - COMMUNITY 分支:不注册企业模块,也不调用任何
.set(),所有钩子保持 CE 默认实现——这正是"同一份代码、三种产物"的开关所在。
这种"模块注册 + 钩子注入"双轨并行的写法,让 EE 能力既能以 Fastify 插件形式整体挂载(新增路由与表),也能以钩子形式替换既有 CE 行为(覆盖语义而不改路由)。
五、实战案例:流程发布钩子被 EE 覆盖为审批流
flow-publish-hooks.ts 是 hooksFactory 用法的典型范本。CE 侧在 flow-publish-hooks.ts 中定义类型与默认实现:
export type PublishRoute = 'PUBLISH_NOW' | 'NEEDS_APPROVAL'
export type PublishHooks = {
routePublish(params: RoutePublishParams): Promise<PublishRoute>
submitForApproval(params: SubmitForApprovalParams): Promise<void>
}
export const publishHooksFactory = hooksFactory.create<PublishHooks>(_log => ({
async routePublish(_params: RoutePublishParams): Promise<PublishRoute> {
return 'PUBLISH_NOW'
},
async submitForApproval(_params: SubmitForApprovalParams): Promise<void> {
return
},
}))
export const flowPublishHooks = hooksFactory.create<FlowPublishHooks>(() => ({
async assertReferencesResolve(): Promise<void> {
return
},
}))
语义非常清晰:
- CE 默认:发布路由直接返回
'PUBLISH_NOW'(一键发布),submitForApproval为空操作,assertReferencesResolve不做任何校验; - 当 edition 为 CLOUD/ENTERPRISE 时,app.ts 执行
publishHooksFactory.set(eeFlowPublishHook),把发布语义替换为:先assertAgentsResolveInProject校验 Agent 引用是否可解析,再由 EE 实现决定走'PUBLISH_NOW'还是'NEEDS_APPROVAL',并落地submitForApproval审批提交流程——这正是 Activepieces 流程发布审批(flow approval)的企业能力。
对于想要在 CE 侧新增可扩展点的开发者,照此模式即可:先在 CE 定义好 XxxHooks 类型与 hooksFactory.create<XxxHooks>(默认实现),业务代码只调 .get(log),EE 侧在 app.ts 对应分支 .set(eeImpl) 覆盖。全程不需要 CE 与 EE 互相 import。
六、更多钩子实例:仓库中的同款模式
除流程发布外,仓库中还有多个遵循同一模式的扩展点,可作为补充印证:
- project-hooks.ts:项目生命周期钩子,EE 侧由 ee-project-hooks.ts 通过
projectHooks.set(projectEnterpriseHooks)注入(app.ts),用于承载企业版项目级校验与默认配置; - resume-page-hooks.ts:等待点恢复页面的主题钩子,Cloud 分支用
resumePageHooks.set((log) => ({ getTheme: (params) => appearanceHelper.getTheme({ ...params, log }) }))注入企业外观主题(app.ts); - enterprise-flags.hooks.ts:企业功能开关钩子,通过
flagHooks.set(enterpriseFlagsHooks)覆盖 CE 的 flag 默认值(app.ts); - billing-provider.ts:计费提供方钩子,Cloud 分支
billingProvider.set(autumnBillingProvider)注入云计费实现(app.ts)。
由此可见,"CE 定义接口与默认行为、EE 在启动时替换实现"是贯穿整个服务端的企业扩展设计范式,并非某个模块的孤例。
七、开发实践:如何遵守 edition-safety 规则
把规则文档落到日常开发中,可以总结为如下检查清单:
- 定位你的改动:新增功能属于 CE 基础能力,还是 EE 企业能力?企业能力一律放入 packages/server/api/src/app/ee 对应模块下;
- 检查 import 方向:在 CE 目录(
src/app/非 ee 子目录)的代码中,import ... from '../ee/...'或from './ee/...'都属于违规依赖,应立即重构; - 优先复用钩子:当 EE 需要改变某个 CE 行为时,不要修改 CE 文件,而是确认该模块是否已有 hooksFactory 扩展点;若没有,在 CE 侧新增
hooksFactory.create<T>(ceDefault),并让业务代码通过.get(log)调用; - 接线放在 app.ts:在 app.ts 的
CLOUD/ENTERPRISE分支中集中执行.set(eeImpl),保持 edition 分支单一可信; - 保持默认实现可用:CE 默认实现必须能独立支撑 Community 场景(如发布直接
PUBLISH_NOW、不校验、不审批),这样未set时系统依然可用; - 验证隔离性:可用
rg "from ['\"]\.\./ee|from ['\"]\./ee" packages/server/api/src/app --glob '!**/ee/**'之类的检索确认 CE 目录没有反向引用 EE 的 import。
八、小结
edition-safety.md 用两句话概括了 Activepieces 服务端最核心的架构纪律:依赖方向只能从 EE 指向 CE(通过启动期注入),CE 永不感知 EE。底层支撑是 hooks-factory.ts 的 create/set/get 三方法闭包工厂,配合 app.ts 中 system.getEdition() 驱动的 edition 分支集中接线,使 Community、Enterprise、Cloud 三种 edition 得以共享全部 CE 代码,同时让企业能力以可插拔、可测试的方式叠加。理解这套模式,是向 Activepieces 服务端贡献代码或扩展企业功能的前提,也是阅读 packages/server/api/src/app 目录代码时最快的导航地图。