Realtime Database 写入触发 Webhook 回调:functions-samples minimal-webhook 示例源码级解析

原创2026-10-13 14:02:241,684 阅读
文章标签:示例工程

Realtime Database 写入触发 Webhook 回调:functions-samples minimal-webhook 示例源码级解析

本文围绕 functions-samples 仓库中的 Node-1st-gen/minimal-webhook 示例,讲解如何利用 Cloud Functions for Firebase(1st gen)监听 Realtime Database 指定路径下的数据写入事件,并把变更数据以 HTTP POST 形式转发给一个硬编码的外部 Webhook 回调地址。读完本文,你将掌握 functions.database.ref(...).onCreate 触发器、通配符路径捕获、snap.val() 数据序列化、fetch 请求与响应状态检查的完整写法,以及从本地模拟到云端部署的实操路径。

示例在仓库中的定位

在仓库根目录 README.md 的示例索引中,该示例被归入 “Webhook upon Firebase Database writes” 一类,描述为:

Writing to the Firebase Database triggers a request to a callback URL (a Webhook). The content of the modified Data is sent to the Webhook. Uses a Realtime Database trigger.

即:向 Firebase 数据库写入数据 → 触发一次对回调 URL(Webhook)的请求 → 被修改的数据内容随请求发送到该 Webhook。它使用的是 Realtime Database 触发器。

同时需要注意示例所属目录的定位:Node-1st-gen 目录专门存放 第一代(1st gen) Node.js 云函数示例,Node-1st-gen/README.md 中明确指出:第二代(2nd gen)函数已经可用,且是 Cloud Functions for Firebase 的推荐平台。因此本文所述的写法是基于 1st gen SDK 的经典示例,适合理解事件驱动函数的触发与回调模型,生产环境可参考该说明评估是否迁移到 2nd gen。

触发器与核心代码解析

示例的完整实现位于 functions/index.js,去除许可证头后主体代码如下:

'use strict';

const functions = require('firebase-functions/v1');

// This is the URL that we will callback and send the content of the updated data node.
// As an example we're using a Request Bin from http://requestb.in
// TODO: Make sure you create your own Request Bin and change this URL to try this sample.
const WEBHOOK_URL = 'http://requestb.in/1mqw97l1';

// Reads the content of the node that triggered the function and sends it to the registered Webhook
// URL.
exports.webhook = functions.database.ref('/hooks/{hookId}').onCreate(async (snap) => {
  const response = await fetch(WEBHOOK_URL, {
    method: 'post',
    body: JSON.stringify(snap.val()),
    headers: {'Content-Type': 'application/json'}
  });

  if (!response.ok) {
    throw new Error(`HTTP Error: ${response.status}`);
  }
  functions.logger.log('SUCCESS! Posted', snap.ref);
});

第一代 SDK 的引入方式

代码通过 require('firebase-functions/v1') 显式引入 1st gen API。对应的依赖声明位于 functions/package.json,当前仓库锁定的版本为 firebase-functions ^7.4.0 与 firebase-admin ^14.5.0(见 functions/pnpm-lock.yaml),运行时引擎为 Node 22("engines": {"node": "22"}),因此可以直接使用 Node 内置的全局 fetch API 发起外部 HTTP 请求。

触发器声明:路径、通配符与事件类型

exports.webhook = functions.database.ref('/hooks/{hookId}').onCreate(async (snap) => { ... });

这行声明包含三个关键信息:

  • 监听路径:/hooks,即示例约定的数据库根节点;
  • 通配符捕获:{hookId} 会匹配 /hooks 下的任意一级子节点,并把该节点的键(如 key-123456)作为参数传入(虽然本例回调体未使用它,但通配符保证了每个子节点写入都会各自触发一次执行);
  • 事件类型:onCreate,仅在节点新建时触发,回调参数 snap 是包含新数据快照的 DataSnapshot。

数据读取与请求构造

const response = await fetch(WEBHOOK_URL, {
  method: 'post',
  body: JSON.stringify(snap.val()),
  headers: {'Content-Type': 'application/json'}
});
  • snap.val() 取出触发节点下的完整数据对象;
  • JSON.stringify(...) 将其序列化为 JSON 字符串,作为 POST 请求体;
  • 请求头显式声明 Content-Type: application/json,让接收方(Webhook 服务)能正确解析请求体;
  • await 保证函数等待请求完成后再退出,避免执行被提前终止。

响应状态检查与日志

if (!response.ok) {
  throw new Error(`HTTP Error: ${response.status}`);
}
functions.logger.log('SUCCESS! Posted', snap.ref);
  • 通过 response.ok(即状态码是否为 2xx)判断 Webhook 是否接收成功;
  • 失败时抛出携带状态码的 Error,把本次调用标记为失败,便于在 Cloud Logging 中定位问题;
  • 成功时使用 functions.logger.log 输出日志,并附带触发节点的引用 snap.ref,方便核对是哪个路径的写入触发了回调。

示例数据库结构:/hooks 下的数据组织

原文档给出了一份可直接对照的示例数据布局。假设 Firebase 项目 ID 为 functions-project-12345,在 /hooks 下写入两个子节点,就会分别触发两次 webhook 函数执行:

/functions-project-12345
    /hooks
        /key-123456
            stuff: "Whatever"
            more_stuff: "Cool"
        /key-123457
            things: "A car"
            more_things: "A truck"

子节点内容可以是任意字段组合。每次写入后,Webhook 收到的请求体(JSON)大致如下:

{"stuff": "Whatever", "more_stuff": "Cool"}

这种“一个子节点 = 一次回调”的数据组织方式,让 /hooks 天然成为一条 Webhook 投递队列:客户端只需向该路径推送数据,即可触发外部服务的同步。

触发范围说明:原文档将行为描述为“在 /hooks 下添加或更新元素将触发 Webhook”,而当前仓库源码实际使用的是 onCreate 触发器——即只在节点首次创建时触发,对已存在节点的 update() / set() 覆盖写入不会再次触发。如需同时覆盖“新增 + 更新”场景,可将触发器改为 onWrite(它会同时捕获创建、更新与删除),同仓库的 Node-1st-gen/child-count/functions/index.js 即使用 onWrite 处理 change.before / change.after 的对比逻辑,可作为扩展参考。

硬编码的 WEBHOOK_URL 与 Request Bin 可视化

回调目标被硬编码在源码第 23 行:

const WEBHOOK_URL = 'http://requestb.in/1mqw97l1';

原文档明确提醒:示例使用的是 Request Bin(requestb.in 提供的临时 HTTP 接收服务),它的作用是接收请求并展示请求体,让你无需自建服务即可直观看到函数发出的数据。必须创建属于自己的 Request Bin,并把新的回调地址替换进 WEBHOOK_URL 后再运行本示例(源码中的 TODO 注释也做了同样提示)。这类临时接收服务让“数据库写入 → 云函数转发 → 外部收到 JSON”的整条链路可被端到端可视化验证,非常适合先跑通流程再接入真实业务系统。

需要说明的是:把回调地址直接写死在代码里仅适用于本示例的教学目的;生产环境不应将敏感 URL 或密钥硬编码,更合适的做法是使用 Cloud Secret Manager 管理(下文展开)。

上线前提:Blaze 计费套餐

原文档特别强调了一个部署前提:

You will need to enable billing on your Firebase the project by switching to the Blaze plan, this is currently needed to be able to perform HTTP requests to external services from a Cloud Function.

即:Cloud Functions 若要向外部(非 Google 服务)发起 HTTP 出站请求,必须将 Firebase 项目切换到 Blaze(按量付费) 计费套餐。这是 Firebase 平台对云函数出站网络的既有限制,不是示例自身的可选配置——凡是部署到云端执行对外请求的 1st gen 函数都需要满足该前提。在切换前,你无法在正式环境中跑通本示例的 Webhook 转发。

项目配置文件速览

示例目录包含三个配套配置文件,均围绕“最小化”设计:

文件 作用
functions/index.js 唯一云函数实现(webhook)
functions/package.json 依赖、脚本与运行时声明
firebase.json Firebase 项目级配置(codebase 标识)

其中 firebase.json 内容极简:

{
    "functions": {
      "codebase": "minimal-webhook"
    }
}

codebase 字段用于在同一个 Firebase 项目中区分多个独立的函数源码目录,部署时可按 codebase 精准发布。而 functions/package.json 中预置的脚本,直接对应下文各种运行方式:

{
  "scripts": {
    "lint": "./node_modules/.bin/eslint --max-warnings=0 .",
    "serve": "firebase emulators:start --only functions",
    "shell": "firebase functions:shell",
    "start": "npm run shell",
    "deploy": "firebase deploy --only functions",
    "logs": "firebase functions:log",
    "compile": "cp ../../../tsconfig.template.json ./tsconfig-compile.json && tsc --project tsconfig-compile.json"
  }
}
  • lint:执行仓库配置的 ESLint 检查(eslint.config.js 对示例代码放宽了 no-console、no-unused-vars 等规则,便于教学代码通过检查);
  • serve:启动 Functions Emulator,本地模拟云函数,无需部署即可验证;
  • shell / start:进入交互式函数调用壳,便于直接调用函数测试;
  • deploy:仅部署 functions 资源到云端;
  • logs:查看已部署函数的云端日志。

本地模拟与云端部署实操

该示例没有像同仓库 Node-1st-gen/github-to-slack/README.md 那样给出逐步部署清单,但依据上述配置文件,可以按以下流程完整跑通(依赖安装工具可选用仓库采用的 pnpm,仓库根目录存在 pnpm-workspace.yaml 工作区配置):

  1. 安装依赖:进入 functions 目录执行 pnpm install(或 npm install);
  2. 本地模拟(推荐先跑通):执行 pnpm serve 启动 Emulator,然后在数据库中向 /hooks 下写入任意子节点(或通过 pnpm shell 直接调用 webhook 函数),观察回调接收服务是否收到 JSON 请求体;
  3. 配置项目:firebase use --add 选择目标 Firebase 项目,并确认项目已切换到 Blaze 套餐(见上文前提);
  4. 部署:执行 pnpm deploy 完成 firebase deploy --only functions;
  5. 触发与观察:在真实 Realtime Database 的 /hooks 下写入数据,随后执行 pnpm logs 查看云函数日志,应能看到 SUCCESS! Posted /hooks/{hookId};若 Webhook 返回非 2xx,日志中会出现 HTTP Error: <status> 错误。

生产化改进方向(结合同仓库更完整的示例)

本示例刻意保持“最小”,只包含一条核心链路。如果要在真实业务中复用这个模式,可以参照 functions-samples 仓库中其他同类示例的做法逐步加固:

  • 用 Secret Manager 替代硬编码 URL:Node-1st-gen/minimal-webhook 将回调地址写死在源码中;而同仓库的 Node-1st-gen/testlab-to-slack/functions/index.js 使用 defineSecret('SLACK_WEBHOOK_URL') 声明机密参数,并在 runWith({secrets: [...]}) 中注入,再通过 firebase functions:secrets:set 写入,可避免敏感地址进入代码库;
  • 错误处理与可观测性:示例仅在失败时抛错、成功时打日志。更复杂的场景可参考 Node-1st-gen/testlab-to-slack/functions/index.js 把响应体记录下来,便于排查接收方解析问题;此外触发型函数执行失败会体现为调用失败,建议结合 Cloud Logging 持续观察;
  • 扩展触发器语义:如前文所述,将 onCreate 换成 onWrite 可同时捕获新增与更新,需要时可用 change.before / change.after 区分事件类型。

小结

minimal-webhook 用一个函数、一条数据库路径和一个回调地址,完整演示了 Realtime Database 事件驱动 → 云函数执行 → 外部 Webhook 接收 的最小闭环:核心代码是 functions/index.js 中 functions.database.ref('/hooks/{hookId}').onCreate 与 fetch POST 的组合,前提条件是 Firebase 项目处于 Blaze 套餐,验证手段是 Request Bin 之类的临时接收服务,扩展方向则是用 Secret Manager 管理回调地址、用 onWrite 覆盖更新场景。对于想快速理解 Cloud Functions 事件触发器与 HTTP 出站回调模型的开发者,这是一个起点极低、链路清晰的入门示例。

登录后查看全文
functions-samples