mcpField
W
wix-cli-backend-event

wix-cli-backend-event

github.com/wix开发36282 次安装今天更新
代码仓库

关于 wix-cli-backend-event

面向 Wix CLI 应用开发者的后端事件扩展指南，介绍如何通过 JavaScript SDK webhook 在事件触发时运行处理逻辑。内容包括扩展文件、注册、权限、测试与处理器约束。

主要功能

  1. 01创建事件构建器与处理器
  2. 02通过 SDK webhook 响应事件
  3. 03将事件扩展注册到应用
  4. 04说明权限配置与 API 提权
  5. 05提供测试及幂等性建议

适用场景

  1. 01联系人创建时运行自定义逻辑
  2. 02订单或预订触发后执行处理
  3. 03文章发布后同步或处理数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wix/skills --skill wix-cli-backend-event

安装后在 Claude Code 中输入/wix-cli-backend-event确认已加载。

附带文件references/COMMON-EVENTS.md

详细介绍

Wix CLI 后端事件扩展

为 Wix CLI 应用创建事件扩展。当特定条件满足时会触发事件：对于应用项目，事件发生在 Wix 用户的网站上；对于无头项目，事件发生在你项目的网站上。你的项目通过基于 JavaScript SDK Webhook 构建的事件扩展进行响应；CLI 会将你的项目订阅到这些 Webhook。

常见用例：在创建联系人、下单、确认预约或发布博客文章时运行逻辑。

快速入门清单

创建事件扩展时，请按顺序执行以下步骤。

  1. 创建事件文件夹：src/extensions/backend/events/<event-name>/
  2. 创建 <event-name>.ts，其中包含 SDK 事件导入语句和处理函数
  3. 创建 <event-name>.extension.ts，其中包含 extensions.event() 和唯一 UUID
  4. 更新 src/extensions.ts，导入并使用新扩展

用户（手动）： 如有需要，在应用仪表板中配置事件的应用权限；发布一个版本并触发事件进行测试。

参考资料

主题参考资料
常见事件（CRM、电子商务、预约、博客）COMMON-EVENTS.md

输出结构

每个事件包含两个文件（文档）。应用中每个事件只能有一个处理函数（包括仪表板处理函数）。

src/extensions/backend/events/<event-name>/
├── <event-name>.extension.ts   # Builder: extensions.event({ id, source }) – id is unique GUID
└── <event-name>.ts             # Handler: imports SDK event (e.g. onContactCreated), runs on trigger

实现模式

事件构建器（<event-name>.extension.ts）

使用 @wix/astro/builders 中的 extensions.event()。必填字段：id（唯一 GUID）、source（处理函数文件的路径）。

import { extensions } from "@wix/astro/builders";

export const eventContactCreated = extensions.event({
  id: "{{GENERATE_UUID}}",
  source: "./extensions/backend/events/contact-created/contact-created.ts",
});

重要：生成 UUID

id 必须是唯一且静态的 UUID v4 字符串。为每个扩展生成一个全新的 UUID——不要使用 randomUUID()，也不要复制示例中的 UUID。将 {{GENERATE_UUID}} 替换为新生成的 UUID，例如 "a1b2c3d4-e5f6-7890-abcd-ef1234567890"。

事件处理函数（<event-name>.ts）

从正确的 SDK 模块导入事件，并传入处理函数。事件发生时，Wix 会使用事件负载和元数据调用该处理函数。处理函数签名请参阅 JavaScript SDK 参考。

import { onContactCreated } from "@wix/crm/events";

onContactCreated((event) => {
  console.log("Contact created:", event.entity);
  // Custom logic: sync to CRM, send welcome email, etc.
});

处理函数可以是 async；请确保捕获并记录错误，以免某个处理函数出错导致其他处理函数无法运行。

扩展注册

需要执行两个步骤。

步骤 1：事件构建器文件

如上方实现模式所示，在事件文件夹中创建 <event-name>.extension.ts（以及用于处理函数的 <event-name>.ts）。

步骤 2：在主 extensions.ts 中注册

重要： 阅读 wix-cli-extension-registration，并将事件扩展添加到 src/extensions.ts（导入并调用 .use(eventContactCreated) 或等效方法）。如果不执行此操作，事件扩展将不会生效。

命名：导出名称遵循 event{CamelCaseName} 格式（例如 eventContactCreated、eventOrderPaid）。

提升 API 调用权限

在事件处理函数中调用 Wix API 时，请使用 @wix/essentials 中的 auth.elevate，以便在调用时使用正确的权限。

import { auth } from "@wix/essentials";
import { items } from "@wix/data";

onContactCreated(async (event) => {
  const elevatedQuery = auth.elevate(items.query);
  const result = await elevatedQuery("MyCollection").find();
  // Use result
});

关键限制

  • 每个事件只能有一个处理函数——应用中不能有两个针对同一事件的事件扩展（本地或仪表板均不行）。
  • 权限——每个事件可能需要特定的权限范围；请在应用仪表板的 Permissions 页面中进行配置。
  • 测试——发布包含更改的版本，然后执行触发事件的操作。某些事件无法在本地开发环境中完全测试。
  • 后端限制——事件处理函数受后端扩展限制约束（例如，每个请求 1000 CPU ms、20 个子请求）。请参阅关于后端扩展。

最佳实践

  • 错误处理： 将处理器逻辑封装在 try/catch 中；记录日志，并可选择重新抛出错误或报告错误。
  • 幂等性： 事件可能被多次传递；尽可能将处理器设计为幂等。
  • 日志记录： 使用 console.log 进行调试；生产环境中的日志应尽量精简且不包含敏感信息。
  • 性能： 在后端限制时间内完成；如有需要，将繁重的工作移交给队列或后台任务。

测试事件扩展

  1. 发布 包含更改的版本。
  2. 触发 事件：执行相应操作。

评论

支持 Markdown