Baserow 集成与服务类型开发指南创建与更新 IntegrationType / ServiceType 的完整实践【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow导读本文是 Baserow 开源仓库中面向开发者的实操指南讲解如何在contrib/integrations技术栈中创建或更新「集成类型IntegrationType」与「服务类型ServiceType」并让同一个可复用服务被 Application Builder 数据源、Builder 工作流动作、自动化节点动作、自动化节点触发器、Dashboard 数据源等产品面消费。读完本文你将掌握 Baserow 前后端类型注册体系、DispatchTypes 分发语义、导入导出 ID 迁移、以及各产品面包装层wrapper的完整落地步骤与测试要求。Baserow 是开源的「无代码数据库、自动化、应用与 AI Agent 平台」。在其架构中集成Integration与服务Service被 Application Builder、Dashboard 和 Automation 三大工具共享可复用的服务本体位于contrib/integrations各产品专属对象数据源、工作流动作、自动化节点通常只是对该服务的包装。本文的核心骨架来自仓库内.agents/skills/create-update-service/SKILL.md并结合真实源码逐一印证每个环节。一、先理解服务的使用面Service Usage Map动手改代码之前必须先确定目标服务将被暴露在哪个产品面上。不同产品面对应的后端包装层、前端包装层和**必需的分发类型dispatch type**完全不同官方文档用一张表做了精确映射产品面后端包装层前端包装层必需分发类型Builder 数据源DataSource.service位于 backend/src/baserow/contrib/builder/data_sources/**服务类型注册于 web-frontend/modules/integrations/plugin.js 并被 Builder 数据源 UI 使用DispatchTypes.DATADashboard 数据源DashboardDataSource.service位于 backend/src/baserow/contrib/dashboard/**服务类型注册于 integrations 插件与 dashboard 表单/UIDispatchTypes.DATABuilder 工作流动作backend/src/baserow/contrib/builder/workflow_actions/workflow_action_types.py 中的BuilderWorkflowServiceActionType子类 工作流动作模型web-frontend/modules/builder/workflowActionTypes.js 中的WorkflowActionType子类DispatchTypes.ACTION自动化动作节点backend/src/baserow/contrib/automation/nodes/node_types.py 中的AutomationNodeActionNodeType子类 自动化节点模型web-frontend/modules/automation/nodeTypes.js 中的ActionNodeTypeMixin节点类型DispatchTypes.ACTION自动化触发器节点node_types.py中的触发器节点类型通常使用TriggerServiceTypeMixinnodeTypes.js中的TriggerNodeTypeMixin节点类型触发器能力服务类型关键原则对于数据源服务声明DispatchTypes.DATA通常就足够了因为产品对象直接指向该服务而对于工作流动作和自动化节点还需要额外添加包装类型/模型服务才会出现在动作/节点注册表中。分发类型的语义在源码中有明确定义。backend/src/baserow/core/services/registries.py 中的DispatchTypes枚举class DispatchTypes(str, Enum): # A ServiceType which performs an action. ACTION action # A ServiceType which fetches data. DATA data # A ServiceType which responds to events. EVENT event而ServiceType基类通过dispatch_types: List[DispatchTypes]列表声明能力并提供can_be_dispatched_as()方法做运行时校验同一服务可同时声明多种分发类型以跨模块复用。这正是「服务被 Builder、Automation、Dashboard 共享」这一架构的基石服务本体只关心“做什么”由分发类型决定它能挂到哪些产品面上。二、第一步先定位任务类型再找最近范例文档明确要求动手编辑前先判断当前任务属于以下哪一类仅新增集成类型integration type为既有集成新增服务类型service type将既有服务暴露到新产品面如自动化或 Builder更新既有集成、服务或包装类型横跨后端、前端、翻译与测试的完整功能随后用grep检查最近的相似实现再动手若rg可用它是更快的等价工具。官方推荐的起步检索路径均为仓库根目录相对路径后端注册backend/src/baserow/contrib/integrations/apps.py前端注册web-frontend/modules/integrations/plugin.js核心后端服务示例backend/src/baserow/contrib/integrations/core/service_types.py核心前端服务示例web-frontend/modules/integrations/core/serviceTypes.js后端集成示例backend/src/baserow/contrib/integrations/core/integration_types.py前端集成示例web-frontend/modules/integrations/core/integrationTypes.jsBuilder 工作流动作包装backend/src/baserow/contrib/builder/workflow_actions/workflow_action_types.py自动化节点包装backend/src/baserow/contrib/automation/nodes/node_types.py前端 Builder 工作流动作包装web-frontend/modules/builder/workflowActionTypes.js前端自动化节点包装web-frontend/modules/automation/nodeTypes.js三、后端检查清单Backend Checklist3.1 新增/更新服务类型时的检查项模型字段存在且支持预期配置ServiceType子类暴露正确的type、model_class、dispatch_types、allowed_fields及序列化器配置相关嵌套对象在after_create、更新辅助方法或自定义方法中处理若服务会向下游节点输出数据需实现上下文/模式schema方法序列化后的外键或 ID 在导入/导出期间正确迁移在backend/src/baserow/contrib/integrations/apps.py中完成注册模型有变更时补充迁移文件。3.2 新增/更新集成类型时的检查项IntegrationType子类定义type、model_class、序列化器字段名、allowed fields以及相关时的敏感字段sensitive fields保留集成特有的上下文数据或权限行为在apps.py中注册模型变更时补充迁移。3.3 真实源码示例一个核心服务类型backend/src/baserow/contrib/integrations/core/service_types.py 中的CoreHTTPRequestServiceType是 ACTION 分发的典型范例class CoreHTTPRequestServiceType(CoreServiceType): type http_request model_class CoreHTTPRequestService dispatch_types [DispatchTypes.ACTION] # 请求上的凭证可能位于任意位置无法猜测哪个是密钥 # 因此导出时保留 key、清空 value交由用户重新填写。 sensitive_fields [headers, query_params, form_data, body_content] allowed_fields [ http_method, url, body_type, body_content, timeout, ] _serializer_field_names [ http_method, url, headers, query_params, form_data, body_type, body_content, timeout, ]这里可以看到文档要求的核心属性如何落地type是持久化字符串标识http_requestmodel_class指向 Django 模型dispatch_types [DispatchTypes.ACTION]声明它只能被动作类产品面消费sensitive_fields决定导出时哪些字段需要脱敏key 保留、值清空。3.4 真实源码示例一个集成类型及其敏感字段保护backend/src/baserow/contrib/integrations/core/integration_types.py 中的SMTPIntegrationType展示了更精细的字段治理class SMTPIntegrationType(IntegrationType): type smtp model_class SMTPIntegration serializer_field_names [host, port, use_tls, username, password] allowed_fields [host, port, use_tls, username, password] sensitive_fields [host, port, use_tls, username, password] secret_fields [password] # 改变发送目标或降级为明文都会把存储的密码发送到其所有者从未同意的地方。 secret_field_dependencies {password: [host, port, use_tls]}secret_fields声明密码字段为写保护secret_field_dependencies声明密码与主机/端口/TLS 之间的依赖关系——修改发送目标或降级传输加密会触发对密码的保护策略这是「集成类型敏感行为保留」检查项的源码级印证。3.5 注册入口apps.py所有后端类型都汇聚到 backend/src/baserow/contrib/integrations/apps.py 的IntegrationsConfig.ready()中注册。集成类型注册进integration_type_registryintegration_type_registry.register(LocalBaserowIntegrationType()) integration_type_registry.register(SMTPIntegrationType()) integration_type_registry.register(AIIntegrationType()) integration_type_registry.register(SlackBotIntegrationType())服务类型注册进service_type_registry例如LocalBaserowGetRowUserServiceType、LocalBaserowListRowsUserServiceType、CoreHTTPRequestServiceType、CorePeriodicServiceType、AIAgentServiceType等二十余个服务类型。这个文件就是「后端注册检查项」的唯一事实来源——漏注册等于功能不存在。四、导入/导出的 ID 迁移Import/Export ID Migration当服务序列化包含外键或路径中的 ID 时必须在导入期间通过id_mapping迁移它们。官方文档给出了四种递进手段deserialize_property()用于简单字段如workflow_id、table_id、field_idcreate_instance_from_serialized()用于必须在服务创建后重建的嵌套行或列表import_serialized()当 ID 或 UUID 必须在常规反序列化前预留时使用数据提供方路径还需检查import_path()与import_context_path()公式字段通常通过import_formula回调单独迁移。常见的id_mapping键包括automation_workflows、automation_workflow_nodes、builder_*、database_tables、database_fields、integrations、services。文档给出的参照实现CoreStartWorkflowServiceType.deserialize_property()处理工作流 IDCoreRouterServiceType处理边edgeUIDlocal Baserow 服务类型处理表/字段 IDpremium 分组聚合服务处理嵌套字段引用。官方建议增加一个使用旧到新old-to-newid_mapping的导入回归测试。Builder 工作流动作包装层对 service 属性的反序列化有现成实现可参考。backend/src/baserow/contrib/builder/workflow_actions/workflow_action_types.py 中deserialize_property()在prop_name service时先通过id_mapping[integrations]重映射integration_id再借助 trash-inclusive 管理器Integration.objects_and_trash解析集成对象避免因集成已回收trashed导致导入崩溃并校验集成不得越出目标应用边界。这些细节是「导入导出健壮性」在生产级实现中的最佳实践。五、各产品面检查清单Product Surface Checklist5.1 Builder 或 Dashboard 数据源后端服务类型必须声明DispatchTypes.DATA确认dispatch()返回的形状符合get_schema()、get_data_schema()、get_result()或既有前端消费者的预期为数据源 UX 添加前端服务类型行为表单组件、校验、schema 辅助方法、结果辅助方法、错误消息在后端与前端集成注册表中注册服务若引入新字段或新输出形状检查数据源 create/update/dispatch 序列化器与测试。5.2 Builder 工作流动作后端服务类型声明DispatchTypes.ACTION在backend/src/baserow/contrib/builder/workflow_actions/models.py添加或复用工作流动作模型添加BuilderWorkflowServiceActionType子类声明type、model_class、service_type、get_pytest_params在backend/src/baserow/contrib/builder/apps.py注册在 web-frontend/modules/builder/workflowActionTypes.js 添加指向服务类型的前端工作流动作类型在web-frontend/modules/builder/plugin.js注册为动作标签、描述、校验与表单文案添加翻译。源码中的基类印证workflow_action_types.py 定义了BuilderWorkflowServiceActionType(ServiceBackedTypeMixin, BuilderWorkflowActionType)其service_type None要求子类必须实现且用PolymorphicServiceSerializer序列化service字段——这就是「包装层持有 service 引用」的实现机制。5.3 自动化动作节点后端服务类型声明DispatchTypes.ACTION在backend/src/baserow/contrib/automation/nodes/models.py添加或复用自动化节点模型添加AutomationNodeActionNodeType子类声明type、model_class、service_type、get_pytest_params在backend/src/baserow/contrib/automation/apps.py注册在 web-frontend/modules/automation/nodeTypes.js 用ActionNodeTypeMixin添加前端节点类型在web-frontend/modules/automation/plugin.js注册为节点标签、默认标签模板、描述、校验与表单文案添加翻译。5.4 自动化触发器节点使用或实现具备触发器能力的服务类型通常借助TriggerServiceTypeMixin添加或复用自动化触发器节点模型与后端节点类型通过既有触发器 mixin/模式实现is_workflow_trigger行为在backend/src/baserow/contrib/automation/apps.py注册后端节点类型添加使用TriggerNodeTypeMixin的前端节点类型在web-frontend/modules/automation/plugin.js注册确认样本数据、输出 schema、边edge行为与工作流模拟行为与既有触发器模式一致。六、前端检查清单Frontend Checklist若功能面向用户可配置前端需与后端并行更新添加或更新服务/集成类型类在 web-frontend/modules/integrations/plugin.js 中注册添加或更新用于配置它的表单组件在web-frontend/modules/integrations/locales/en.json添加翻译仅在既有模式需要时添加辅助 mixin、helper 或资源若暴露为 Builder 工作流动作或自动化节点在对应 builder/automation 模块中添加并注册前端包装类型。plugin.js是前端注册的事实中心。其注册代码与后端apps.py一一对应例如$registry.register(service, new CoreHTTPRequestServiceType(context))、$registry.register(service, new SlackWriteMessageServiceType(context))以及四个触发器服务类型LocalBaserowRowsCreatedTriggerServiceType等。前后端注册必须同步——这也是后面 Guardrails 中「不要只加后端类型而不检查对应前端注册路径」的由来。前端服务类型的类结构可参考 web-frontend/modules/integrations/core/serviceTypes.js 中的CoreHTTPRequestServiceType通过WorkflowActionServiceTypeMixin(ServiceType)获得动作能力static getType()返回与后端一致的http_request标识get icon/get group/get name/get description提供 UI 元数据名称与描述均走this.app.$i18n.t(...)对应翻译键getErrorMessage()实现 URL 缺失校验getDataSchema()透出服务 schema。这套「Mixin 组合 getType 对齐 i18n 文案」就是前端类型类的标准样板。常用前端文件web-frontend/modules/integrations/*/serviceTypes.jsweb-frontend/modules/integrations/*/integrationTypes.jsweb-frontend/modules/integrations/*/components/services/**web-frontend/modules/integrations/*/components/integrations/**web-frontend/modules/integrations/locales/en.json七、如何实现How To Implement7.1 创建新的服务类型从分发行为最接近的既有服务类型起步ACTION、DATA或触发器行为若服务需要持久化字段添加或更新后端模型实现或扩展后端ServiceType子类在backend/src/baserow/contrib/integrations/apps.py注册实现前端服务类型类与表单组件在web-frontend/modules/integrations/plugin.js注册仅为目标产品面添加包装补充翻译与测试。7.2 将既有服务暴露到另一产品面确认服务具备目标面所需的分发能力仅添加该面缺失的包装类型/模型/注册除非目标面确实需要不同的 UX否则复用既有服务表单与 schema 辅助方法保持服务type标识稳定包装type标识与邻近示例保持一致为包装的 create/update/dispatch 路径添加针对性测试。7.3 创建新的集成类型从认证或配置需求最接近的既有集成类型起步必要时添加或更新后端模型实现或扩展后端IntegrationType子类在apps.py注册实现前端集成类型类与表单组件在plugin.js注册补充翻译与测试。7.4 更新既有类型找到该类型字符串的全部前后端注册点检查 API 序列化器、嵌套关系或 schema 生成是否需要更新除非用户明确要求破坏性变更否则保持既有type标识稳定检查旧记录是否需要迁移或数据回填行为变化时同时更新 create 与 update 流程的测试。八、测试预期Testing Expectations文档要求先运行最窄范围的针对性测试若无现成测试则先创建。仓库中的真实测试布局如下后端测试集成与服务测试backend/tests/baserow/api/integrations/**如 backend/tests/baserow/api/integrations/test_integration_views.pyBuilder 数据源测试backend/tests/baserow/contrib/builder/data_sources/**及附近 API 数据源测试Builder 工作流动作测试backend/tests/baserow/contrib/builder/workflow_actions/**及附近 API 工作流动作测试自动化节点测试backend/tests/baserow/contrib/automation/nodes/**及附近 API 节点测试Dashboard 数据源测试服务暴露于 dashboard 时见backend/tests/baserow/contrib/dashboard/**前端测试集成单元测试web-frontend/test/unit/integrations/**Builder 工作流动作与数据源测试web-frontend/test/unit/builder/**自动化节点测试web-frontend/test/unit/automation/**收尾前的最低验证标准7 项类型在前端与后端均已注册如适用create 与 update 流程序列化了预期字段目标产品面可对该服务/包装执行 create、update、serialize、import/export 与 dispatch当下游公式/数据提供方依赖输出时输出 schema/样本数据可用必要翻译齐全模型变更伴随迁移文件最相关的针对性测试通过或明确报告失败原因。九、快速检索模式Search Patterns文档提供了可直接复制的高效检索命令便于在大型代码库中快速定位类型与注册点rg可用时是grep -RInE的更快等价物# 查找所有服务类型 / 集成类型 grep -RInE class .*ServiceType backend/src/baserow/contrib/integrations grep -RInE class .*IntegrationType backend/src/baserow/contrib/integrations # 按分发能力检索 grep -RInE DispatchTypes\.(ACTION|DATA) backend/src/baserow/contrib/integrations grep -RInE TriggerServiceTypeMixin|ListServiceTypeMixin backend/src/baserow/contrib/integrations # 注册点 grep -RInE register\( backend/src/baserow/contrib/integrations/apps.py web-frontend/modules/integrations/plugin.js # Builder / Automation 包装层 grep -RInE BuilderWorkflowServiceActionType|builder_workflow_action_type_registry backend/src/baserow/contrib/builder grep -RInE AutomationNodeActionNodeType|TriggerNodeType|automation_node_type_registry backend/src/baserow/contrib/automation grep -RInE WorkflowActionType|register\(workflowAction web-frontend/modules/builder grep -RInE ActionNodeTypeMixin|TriggerNodeTypeMixin|register\(node web-frontend/modules/automation # 前端类型标识与翻译键 grep -RInE getType\(\) web-frontend/modules/integrations grep -RInE serviceType\.|integrationType\. web-frontend/modules/integrations/locales/en.json这些命令对应的是全仓库搜索定位的最佳实践先按类名找到相近实现再沿注册链确认前后端一致性最后用翻译键补全文案。十、守卫规则Guardrails文档最后给出了七条不可逾越的红线它们实际上是本指南全部检查项的浓缩不要在未核对对应前端注册路径的情况下添加后端类型不要随意重命名已持久化的type字符串破坏既有数据的标识稳定性不要在模型字段变更时忘记迁移不要将无法以DispatchTypes.DATA分发的服务暴露为数据源不要将无法以DispatchTypes.ACTION分发的服务暴露为工作流动作或动作节点不要在纯数据源服务注册已足够时画蛇添足地添加自动化或 Builder 包装不要引入宽泛抽象除非至少两个既有实现已经需要它优先匹配最近的既有模块布局而不是自创新目录结构。结语Baserow 的集成与服务体系之所以能同时驱动 Application Builder、Dashboard 与 Automation核心在于「可复用服务本体 分发类型声明 各产品面薄包装」的三层设计。ServiceType用DispatchTypes声明能力边界IntegrationType用sensitive_fields/secret_fields守护凭证安全apps.py与plugin.js分别是前后端的注册中枢导入导出则依赖deserialize_property/import_serialized等钩子完成跨环境 ID 迁移。按本文的清单顺序——先定产品面、再抄最近范例、后端模型与类型、注册、前端表单、翻译、迁移与测试——即可在保持架构一致性的前提下稳妥地扩展出新的集成与服务能力。【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
