跳到主要内容

Connector

Connector 是把 Flow 与外部 provider 集成起来的独立 Dex primitive。它封装 typed operation、event ingress、authorization 和可选的 configuration UI，同时避免把 provider credential 写入持久化 Flow state。

官方 Connector 与 Dex 分别发布。当前 Connector SDK 和官方 provider module 支持 Go 应用。

Capabilities​

一个 Connector 可以提供五种 capability：

  • Auth 为 logical connection 授权，并把 credential 留在 Flow 之外。
  • Trigger 把 provider event 转换成 typed event，用于启动 Flow 或调用 typed RPC。
  • Query 通过 Connector Step 读取 provider state。
  • Mutation 修改 provider state，并显式处理 idempotency 和 uncertain outcome。
  • UI 提供可复用的 configuration unit，由 Dex Web 为 Step 或 Trigger binding 组合显示。

Provider module 只需要提供自身所需的 capability。应用使用对应 module release 生成的类型。

Operation 是 Connector Step​

Operation-specific factory 会创建 Connector Step。应用把当前 Step input 映射为 provider input，并把每个 required result branch 连接到另一个 Step。Provider call 在 Execute 中运行，并使用 Dex 的 retry、timeout、durability 和 recovery 语义。

Connector result 包含当前 operation output、receipt、选中的 branch，以及存在时的 安全 failure classification。它不会转发上一个 Step input。调用 Connector 前，应把 业务上下文持久化到应用 Attribute，或通过应用 Step 显式传递。

Query 读取 provider state。Mutation 修改 provider state，并使用从 Step execution 派生的稳定 idempotency key。如果已发出的 Mutation 无法确认结果，Connector 会选择 uncertainty branch，使 Flow 先查询并 reconcile，而不是盲目重发。

默认只要求连接 happy-path branch。Optional branch 可以不连接；当 operation 选中 未连接的 optional branch 时，Flow 会失败，并把 provider outcome 暴露给 recovery。

Trigger 启动或更新 Flow​

Connector Trigger 是运行在 Flow 之外的长时间 event source。它保留 provider event ID 和发生时间，然后以 at-least-once 方式把 event 交给应用定义的 target。

应用提供最终 filter、解析 Flow ID，并把 provider event 映射为 typed input。应用决定 event 是启动 Flow，还是调用已有 Flow 的 typed RPC。Root start 使用 provider event ID 作为 request identity。RPC target 所需的重复投递处理保存在有界的应用 state 中。

本地 Trigger runner 会在向 provider acknowledgement 前持久化匹配的 event，并在 process restart 后重放未完成的 delivery。

Connection 与 configuration​

Flow definition 引用 logical connection name，而不是 credential。本地开发时，Dex Web 会读取这些静态引用，并显示在 Connections 中。只有验证了精确的官方 module release 后，它才会写入 connection、operation 或 Trigger-binding configuration。

Connector Studio UI 运行在 opaque-origin sandbox 中。Provider command 由 Connector release 声明，并由 Dex Web host 执行。已保存的 credential 不会进入 iframe、Flow input、Attribute、result、receipt、Stream、日志或生成 artifact。

Dex Web 与本地 credential storage 的使用方式见 本地 Connector 配置。

使用或贡献 Connector​

编写 provider integration 前，先查看 已发布 Connector catalog。 Dex Connectors Library 包含 manifest、生成 API、provider implementation、UI unit 和可运行示例。

应用使用已发布 Connector 时，使用 Dex SDK skill。新增或修改官方 Connector、 operation、Trigger 或 UI unit 时，使用 Dex Connector Contributor skill。