5.3 合作伙伴与集成

5.3 合作伙伴与集成

直接定义：集成（integration）指 Supabase 和外部服务之间预先做好的对接，让你不用自己写胶水就能把数据或事件流过去。比如把数据库变更发到消息队列、把认证事件同步到数据分析工具、把文件处理交给专用服务。这一节我们讲常见的集成类别、怎么用，以及何时该自己写而不是用现成集成。

场景：关键事件不能丢怎么办

1. 事件对外推送：数据库变更通过 Realtime 或 webhook 流出，喂给下游（队列、数据仓库、搜索）。
2. 认证源对接：在 Auth 里开启第三方登录（GitHub、Google 等），配置走 Dashboard 的 Providers。
3. 逻辑复制对接：把表变更通过 Postgres 逻辑复制同步到外部分析库。
4. 函数代理外部 API：Edge Function 作为中转，调用第三方并隐藏密钥。

下面 SVG 把"Supabase 为中心的集成星型"画出来，看清它在系统里的位置：

认证源集成：第三方登录

开启 GitHub 登录只需在 Dashboard 填 OAuth 凭据，前端调用 signInWithOAuth({ provider: 'github' }) 即可，不用自己实现 OAuth 回调。

await supabase.auth.signInWithOAuth({ provider: 'github' })
// 回调后用户入库，触发器自动建 profiles（见 3.3）
​

代价：依赖第三方可用性，且用户数据分布在第三方。若某登录源宕机，对应登录不可用——要有兜底（邮箱密码）别把登录源锁死。

事件流出：变更进队列/仓库

把订单创建事件流出做异步处理（发货、通知），可用数据库函数 + Edge Function 桥接，或逻辑复制直送外部。下面用函数写一行到"出站事件"表，由外部 worker 消费：

create table public.outbox (
  id bigint generated always as identity primary key,
  topic text,
  payload jsonb,
  sent boolean default false
);

create or replace function public.emit_order_event()
returns trigger language plpgsql as $$
begin
  insert into public.outbox(topic, payload)
  values ('order.created', jsonb_build_object('id', new.id, 'user', new.user_id));
  return new;
end;
$$;

create trigger trg_order_outbox
  after insert on public.orders
  for each row execute function public.emit_order_event();
​

这个 outbox 模式保证"写业务数据"和"发事件"在同一事务里，避免丢事件——外部 worker 再读 outbox 推给队列。

展开案例：用集成替代自研通知系统

背景：产品要在用户注册后发欢迎邮件、下单相通知。团队原本打算自己搭邮件服务和推送服务。

操作过程：

1. 邮件：用 Edge Function 在 auth.users 插入触发器后调用邮件服务的 API（密钥存函数环境变量，不暴露前端）。
2. 通知：订单变更写入 outbox（见上），外部轻量 worker 读 outbox 推到消息队列，再由队列触发各类通知渠道。
3. 文件处理：用户传图后，Storage 的事件经函数转去专用图像服务做压缩，回写缩略图路径。

结果：没自研邮件/推送核心，只写了薄薄的胶水（函数 + 触发器），把重活交给成熟外部服务。

解读：集成的价值是"让专业服务干专业事"。Supabase 负责事务与权限中枢，邮件、推送、搜索这些它有集成或容易桥接的，交给专门服务，团队聚焦业务。

变式：若外部服务不可用，outbox 模式让事件不丢——worker 重试即可。这也是为什么不用"函数里直接调外部 API 不等确认"，而是先落 outbox 再异步消费，可靠性更高。

收尾提醒

• 集成有四种形态：事件流出、认证源、逻辑复制、函数代理。
• 第三方登录开箱即用，但要有邮箱兜底防单点故障。
• outbox 模式让事件不丢，桥接外部服务更可靠。

提醒：在 Edge Function 里直接调外部 API 做关键业务（如扣费通知）却不落 outbox，一旦函数超时或外部 500，事件就丢了。关键事件先写库再异步消费，别赌网络。

建议：我们建议：凡是"发一次就好"的外部副作用，都用 outbox/队列解耦，Supabase 只管落数据和发事件，外部服务失败可重试。这样核心库不会被外部抖动拖垮。

四种集成形态的取舍对照

集成不是越多越好，选错形态反而引入脆弱点。下面把四种形态适合什么、不适合什么排清楚：

💡 关键直觉：集成的本质是"把不适合放在 Supabase 的事，交给擅长它的系统"，而 Supabase 退居事件与权限中枢。判断用哪种形态，看你的下游要的是"实时性"还是"可靠性"还是"计算力"——三者指向不同形态。

再展开一个案例：webhook 重试救回丢失的通知

背景：订单支付成功后要发短信通知，但短信网关偶发 500，导致部分用户没收到通知。

操作过程：

1. 原写法在 Edge Function 里直接调短信 API，网关 500 时事件随函数结束丢失。
2. 改为先落 outbox，再由带重试的 worker 消费（见上节 outbox 模式）。并给 webhook 目标配置指数退避重试：

-- outbox 消费状态由 worker 更新，失败可重试
update public.outbox
set sent = true, sent_at = now()
where id = $1;
-- worker 只取 sent = false 且重试次数 < 5 的行
​

3. 短信网关恢复后，积压的未发送事件被 worker 逐条补发，带指数退避（1s、2s、4s…）。
4. 用户最终全部收到通知，无遗漏。

结果：偶发外部故障不再造成永久丢失，系统具备自愈能力。

解读：和外部服务的交互永远假设"它会挂"。落 outbox + 重试，是把"尽力而为"变成"最终送达"的标准做法。Supabase 本身不替你保证外部可达，但 outbox 模式给你一个可靠的缓冲层。

⚠️ 常见坑：有人给 webhook 配了无限重试却不设上限，结果外部服务长期故障期间，积压事件把数据库撑爆。重试必须带上限和告警——超过阈值就转人工/死信队列，而不是无脑一直重试。

第五章把生态讲完。第六章落到真实行业：MVP、实时协作、数据分析、移动后端、游戏、以及几个成功案例，看前面学的东西怎么在真实产品里组装。