飞书多维表格 SDK

一个功能强大的飞书多维表格（Bitable）操作封装类，支持批量操作、文件上传、自动重试等功能。

功能特性

• 🔐 自定义应用凭证 - 支持传入自己的 appId 和 appSecret，提高安全性
• 📦 批量操作 - 支持大批量数据的增删改查，自动处理分片
• ⚡ 并发控制 - 可配置并发请求数，提高处理效率
• 🔄 自动重试 - API 请求失败时自动重试，提高稳定性
• 📁 文件上传 - 支持文件上传到飞书云文档
• 🔍 分页处理 - 自动处理分页，获取所有数据
• 🎯 类型安全 - 完整的 JSDoc 注释，提供良好的开发体验

安装

npm install ruindong-feishu-bitable

安全建议

⚠️ 重要: 为了安全起见，建议在生产环境中：

1. 使用自己的应用凭证而不是默认值
2. 通过环境变量或配置文件管理敏感信息
3. 不要将 appId 和 appSecret 硬编码在代码中
4. 定期轮换应用密钥

快速开始

使用自定义凭证

const Bitable = require('ruindong-feishu-bitable');

// 使用环境变量
const appId = process.env.FEISHU_APP_ID;
const appSecret = process.env.FEISHU_APP_SECRET;
const appToken = process.env.FEISHU_APP_TOKEN;

const bitable = new Bitable(appToken, appId, appSecret);

构造函数

new Bitable(defaultAppToken = null, appId = null, appSecret = null)

• defaultAppToken (可选): 默认的飞书多维表格 app_token
• appId (必填): 飞书应用的 appId，如果不提供则使用默认值
• appSecret (必填): 飞书应用的 appSecret，如果不提供则使用默认值

环境变量配置示例

创建 .env 文件（可选）：

# 飞书应用配置
FEISHU_APP_ID=your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here
FEISHU_APP_TOKEN=your_app_token_here

使用 dotenv 加载环境变量：

require('dotenv').config();
const Bitable = require('ruindong-feishu-bitable');

const bitable = new Bitable(
    process.env.FEISHU_APP_TOKEN,
    process.env.FEISHU_APP_ID,
    process.env.FEISHU_APP_SECRET
);

获取所有记录

const records = await bitable.fetchAllRecords(
    'table_id', 
    {
        viewId: 'view_id',
        fieldNames: ['field1', 'field2'],
        pageSize: 500
    },
    'app_token' // 可选，会覆盖构造函数中的默认值
);

批量新增记录

const records = [
    { field1: 'value1', field2: 'value2' },
    { field1: 'value3', field2: 'value4' }
];

const results = await bitable.insertList(
    'table_id',
    records,
    {
        appToken: 'app_token', // 可选
        concurrency: 2,        // 并发数，默认 1
        chunkSize: 500         // 每批记录数，默认 500
    }
);

批量更新记录

const records = [
    { record_id: 'id1', field1: 'new_value1' },
    { record_id: 'id2', field1: 'new_value2' }
];

const results = await bitable.updateList(
    'table_id',
    records,
    {
        appToken: 'app_token', // 可选
        concurrency: 2,        // 并发数，默认 1
        chunkSize: 500         // 每批记录数，默认 500
    }
);

批量删除记录

const recordIds = ['id1', 'id2', 'id3'];

const results = await bitable.deleteList(
    'table_id',
    recordIds,
    {
        appToken: 'app_token', // 可选
        concurrency: 2,        // 并发数，默认 1
        chunkSize: 500         // 每批记录数，默认 500
    }
);

上传文件

// 上传 base64 图片
const result = await bitable.uploadFile({
    file: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
    parentType: 'bitable_file',
    parent_node: 'parent_node_id',
    fileName: 'example.jpg', // 可选，未提供时自动生成
    extra: '{}' // 可选
});

// 上传 Buffer
const fs = require('fs');
const buffer = fs.readFileSync('./example.jpg');
const result = await bitable.uploadFile({
    file: buffer,
    parentType: 'bitable_file',
    parent_node: 'parent_node_id'
});

下载文件

const buffer = await bitable.downLoadFile('file_token', 'extra_param');

配置选项

并发控制

所有批量操作方法都支持并发控制：

{
    concurrency: 2,  // 并发请求数，默认 1
    chunkSize: 500   // 每批记录数，最大 500（飞书限制）
}

App Token 管理

可以在构造函数中设置默认 app_token，也可以在每次方法调用时传入：

// 方式1：构造函数设置
const bitable = new Bitable(appToken, appId, appSecret);

// 方式2：方法调用时传入
await bitable.insertList('table_id', records, { appToken: 'temp_token' });

错误处理

SDK 内置了自动重试机制，当 API 请求失败时会自动重试最多 5 次。如果所有重试都失败，会抛出最终的错误。

try {
    const results = await bitable.insertList('table_id', records);
    console.log('操作成功:', results);
} catch (error) {
    console.error('操作失败:', error.message);
}

更新日志

v1.0.0

• 初始版本发布
• 支持自定义应用凭证，提高安全性
• 支持批量增删改查
• 支持文件上传下载
• 内置自动重试机制
• 支持并发控制

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！