NocoBase FlowEngine 与插件体系：内核 API 如何驱动业务扩展

NocoBase FlowEngine 与插件体系内核 API 如何驱动业务扩展【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseFlowEngine 是 NocoBase 2.0 中衔接内核能力与业务扩展的关键桥梁它本身不是插件而是作为内核 API 暴露给所有插件使用插件通过this.engine访问它并通过集中化的 Context 统一获取路由、请求、国际化等能力。本文基于当前仓库的 flow-engine-and-plugins.md 展开结合 flowEngine.ts 与 flowContext.ts 的源码实现讲清楚 FlowEngine 与插件的关系、Context 的集中管理机制、插件快捷别名并给出可直接运行的扩展路由示例。读完本文你将掌握在 NocoBase 插件中注册 FlowModel、扩展路由、调用全局能力请求/国际化/数据源的标准姿势。FlowEngine内核 API而非插件FlowEngine是 flow-engine 包的核心类负责管理 flow 模型Model、动作Action、事件Event、模型仓库Model Repository以及上下文它的职责定位在类注释中写得很明确FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more. It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.在 NocoBase 2.0 中所有与流程编排相关的 API 都汇聚在 FlowEngine 这里插件可以通过this.engine访问 FlowEngine。这一点在 flowEngine.ts 的FlowEngine类定义中得到印证类中聚合了以下几类核心能力模型注册与查找registerModels、getModelClass、getSubclassesOf、findModelClass支持模型类的继承过滤与异步加载动作与事件注册registerActions/getAction、registerEvents/getEvent模型实例生命周期createModel、getModel、saveModel、destroyModel、replaceModel、moveModel、duplicateModel模型仓库通过setModelRepository注入实现IFlowModelRepository的仓库用于持久化与查询上下文与视图渲染集成FlowEngineContext、FlowSettings、ReactView支持 React 视图渲染与国际化。一个插件要扩展 FlowEngine 的能力典型写法如下class PluginHello extends Plugin { async load() { this.engine.registerModelLoaders({ ... }); } }这里registerModelLoaders是 FlowEngine 提供的异步模型加载器注册入口它的输入类型定义在 types.tsexport interface FlowModelLoaderInput { loader: FlowModelLoader; // 异步加载函数返回模型构造函数或模块对象 extends?: string | ModelConstructor | (string | ModelConstructor)[]; } export type FlowModelLoaderInputMap Recordstring, FlowModelLoaderInput;其中loader() PromiseFlowModelLoaderResult加载结果可以是模型构造函数本身、模块的 default 导出或包含同名命名导出的模块对象见 flowEngine.ts 的normalizeModelLoaderResult归一化逻辑extends声明父类可传字符串、构造函数或数组用于getSubclassesOfAsync的异步子类发现内部会被归一化为string[]见 flowEngine.ts。官方文档示例中的写法是flowEngine.registerModelLoaders({ DemoModel: { extends: BaseModel, loader: () import(./models/DemoModel), }, });借助extends声明FlowEngine 可以做到先按需加载、再异步发现子类getSubclassesOfAsync会先收集已加载的类再扫描所有未加载 loader 中extends命中目标基类的条目并逐个解析解析后用isInheritedFrom校验真实继承关系不匹配的会告警并跳过见 flowEngine.ts。仓库中的单元测试 flowEngine.modelLoaders.test.ts 验证了这一整套异步加载链测试注册了ParentModel/ChildModel/DefaultChildModel三个 loader其中ParentModel通过define({ createModelOptions: { subModels: ... } })声明了 meta 默认子模型然后调用engine.loadOrCreateModel创建模型树断言父子模型实例类型正确——这正是显式模型树 meta 默认模型树在同步创建前被统一解析的源码级证据。Context集中管理的全局能力FlowEngine 提供了一个中心化的Context将各种场景所需的 API 汇聚在一起。从源码看这个 Context 就是FlowEngine的context属性懒加载创建get context() { if (!this._flowContext) { this._flowContext new FlowEngineContext(this); } return this._flowContext; }FlowEngineContext继承自BaseFlowEngineContext见 flowContext.ts基类声明的核心能力包括declare t: (key: any, options?: any) string; // 国际化翻译 declare router: Router; // 路由对象 declare dataSourceManager: DataSourceManager; // 数据源管理器 declare api: APIClient; // API 客户端 declare locale: string; // 当前语言 declare engine: FlowEngine; // 引擎实例自身 declare runAction: (actionName: string, params?: Recordstring, any) Promiseany | any;在FlowEngineContext的构造函数中这些能力被逐一装配见 flowContext.ts创建DataSourceManager并挂载到引擎同时内置一个key: main的主数据源通过defineProperty(sql, ...)暴露FlowSQLRepositorySQL 辅助仓库cache: false每次即时创建通过defineProperty(dataSourceManager, ...)暴露数据源管理器通过defineMethod(t, ...)绑定FlowI18n.translate实现国际化通过defineProperty(locale, ...)提供当前语言优先取api.auth.locale回退到i18n.language。插件中可以直接这样使用class PluginHello extends Plugin { async load() { // 路由扩展 this.engine.context.router; // 发起请求 this.engine.context.api.request(); // 国际化相关 this.engine.context.i18n; this.engine.context.t(Hello); } }Context 的可扩展性同样重要插件可以用defineProperty/defineMethod向 Context 注入自定义能力。仓库内置插件 LocalePlugin.ts 就是例证——它通过this.engine.context.defineProperty(locales, { value: data?.data || {} })把语言包注入 Contextcustom-repository demo 也演示了如何用this.engine.context.defineProperty(customRepository, ...)挂载自定义仓库供后续流程步骤读取。为什么 2.0 需要集中式 Context原文档明确列出了 Context 在 2.0 中解决的 1.x 三个问题上下文分散调用不统一不同 React 渲染树之间会丢失上下文只能在 React 组件内使用集中式 Context 把能力从哪来收敛到唯一入口插件不再各自维护零散的上下文对象同时 Context 与具体 React 渲染树解耦可以在组件之外如模型生命周期、流程执行器、调度器中统一访问从而规避渲染树切换导致的上下文丢失问题。插件中的快捷别名为了简化调用FlowEngine 在插件实例上提供了部分别名this.context→ 等价于this.engine.contextthis.router→ 等价于this.engine.context.router这个设计在 Plugin 基类文档 中同样有体现Plugin基类为app的部分方法/属性提供了快捷访问例如get router() { return this.app.router; }插件生命周期钩子也值得注意afterAdd插件被添加后立即执行→beforeLoad渲染时执行→load最后执行。路由扩展等初始化逻辑通常放在load中执行确保应用与引擎已就绪。示例扩展路由原文档给出了一个完整的、可直接运行的扩展路由示例import { createMockClient, Plugin } from nocobase/client; class PluginHelloModel extends Plugin { async afterAdd() {} async beforeLoad() {} async load() { this.router.add(root, { path: /, element: divHello/div, }); } } // 用于示例和测试场景 const app createMockClient({ plugins: [PluginHelloModel], }); export default app.getRootComponent();在这个示例中插件通过this.router.add方法扩展了/路径的路由createMockClient提供了一个干净的 Mock 应用便于示例和测试app.getRootComponent()返回根组件可以直接挂载到页面。this.router.add(root, { path, element })是注册路由的标准 API第一个参数是路由名称需全局唯一第二个参数是路由配置其中path为路径、element为要渲染的 React 组件。createMockClient的用途是隔离真实应用环境让插件在最小依赖下完成注册与验证因此它也被广泛用于 flow-engine 包的组件测试例如 provider.test.tsx 等测试文件中的 Mock 应用场景。从插件到 FlowModel一条完整的扩展链路把上面的知识点串联起来一个插件在 NocoBase 2.0 中扩展流程能力的完整链路是注册模型类在load()中用this.engine.registerModels({ MyModel })直接注册或用registerModelLoaders注册异步加载器适合大模型按需加载注册动作/事件用registerActions/registerEvents为模型补充可复用的动作定义与事件定义注入模型仓库用setModelRepository设置实现IFlowModelRepository的持久化仓库支撑saveModel/loadModel/destroyModel等读写操作使用 Context通过this.engine.context或别名this.context访问路由、API 客户端、国际化、数据源管理器等全局能力扩展界面通过this.router.add添加路由页面通过reactView/flowSettings参与视图渲染与配置。FlowEngine 在构造时见 flowEngine.ts还会自动完成三件基础装配注册FlowModel基类、注册FlowResource/SQLResource/APIResource/SingleRecordResource/MultiRecordResource五类资源、通过registerScopes({ t })把国际化注入 FlowSettings。这意味着插件拿到的是一个开箱即用的内核模型、资源、国际化、日志、执行器均已就绪插件只需在此基础上做业务扩展。这种内核提供底座、插件负责扩展的分层正是 NocoBase 2.0 FlowEngine 与插件体系的核心设计FlowEngine 保持轻量与可组合业务差异全部由插件通过注册机制注入从而兼顾内核稳定性与业务扩展性。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考