BitableSDK

项目简介

BitableSDK 是一个用于与飞书多维表格（Bitable）API 交互的 TypeScript SDK。它提供了简洁、类型安全的接口来对特定数据表执行增、删、改、查（CRUD）操作，作为业务后端与飞书服务之间的桥梁。

主要特性

• 🚀 配置驱动: 通过简单的配置对象即可初始化SDK
• 🔐 自动化认证: 自动处理 tenant_access_token 的获取和刷新
• 📝 类型安全: 完整的 TypeScript 类型定义
• 🛡️ 错误处理: 健壮的错误处理机制
• 📚 完整文档: 详细的 JSDoc 注释和使用示例
• 🧪 测试覆盖: 完整的单元测试和集成测试

技术栈

• 语言: TypeScript
• 运行环境: Node.js (>= 16.0.0)
• 模块系统: ES Modules (ESM)
• 主要依赖: axios (HTTP 请求)
• 测试框架: Jest
• 构建工具: TypeScript Compiler

快速开始

环境配置

1. 复制环境变量模板

cp env.example .env

2. 配置环境变量 编辑 .env 文件，填入真实的配置信息：

# 飞书应用的 App ID
FEISHU_APP_ID=your_app_id_here

# 飞书应用的 App Secret  
FEISHU_APP_SECRET=your_app_secret_here

# 多维表格的 ID (baseId)
FEISHU_BASE_ID=your_base_id_here

# 数据表的 ID
FEISHU_TABLE_ID=your_table_id_here

3. 获取配置信息

• App ID & App Secret: 在飞书开放平台创建应用后获得
• Base ID: 在飞书多维表格的URL中获取
• Table ID: 在飞书多维表格的数据表设置中获取

⚠️ 重要安全提醒

请务必注意以下安全事项：

1. 永远不要将真实的敏感信息提交到代码仓库

   • .env 文件已被添加到 .gitignore 中，不会被提交
   • 所有测试文件现在都从环境变量获取配置，不再包含硬编码的敏感信息

2. 环境变量配置

   • 所有测试和示例代码都使用环境变量获取配置
   • 如果环境变量未设置，程序会抛出明确的错误信息
   • 不要在任何代码文件中硬编码 API 密钥、App Secret 等敏感信息

3. 测试环境

   • 运行测试前请确保已正确配置 .env 文件
   • 测试会使用真实的飞书API，请确保应用权限配置正确

4. 生产环境

   • 在生产环境中使用环境变量或安全的配置管理系统
   • 定期轮换 API 密钥和 App Secret

安装

npm install bitable-sdk

模块系统说明

本SDK使用 ES模块系统 (ESM)，支持以下使用方式：

ES模块项目（推荐）

import { BitableSDK } from 'bitable-sdk';

CommonJS项目

const { BitableSDK } = await import('bitable-sdk');

确保你的项目支持ES模块

• Node.js: 确保 package.json 中有 "type": "module"
• TypeScript: 确保 tsconfig.json 中 "module" 设置为 "ES2020" 或更高版本

基本使用

import { BitableSDK } from 'bitable-sdk';

// 创建SDK实例
const sdk = new BitableSDK({
  appId: 'YOUR_APP_ID',
  appSecret: 'YOUR_APP_SECRET',
  baseId: 'YOUR_BASE_ID',
  tableId: 'YOUR_TABLE_ID',
});

// 创建记录
const record = await sdk.addRecord('你好，世界！', 'user_001');

// 查询记录
const records = await sdk.listRecords('user_001');

// 更新记录
const updated = await sdk.updateRecord(record.id, 'Hello, World!');

// 删除记录
const result = await sdk.deleteRecord(record.id);

注意: 本SDK使用ES模块系统，确保你的项目支持ES模块。如果使用CommonJS，请使用动态导入：

const { BitableSDK } = await import('bitable-sdk');

API 文档

配置接口

interface BitableSDKConfig {
  appId: string;        // 飞书应用的 App ID
  appSecret: string;    // 飞书应用的 App Secret
  baseId: string;       // 多维表格的 ID
  tableId: string;      // 数据表的 ID
}

记录数据模型

interface PromptRecord {
  id: string;           // 飞书记录 record_id
  提示词: string;       // 提示词内容
  作者: string;         // 创建该记录的用户ID
  日期: number;         // Unix时间戳（秒）
}

主要方法

listRecords(authorId: string): Promise<PromptRecord[]>

根据作者ID查询其创建的所有记录。

const records = await sdk.listRecords('user_001');
console.log(`查询到 ${records.length} 条记录`);

addRecord(prompt: string, authorId: string): Promise<PromptRecord>

创建一条新的提示词记录。

const record = await sdk.addRecord('你好，世界！', 'user_001');
console.log('创建成功:', record);

updateRecord(recordId: string, newPrompt: string): Promise<PromptRecord>

根据记录ID更新指定的提示词内容。

const updated = await sdk.updateRecord('rec123', 'Hello, New World!');
console.log('更新成功:', updated);

deleteRecord(recordId: string): Promise<{ deleted: boolean }>

根据记录ID删除一条记录。

const result = await sdk.deleteRecord('rec123');
console.log('删除成功:', result.deleted);

调试方法

getConfig(): BitableSDKConfig

获取当前SDK配置信息。

getAuthInfo(): { token: string; expireTime: number } | null

获取当前认证token信息。

clearAuthCache(): void

清除认证缓存，强制下次请求时重新获取token。

错误处理

SDK 提供了完善的错误处理机制：

try {
  const records = await sdk.listRecords('user_001');
} catch (error) {
  if (error instanceof AuthError) {
    console.error('认证错误:', error.message);
  } else if (error instanceof APIError) {
    console.error('API错误:', error.message, error.code);
  } else {
    console.error('其他错误:', error.message);
  }
}

错误类型

• BitableSDKError: 基础错误类
• AuthError: 认证相关错误
• APIError: API调用相关错误

开发环境设置

前置要求

• Node.js (推荐 v16 或更高版本)
• npm 或 yarn 包管理器

安装依赖

npm install

开发命令

# 启动开发服务器（监听文件变化）
npm run dev

# 构建项目
npm run build

# 运行测试
npm run test

# 代码检查
npm run lint

# 运行特定测试文件
node tests/test-add-record.ts
node tests/test-delete-record.ts
node tests/test-real-api.ts
node tests/debug-api-response.ts

# 清理构建文件
npm run clean

项目结构

BitableSDK/
├── src/                    # 源代码目录
│   ├── types/             # 类型定义
│   │   └── index.ts       # 主要类型定义
│   ├── auth.ts            # 认证管理模块
│   ├── api.ts             # API请求封装
│   ├── BitableSDK.ts      # 主SDK类
│   └── index.ts           # 主入口文件
├── examples/              # 使用示例
│   ├── demo.ts            # 演示程序
│   └── simple-demo.ts     # 简单示例
├── tests/                 # 测试文件
│   ├── setup.ts           # 测试设置
│   ├── BitableSDK.test.ts # 单元测试
│   ├── crud-integration.test.ts # CRUD集成测试
│   ├── error-handling.test.ts # 错误处理测试
│   ├── performance.test.ts # 性能测试
│   ├── concurrent.test.ts # 并发测试
│   ├── run-all-tests.ts   # 测试运行脚本
│   ├── test-add-record.ts # 添加记录测试（旧版）
│   ├── test-delete-record.ts # 删除记录测试（旧版）
│   ├── test-real-api.ts   # 真实API测试（旧版）
│   └── debug-api-response.ts # API响应调试（旧版）
├── doc/                   # 文档目录
│   └── prd.md             # 产品需求文档
├── dist/                  # 构建输出目录
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript配置
├── jest.config.js         # Jest测试配置
├── eslint.config.js       # ESLint代码规范配置
└── README.md              # 项目说明文档

数据表结构

SDK 操作的目标飞书多维表格包含以下字段：

| 字段名 | 字段类型 | 描述 | | :------- | :----------- | :--------------------------------- | | id | (记录ID) | 飞书系统自动生成的唯一记录 ID | | 提示词 | 文本 (Text) | 用户创建的 Prompt 内容 | | 作者 | 文本 (Text) | 创建该记录的用户的唯一标识符 (userId) | | 日期 | 数字 (Number) | 记录创建或更新的 Unix 时间戳（秒） |

使用示例

完整的使用示例请参考 examples/demo.ts 文件：

import { BitableSDK } from 'bitable-sdk';

async function runDemo() {
  const sdk = new BitableSDK({
    appId: 'YOUR_APP_ID',
    appSecret: 'YOUR_APP_SECRET',
    baseId: 'YOUR_BASE_ID',
    tableId: 'YOUR_TABLE_ID',
  });

  const testUserId = 'user_test_001';
  let newRecordId = '';

  try {
    // 新增记录
    const created = await sdk.addRecord('你好，世界！', testUserId);
    newRecordId = created.id;

    // 查询记录
    const records = await sdk.listRecords(testUserId);
    console.log(`查询到 ${records.length} 条记录`);

    // 更新记录
    const updated = await sdk.updateRecord(newRecordId, 'Hello, New World!');

    // 删除记录
    const result = await sdk.deleteRecord(newRecordId);

  } catch (error) {
    console.error('操作失败:', error);
  }
}

测试

运行测试

# 运行所有测试
npm test

# 运行完整测试套件（包含所有测试类型）
npm run test:all

# 运行特定类型的测试
npm run test:crud      # CRUD集成测试
npm run test:error     # 错误处理测试
npm run test:performance # 性能测试
npm run test:concurrent  # 并发测试
npm run test:unit      # 单元测试

# 运行测试并生成覆盖率报告
npm run test:coverage

# 监听模式运行测试
npm run test -- --watch

测试覆盖

测试类型

1. 单元测试 (tests/BitableSDK.test.ts)

   • SDK核心功能测试
   • 参数验证测试
   • 配置验证测试

2. CRUD集成测试 (tests/crud-integration.test.ts)

   • 完整的增删改查操作测试
   • 数据一致性测试
   • 边界值测试
   • 特殊字符和Unicode测试

3. 错误处理测试 (tests/error-handling.test.ts)

   • 参数验证错误测试
   • 网络错误和超时测试
   • 并发错误处理测试
   • 错误恢复测试

4. 性能测试 (tests/performance.test.ts)

   • 单次操作性能测试
   • 批量操作性能测试
   • 并发性能测试
   • 内存使用测试
   • 响应时间测试
   • 压力测试

5. 并发测试 (tests/concurrent.test.ts)

   • 基础并发测试
   • 高并发压力测试
   • 混合并发操作测试
   • 并发限制测试
   • 长时间并发测试
   • 并发性能基准测试

测试特性

• 自动化清理：所有测试都会自动清理测试数据
• 环境变量支持：支持通过 .env 文件配置测试环境
• 详细日志：提供详细的测试执行日志和性能指标
• 错误处理：完善的错误处理和恢复机制
• 性能监控：实时监控测试性能和响应时间

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

开发规范

• 使用 TypeScript 编写代码
• 添加完整的 JSDoc 注释
• 编写对应的单元测试
• 遵循项目的代码风格

许可证

MIT License

更新日志

v1.1.0 (2024-01-XX)

• 🧪 新增完整的测试套件
  • CRUD集成测试：完整的增删改查操作测试
  • 错误处理测试：各种异常场景和边界情况测试
  • 性能测试：单次、批量、并发操作性能测试
  • 并发测试：高并发场景下的稳定性测试
• 🔧 新增测试工具和配置
  • 统一的测试配置管理
  • 自动化数据清理工具
  • 性能测量工具
  • 测试运行脚本
• 📚 完善测试文档和使用说明

v1.0.0 (2024-01-XX)

• 🎉 初始版本发布
• ✨ 实现完整的CRUD操作
• 🔐 自动化认证管理
• 📝 完整的TypeScript类型定义
• 🧪 基础单元测试
• 📚 详细的使用文档和示例

技术支持

如果您在使用过程中遇到问题，请：

1. 查看 文档
2. 运行 示例程序
3. 检查 测试用例
4. 提交 Issue

相关链接

• 飞书开放平台文档
• 飞书多维表格API文档
• TypeScript 官方文档
• Jest 测试框架