DataOps-platform/docs/development/CONNECTOR_SDK_GUIDE.md

Connector SDK v1 开发指南

最小接入

从 app.core.connectors 导入 Connector、ConnectorManifest、OperationRequest、 OperationResult 和 ConnectorRegistry。连接器声明唯一 connector_id、语义版本、固定 sdk_version=1.0、能力清单与 additionalProperties: false 的配置 Schema，实现八个统一方法， 然后调用 registry.register(connector)。不要修改 runtime 或采集 dispatcher。

配置由 JSON Schema Draft 2020-12 递归校验，包括嵌套对象、数组、上下界、组合规则和未知字段。 非 dry-run 机器运行不得出现调用方 config 字段，即使值为 {} 也拒绝。Oracle、SQL Server、REST 均须先由管理员创建版本化 source binding，再将 principal 绑定到同一 connector/version/source/ domain/environment；runtime 只使用服务端批准的完整配置，包括非 REST 的 credential reference。 配置只能保存连接信息与秘密引用。秘密字段必须命名为 *_ref，值使用 env:、vault: 或 secret: 引用；不得把 password、token、API key、Authorization 或私钥放入配置、manifest、 异常、日志或 evidence。

契约规则

1. 所有外部读取必须有超时、响应/记录上界与明确 scope；SQL 必须只读且参数化。
2. OperationResult 返回不可变 records、cursor、checkpoint 和安全 evidence。增量和恢复必须 使用已持久化的 cursor/checkpoint。大型 snapshot checkpoint 应保存有界 hash/count 摘要；若没有 足够信息精确重建 added/removed/changed，就明确 details_materialized=false，不得伪造明细。evidence 超过 32 KiB 时拒绝；records、cursor 和 checkpoint 也分别受 10,000 条/1 MiB、32 KiB、256 KiB 上界。所有通道在持久化前递归脱敏，列表只暴露 checkpoint/cursor 摘要。
3. 未声明能力、未知版本、非法配置、重复运行和不允许状态迁移必须失败关闭。
4. 上游异常映射到 configuration/authentication/permission/rate_limit/timeout/upstream/ contract/cancelled 稳定类别，响应不携带驱动原始错误。
5. capability 必须与实际行为一致；未实现的方法不得写入 manifest。使用通用兼容套件验证已声明 方法、幂等、重试、取消、恢复、脱敏和注册零核心修改。
6. 普通 connector operation 的 OperationResult.status 只能是 succeeded；不得返回 running、failed 或 cancelled 让 runtime 写入悬挂状态。dry-run 状态由 runtime 产生。

受控 REST Catalog 是参考实现。生产 transport 必须使用首次验证的公共 IP 建立连接，同时保留 原始 host 用于 TLS SNI、证书 hostname 与 Host 校验；不得跟随重定向，也不得在 DNS 重解析后 更换目标。响应必须流式限长；秘密解析器只能将解析值送入 Authorization，不得写入配置或证据。 默认环境解析器仅接受 env:DATAOPS_CONNECTOR_*；vault: 和 secret: 必须在部署方显式注入 后端解析器，否则稳定失败关闭。

人工管理接口仅用于显式 dry-run；execute/resume 均不得调用真实 operation、secret resolver 或 I/O。 真实非 dry-run 采集必须使用 connector principal 的一次性 短期凭证，并同时匹配 connector/version/source/business-domain/environment、操作及资源 scope。 execute 与 resume 共用单个运行的五次总 attempt 上限；resume 失败必须落回 failed 并保留原 checkpoint，不能停留在 resumable。持久化适配器的状态更新必须返回显式 CAS ownership 结果； 每次 attempt 使用不可复用 lease token，只有 exact attempt + lease 的 acquired=true 调用方可提交 终态。竞争失败方必须返回冲突或 already-running， 不得把“读取到当前行”解释成已获得运行权，也不得追加重复 attempt。

取消是协作式协议：先持久化运行取消标志，再由连接器在 I/O 边界探测；最长响应时间受数据库驱动 query timeout 与 REST read timeout 限制。不要用 connector 实例的 source 级内存标志，否则会把 同一来源的其他运行误取消。REST 分页还必须拒绝重复/倒退 cursor，并设置页数和总记录数上界。

SQL Server 连接默认启用加密并验证服务器证书。可信 environment 必须从已认证 source binding 传给 连接管理器，禁止在 tls_options 中自报 development。staging/production 不允许 TrustServerCertificate=yes 或 Encrypt=no；development 例外必须显式声明，仅用于本地验证并留警告。