SuperAPI AI 工具集

syncable-entity-builder-and-validation

编程与开发

查看项目

更新于 10-16 02:15

技能介绍

用途 本步骤属于 Twenty 代码库(twentyhq/twenty 服务端内部)的可同步实体开发流程,位于第 3/6 步。其目标是实现业务规则校验,并创建迁移动作构建器(migration action builders)。适用时机为完成第 1-2 步(类型、缓存、转换)之后,且必须在实现动作处理器之前完成。注意:该资料面向 Twenty 代码库本身的贡献,不适用于在 Twenty 之上构建应用。

本步骤创建的内容 一是校验服务(业务逻辑校验),二是构建器服务(动作创建),三是编排器接线(资料标注为 CRITICAL,且常被遗漏)。

核心原则 资料给出的关键原则包括:校验器从不抛出异常,而是返回错误数组;校验器不做变更,使用乐观实体映射(optimistic entity maps)传入;使用索引查找(O(1)),而不是 Object.values().find()(O(n))。

使用方式(按资料步骤) 第 1 步:创建校验服务。文件为 src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service.ts。示例类为 FlatMyEntityValidatorService,包含 validateMyEntityForCreate、validateMyEntityForUpdate、validateMyEntityForDelete 三个方法。创建校验包含四类模式:必填字段校验、唯一性校验(使用索引映射 O(1))、外键校验(父实体不存在或已删除)、标准实体保护(isCustom === false 时不可创建)。更新校验包含标准实体保护与名称变更的唯一性校验,并在标准实体时提前 return。删除校验包含标准实体保护。

资料给出性能警告:避免 Object.values().find(),应使用索引映射。示例中给出反例(O(n))与正例(O(1))。

第 2 步:创建构建器服务。文件为 src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service.ts。示例类 WorkspaceMigrationMyEntityActionsBuilderService 继承 WorkspaceEntityMigrationBuilderService,构造函数注入 FlatMyEntityValidatorService,并实现 buildCreateAction、buildUpdateAction、buildDeleteAction;各方法先调用对应校验,若校验结果数组非空则返回 { status: 'failed', errors },否则返回 { status: 'success', action },action 中包含 type、metadataName、universalFlatEntity(update 还包含 universalUpdates)。

第 3 步:接入编排器(CRITICAL)。文件为 src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-build-orchestrator.service.ts。需在构造函数注入 WorkspaceMigrationMyEntityActionsBuilderService,在 buildWorkspaceMigration 中调用其 build 方法(传入 flatEntityToCreate/flatEntityToUpdate/flatEntityToDelete、flatEntityMaps、isSystemBuild),并聚合错误、把 actions 加入返回语句。资料提示这是最常被遗忘的一步,未接入编排器实体将无法同步。

校验模式汇总 资料列出四种校验模式:必填字段;唯一性(O(1) 查找,使用 optimisticMaps.byName);外键校验(父实体不存在或已删除);标准实体保护(isCustom === false 时返回错误并提前 return)。

检查清单(进入第 4 步前) 校验服务已创建;校验器从不抛异常(返回错误数组);校验器不做变更(使用乐观映射);所有唯一性检查使用索引映射(O(1));已实现必填字段校验;已实现外键校验;已实现标准实体保护;构建器继承 WorkspaceEntityMigrationBuilderService;构建器使用 universal 实体创建动作;构建器已接入编排器(CRITICAL);构建器已在编排器构造函数注入;构建器已在 buildWorkspaceMigration 中调用;动作已加入编排器返回语句。

适用场景与限制 适用于按官方规则为 Twenty 增加可同步实体的服务端内部开发。限制包括:必须在前两步完成后进行;必须在实现动作处理器前完成;不适用于在 Twenty 之上构建应用。资料未提供收费、价格、平台、效果等额外信息。