# Wix CLI 后端事件扩展为 Wix CLI 应用程序创建事件扩展。当特定条件发生时，事件就会被触发——在应用程序项目的 Wix 用户站点上，或者在无头项目的项目站点上。您的项目使用基于 JavaScript SDK Webhooks 构建的事件扩展进行响应； CLI 为您的项目订阅这些 webhook。常见用例：在创建联系人、下订单、确认预订或发布博客文章时运行逻辑。 ## 快速入门清单创建事件扩展时请按顺序执行以下步骤。 1. 创建事件文件夹：`src/backend/events/<事件名称>/` 2. 使用 SDK 事件导入和处理函数创建 `.ts` 3. 使用“extensions.event()”和唯一的 UUID 创建“.extension.ts” 4.更新 `src/extensions.ts` 以导入并使用新扩展 **用户（手动）：** 如果需要，在应用程序仪表板中配置事件的应用程序权限；发布版本并触发事件进行测试。 ## 参考文献主题 |参考 ---|--- 常见事件（CRM、电子商务、预订、博客）| [常见事件.md]() ## 输出结构每个事件两个文件（[文档]()）。应用程序中仅允许每个事件**一个**处理程序（包括仪表板处理程序）。 src/backend/events/<事件名称>/ ├── .extension.ts # Builder:extensions.event({ id, source }) – id 是唯一的 GUID └── .ts # Handler：导入SDK事件（例如onContactCreated），在触发器上运行 ## 实现模式 ### 事件生成器 (`.extension.ts`) 使用来自“@wix/astro/builders”的“extensions.event()”。必填字段：“id”（唯一 GUID）、“source”（处理程序文件的路径）。从“@wix/astro/builders”导入{扩展}；导出 const eventContactCreated = Extensions.event({ id：“{{GENERATE_UUID}}”，来源：“./backend/events/contact-created/contact-created.ts”， }); **关键：UUID 生成** `id` 必须是唯一的静态 UUID v4 字符串。为每个扩展生成一个新的 UUID - 不要使用“randomUUID()”或从示例中复制 UUID。将“{{GENERATE_UUID}}”替换为新生成的 UUID，例如“a1b2c3d4-e5f6-7890-abcd-ef1234567890”。 ### 事件处理程序（`<事件名称>.ts`）从正确的 SDK 模块导入事件并传递处理程序。当事件发生时，Wix 使用事件负载和元数据调用处理程序。处理程序签名记录在 [JavaScript SDK 参考]() 中。从“@wix/crm/events”导入{ onContactCreated }； onContactCreated((事件) => { console.log("联系人已创建：", event.entity); // 自定义逻辑：同步到CRM、发送欢迎邮件等。 }); 处理程序可以是“异步”；确保捕获并记录错误，以便一个失败的处理程序不会破坏其他处理程序。 ## 扩展注册 **需要两个步骤。** ### 第 1 步：事件构建器文件在事件文件夹内创建“.extension.ts”（为处理程序创建“.ts”），如上面的实现模式所示。 ### 第2步：在主extensions.ts中注册 **关键：** 阅读 [wix-cli-extension-registration]() 并将事件扩展添加到 `src/extensions.ts` （导入和 `.use(eventContactCreated)` 或等效项）。如果没有这个，事件扩展就不会激活。命名：导出名称遵循“event{CamelCaseName}”（例如“eventContactCreated”、“eventOrderPaid”）。 ## 提升API调用权限从事件处理程序内部调用 Wix API 时，请使用“@wix/essentials”中的“auth.elevate”，以便调用以正确的权限运行。从“@wix/essentials”导入{auth}；从“@wix/data”导入{items}； onContactCreated（异步（事件）=> { constlevedQuery = auth.elevate(items.query); const 结果 =等待leviedQuery("MyCollection").find(); // 使用结果 }); ## 主要限制 * **每个事件一个处理程序** – 应用程序（本地或仪表板）中的同一事件不能有两个事件扩展。 * **权限** – 每个事件可能需要特定的权限范围；在应用程序仪表板（权限页面）中配置它们。 * **测试** – 发布包含更改的版本，然后执行触发事件的操作。有些事件在本地开发中无法完全测试。 * **后端限制** – 事件处理程序在后端扩展限制下运行（例如每个请求 1000 CPU 毫秒，20 个子请求）。请参阅[关于后端扩展]()。 ## 最佳实践 * **错误处理：** 将处理程序逻辑包装在 try/catch 中；记录并可选择重新抛出或报告。 * **幂等性：** 事件可以多次传递；尽可能将处理程序设计为幂等。 * **日志记录：** 使用 `console.log` 进行调试；保持生产日志最少且不敏感。 * **性能：** 在后端限制内完成；如果需要，将繁重的工作卸载到队列或后台作业。 ## 测试事件扩展 1. **发布**包含您的更改的版本。 2. 通过采取行动**触发**事件。 ## 验证实现后，使用 wix-cli-app-validation 来验证 TypeScript、构建和预览。

Wix CLI 后端事件

包含技能