高级功能

本文档介绍飞书插件的高级功能和深度集成方法。

高级字段类型

关联字段

关联字段可以连接不同数据表，实现数据关联。

单向关联（type: 27）

{
  "field_name": "关联客户",
  "type": 27,
  "property": {
    "table_id": "tbl_customer",
    "limit_single": false
  }
}

插入关联记录：

{
  "action": "create",
  "app_token": "S404bxxxxx",
  "table_id": "tbl_order",
  "fields": {
    "订单号": "ORD-2026-001",
    "关联客户": ["rec_customer_xxx", "rec_customer_yyy"]
  }
}

双向关联（type: 28）

双向关联会自动在关联表中创建反向关联。

公式字段（type: 18）

公式字段是只读字段，由系统自动计算。

{
  "field_name": "总价",
  "type": 18,
  "property": {
    "expression": "{单价} * {数量}"
  }
}

支持的运算符：

• +, -, *, /
• (), 优先级控制
• 函数：SUM(), AVERAGE(), COUNT(), IF()

高级筛选

组合条件

{
  "filter": {
    "conjunction": "and",
    "conditions": [
      {"field_name": "状态", "operator": "is", "value": ["进行中"]},
      {"field_name": "金额", "operator": "isGreater", "value": ["10000"]},
      {"field_name": "创建时间", "operator": "isAfter", "value": ["2026-01-01"]}
    ]
  }
}

或条件

{
  "filter": {
    "conjunction": "or",
    "conditions": [
      {"field_name": "状态", "operator": "is", "value": ["已完成"]},
      {"field_name": "负责人", "operator": "is", "value": ["张三"]}
    ]
  }
}

嵌套条件

{
  "filter": {
    "conjunction": "and",
    "conditions": [
      {"field_name": "状态", "operator": "is", "value": ["进行中"]},
      {
        "conjunction": "or",
        "conditions": [
          {"field_name": "优先级", "operator": "is", "value": ["高"]},
          {"field_name": "截止日期", "operator": "isLess", "value": ["2026-03-31"]}
        ]
      }
    ]
  }
}

数据统计

聚合函数

在记录列表中使用聚合：

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "filter": {...},
  "aggregation": {
    "field_name": "金额",
    "type": "sum"  // sum, avg, count, min, max
  }
}

分组统计

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "group_by": {
    "field_name": "部门",
    "aggregation": {
      "field_name": "人数",
      "type": "count"
    }
  }
}

Webhook 集成

配置 Webhook

在多维表格中配置 Webhook，触发外部自动化：

1. 打开多维表格
2. 右上角设置 → 高级 → Webhook
3. 添加 Webhook URL

接收 Webhook

// 示例：使用 Express 接收 Webhook
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/feishu', (req, res) => {
  const { type, table_id, record_id, action } = req.body;
  
  if (action === 'create') {
    console.log('新记录创建:', record_id);
    // 处理新记录
  } else if (action === 'update') {
    console.log('记录更新:', record_id);
    // 处理更新
  }
  
  res.send('OK');
});

自动化工作流

场景：自动创建任务

async function handleNewRecord(record) {
  // 当新客户创建时，自动创建跟进任务
  await feishu_task_task.create({
    summary: `跟进客户: ${record.fields['客户名称']}`,
    description: `客户电话: ${record.fields['电话']}`,
    due: {
      timestamp: Date.now() + 7 * 24 * 60 * 60 * 1000 // 7天后
    },
    current_user_id: record.fields['跟进人'][0].id,
    members: [
      { id: record.fields['跟进人'][0].id, role: 'assignee' }
    ]
  });
}

场景：自动发送提醒

async function sendReminder() {
  // 查询今天到期的任务
  const today = new Date();
  today.setHours(23, 59, 59, 999);
  
  const tasks = await feishu_task_task.list({
    due_start: Date.now(),
    due_end: today.getTime()
  });
  
  for (const task of tasks.items) {
    await feishu_im_user_message.send({
      receive_id: task.members[0].id,
      msg_type: 'text',
      content: JSON.stringify({
        text: `⏰ 任务提醒：${task.summary} 今天到期！`
      })
    });
  }
}

性能优化

1. 批量操作

// 错误：循环单条创建
for (const item of items) {
  await createRecord(item);  // 慢！
}

// 正确：批量创建
await batchCreateRecords(items);  // 快！

2. 并发控制

// 控制并发数
const concurrency = 5;
const chunks = chunkArray(items, concurrency);

for (const chunk of chunks) {
  await Promise.all(chunk.map(item => processItem(item)));
}

3. 缓存策略

// 缓存字段结构，避免重复查询
const fieldCache = new Map();

async function getFields(appToken, tableId) {
  const key = `${appToken}:${tableId}`;
  
  if (fieldCache.has(key)) {
    return fieldCache.get(key);
  }
  
  const fields = await feishu_bitable_app_table_field.list({
    app_token: appToken,
    table_id: tableId
  });
  
  fieldCache.set(key, fields);
  return fields;
}

4. 选择性读取

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "field_names": ["客户名称", "状态", "跟进人"],
  "page_size": 50
}

高级模式

数据验证

function validateRecord(fields, fieldDefs) {
  const errors = [];
  
  for (const [name, value] of Object.entries(fields)) {
    const field = fieldDefs.find(f => f.field_name === name);
    
    if (!field) {
      errors.push(`未知字段: ${name}`);
      continue;
    }
    
    switch (field.type) {
      case 2: // 数字
        if (typeof value !== 'number') {
          errors.push(`${name} 必须是数字`);
        }
        break;
      case 11: // 人员
        if (!Array.isArray(value) || !value[0]?.id) {
          errors.push(`${name} 格式错误`);
        }
        break;
    }
  }
  
  return errors;
}

事务处理

飞书 API 不支持事务，但可以通过以下方式实现：

async function atomicOperation(records) {
  const created = [];
  
  try {
    for (const record of records) {
      const result = await createRecord(record);
      created.push(result);
    }
  } catch (error) {
    // 回滚：删除已创建的记录
    for (const record of created) {
      await deleteRecord(record.record_id);
    }
    throw error;
  }
}