# @useairfoil/connector-kit 中文文档

规范地址：https://npmcn.com/package/%40useairfoil/connector-kit/

版本：0\.7\.0
npm 元数据更新时间：2026-11-02T18:47:22.134Z
中文译文更新时间：2026-11-02T19:46:04.846Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40useairfoil/connector-kit
原文对照：https://npmcn.com/package/%40useairfoil/connector-kit/?lang=original
项目主页：https://github.com/useairfoil/connector-kit#readme
源码仓库：https://github.com/useairfoil/connector-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：614 kB，146 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：effect ^4\.1\.0
- 首次发布：2026-03-10T08:53:25.211Z
- 最新版本发布：2026-11-02T18:47:21.788Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

使用这个包来建立一个翼型生产者连接器。

## 安装

```sh
npm install @useairfoil/connector-kit
```

也可以使用：`pnpm add @useairfoil/connector-kit`、`yarn add @useairfoil/connector-kit`、`bun add @useairfoil/connector-kit`

## README

# 连接器套件

使用这个包来建立一个翼型生产者连接器。

## 安装

```bash
pnpm add @useairfoil/connector-kit effect@^4
```

## 使用

-   `Connector`， `Resource`， `Fetch`, `Cursor` 定义数据流。
-   `Manifest` 定义用户配置。
-   `ConnectorApp` 检查配置并运行HTTP服务器。
-   `Webhook` 定义webhook路由。
-   `Ingestor` 将批处理写入控制台或冰山。
-   `StateStore` 保持摄入进度。

这里有一个小资源：

```ts
import { Connector, Cursor, Fetch, Iceberg, Resource } from "@useairfoil/connector-kit";
import { Effect, Schema } from "effect";

const PostSchema = Schema.Struct({
  id: Schema.String.pipe(Iceberg.field(1)),
  updatedAt: Schema.String.pipe(Iceberg.field(2)),
}).pipe(Iceberg.identifier("id"));

const Posts = Resource.entity({
  name: "posts",
  rowSchema: PostSchema,
  version: "updatedAt",

  check: Effect.void,
  backfill: Fetch.page({
    pageCursor: Cursor.number(),
    cutoff: Cursor.isoDateTime(),
    fetch: () =>
      Effect.succeed({
        rows: [],
        nextPageCursor: 1,
        hasMore: false,
      }),
  }),
});

const connector = Connector.define({
  name: "producer-example",
  resources: [Posts],
});
```

当一个提供程序日志覆盖多个资源（如事件API）时，给出 连接器是单一的。 `changes` 饲料代替 `changes` 在每个资源上。这个 Feed每运行一次读取日志，并根据资源名称返回行：

```ts
const connector = Connector.define({
  name: "producer-example",
  resources: [Posts, Comments],
  changes: Fetch.feed({
    resources: [Posts, Comments],
    cursor: Cursor.string(),
    interval: "5 minutes",
    fetch: ({ cursor }) =>
      readEvents(cursor).pipe(
        Effect.map((page) => ({
          rows: { posts: page.posts, comments: page.comments },
          cursor: page.next,
          // Runs again without waiting for the interval.
          hasMore: page.hasMore,
        })),
      ),
  }),
});
```

资源本身 `changes` 可以返回 `hasMore` 同样的方式，要劈一个长 跨运行读取。

提要中的每个资源都存储提要光标，因此状态显示它 资源。提要中的资源也不能定义自己的资源 `changes`.

机翼型存储引擎支持对冰山行向上操作。使用 `Iceberg.identifier` 注释标识符行（主键）的帮助器。这 注释必须总是在最后使用。

反转操作替换完整的行内容，因此更改提要 必须包括所有字段。如果webhook事件不包括所有字段，则 实现必须在将资源推送到引擎之前获取资源。

翼型存储引擎实现软删除。如果需要删除一行，只需推送即可 键，版本列（如果有的话）， `_deleted = true` 以及任何其他必需的列。 如果目标服务支持恢复记录，则连接器必须发送 `_deleted = false` 每一行。

### 运行

在本地测试时，您可以在内存中运行连接器：

-   `StateStore.layerMemory`：在内存中存储连接器的状态。
-   `Ingestor.layerConsole`：向控制台输出新批。

为了持久的跑步：

-   `RuntimeConfig.layerHosted()`：从文件中加载配置。
-   `StateStore.layerSql()`：在PostgreSQL中存储连接器的状态。
-   `Ingestor.layerArrowFlightConfig(connector)`：向Apache Iceberg发布数据 使用翼型存储引擎和箭飞行。

内置HTTP服务器具有 `/health`， `/status`, `/metrics` 端点。

## 配置

| 变量 | 要求 | 默认的 |
| --- | --- | --- |
| `AIRFOIL_CONFIG_PATH` | 是 | 无 |
| `ENGINE_URI` | 是 | 无 |
| `AIRFOIL_CATALOG` | 是 | 无 |
| `AIRFOIL_TABLE_BINDINGS` | 是 | 无 |
| `AIRFOIL_CONNECTOR_INSTANCE_ID` | 是 | 无 |
| `POSTGRES_CONNECTION_STRING` | 是 | 无 |
| `AIRFOIL_HTTP_PORT` | 否 | `8080` |
| `AIRFOIL_STATE_TABLE` | 否 | `_airfoil_connectors_state` |

这个 `AIRFOIL_TABLE_BINDINGS` 环境变量控制使用哪些资源 与目标表同步。必须至少定义一个资源。

```env
AIRFOIL_TABLE_BINDINGS={"posts":{"namespace":["default"],"name":"posts"}}
```

在表名中只使用小写字母、数字和下划线。S3表 目录拒绝其他字符，例如 `-`.

## 演示数据

带有演示的连接器具有 `demo` 命令。它将虚构的行写入 绑定表，然后退出。它不需要提供者凭证，也不需要 PostgreSQL的状态。

```bash
producer-stripe demo --size 128MiB --seed 42
```

-   `--size` 要写入的未压缩箭头大小，如 `512KiB`， `128MiB`， 或者 `1GiB`。运行可以通过一个组块进行，大约为1 MiB 当前的连接器。
-   `--seed` 选择数据。日期取决于跑步开始的时间，所以是两次 只有当它们同时启动并绑定时，才与相同的种子匹配 相同的表。
-   编写一次的设置表（如产品目录）不会增长。如果只有 这些是绑定的，运行写入它们一次，并在小于大小时停止。演示 对于有限的历史记录，例如每日报告，当它们用完时也要停止。
-   它需要 `AIRFOIL_CONFIG_PATH`， `ENGINE_URI`， `AIRFOIL_CATALOG`, `AIRFOIL_TABLE_BINDINGS`。一个空 `{}` 配置文件就足够了。

一个演示列出了它的 `setup` 和 `group` 表，并使用 `Demo.define`。从组索引构建键，因此它们是唯一的和其他的 行可以指向它们。一行省略的必填字段获取占位符值 从行模式中。每一行都要根据它的行模式进行检查 写的。

## 常见问题

### @useairfoil/connector-kit 是什么？

使用这个包来建立一个翼型生产者连接器。

### 如何安装 @useairfoil/connector-kit？

在项目目录运行 npm install @useairfoil/connector-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（^4\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @useairfoil/connector-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @useairfoil/connector-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @useairfoil/connector-kit 可以商用吗？

@useairfoil/connector-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @useairfoil/connector-kit 还在维护吗？

最新版本 0\.7\.0 发布于 2026/11/03（今天）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/03/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。