wix-cli-service-plugin

Wix 服务插件（SPI）构建器

为 Wix CLI 应用创建服务插件扩展。服务插件是一组由 Wix 定义的 API，你可以用它向 Wix 商业解决方案现有的后端流程中注入自定义逻辑，或为 Wix 网站引入全新的流程。

实现服务插件后，Wix 会在特定流程中调用你的自定义函数。常见用例包括电子商务自定义（配送、费用、税费、验证）和预约自定义（员工排序），但服务插件可以扩展任何提供 SPI 的 Wix 商业解决方案。

快速入门清单

创建服务插件时，请按顺序执行以下步骤：

1. 阅读与你的 SPI 类型对应的参考文档，然后停止并调用 ReadFullDocsMethodSchema，并传入参考文档中的文档 URL，以获取确切的请求/响应类型——在获得架构之前，不要编写任何代码
2. 创建插件文件夹：src/extensions/backend/service-plugins/<service-type>/<plugin-name>/
3. 创建 plugin.ts，其中包含正确的导入和 provideHandlers() 调用
4. 实现所有必需的处理函数，并编写完整的业务逻辑
5. 创建 extensions.ts，其中包含适当的构建器方法和唯一 UUID
6. 更新 src/extensions.ts，导入并使用新扩展
7. 运行 npx tsc --noEmit，验证 TypeScript 编译通过
8. 运行 npx wix build，验证构建成功
9. 触发相关的网站操作进行测试（例如，添加到购物车以测试费用）

参考文档

实现相关 SPI 前，必须先阅读对应的参考文档。 每份参考文档都包含正确的导入语句、处理函数签名、响应结构和可运行示例。

SPI 类型	参考文档
附加费用	ADDITIONAL-FEES.md
折扣触发器	DISCOUNT-TRIGGERS.md
礼品卡	GIFT-CARDS.md
配送费率	SHIPPING-RATES.md
税费计算	TAX-CALCULATION.md
验证	VALIDATIONS.md
预约员工排序	BOOKINGS-STAFF-SORTING.md

输出结构

服务插件由两个协同工作的文件组成。注册插件还需要一个扩展构建器文件。

src/extensions/backend/service-plugins/
└── {service-type}/
    └── {plugin-name}/
        ├── plugin.ts           # Handler logic with provideHandlers()
        └── extensions.ts       # Builder configuration (id, name, source)

文件说明

文件	用途
plugin.ts	包含服务插件处理逻辑和 provideHandlers()——你将在此实现自定义业务逻辑
extensions.ts	包含服务插件构建器配置，包括 id（GUID）、名称、源路径和构建器专属的可选字段

实现要求

生成要求

1. 实现所有必需的处理函数，并编写完整的业务逻辑
2. 包含适当的 TypeScript 类型和错误处理
3. 重点实现用户提示中描述的确切业务逻辑

实现模式

• 如果某些功能未记录或不可用，请明确说明这一缺口，并且只实现文档中描述的最基本逻辑
• 按照 Wix 规范实现所有必需的处理函数
• 绝不使用占位内容——始终实现完整且可运行的功能

数据验证

所有服务插件都必须进行全面的数据验证：

• 验证来自 Wix 请求的所有输入数据
• 确保必需字段存在且格式正确
• 妥善处理缺失或格式错误的数据
• 验证业务逻辑约束（例如，最低订单金额、有效地址）

实现模式

处理器文件（plugin.ts）包含服务插件逻辑。它必须：

1. 从适当的软件包导入相关服务插件（例如，电商使用 @wix/ecom/service-plugins，Bookings 使用 @wix/bookings/service-plugins）
2. 使用包含处理器函数的对象调用 provideHandlers()
3. 每个处理器函数接收包含 request 和 metadata 的载荷
4. 返回该 SPI 类型所需的响应结构

import { shippingRates } from "@wix/ecom/service-plugins";

shippingRates.provideHandlers({
  getShippingRates: async (payload) => {
    const { request, metadata } = payload;

    // Implement custom logic based on request data
    // - request contains cart items, shipping address, etc.
    // - metadata contains currency, locale, etc.

    return {
      shippingRates: [
        {
          code: "custom-shipping",
          title: "Custom Shipping",
          logistics: {
            deliveryTime: "3-5 business days",
          },
          cost: {
            price: "9.99",
            currency: metadata.currency || "USD",
          },
        },
      ],
    };
  },
});

当相关网站操作触发处理器时，Wix 会自动调用处理器函数。自定义逻辑应放在各处理器函数中。

提升 API 调用的权限

从服务插件调用 Wix API 时，必须使用 @wix/essentials 中的 auth.elevate 提升权限。

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

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(items.query);
  const elevatedResponse = await elevatedFunction("myCollection");
  return elevatedResponse;
};

import { auth } from "@wix/essentials";
import { cart } from "@wix/ecom";

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(cart.getCart);
  const elevatedResponse = await elevatedFunction("cart-id");
  return elevatedResponse;
};

import { auth } from "@wix/essentials";
import { products } from "@wix/stores";

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(products.deleteCollection);
  const elevatedResponse = await elevatedFunction("collection-id");
  return elevatedResponse;
};

最佳实践

开发工作流

• 始终实现完整且可运行的功能——不要使用占位内容
• 根据 Wix 文档处理所有必填字段
• 为所有输入数据实现适当的验证
• 以 Wix 所需的确切格式返回响应
• 为所有失败情况添加全面的错误处理
• 使用有意义的变量名并保持代码结构清晰
• 使用不同的输入组合进行全面测试

实现指南

• 验证所有输入： 检查必填字段是否存在且格式正确
• 妥善处理错误： 返回适当的错误响应，不要抛出未处理的异常
• 返回确切格式： 响应必须与 Wix 文档规定的结构完全一致
• 使用 TypeScript 类型： 利用 SDK 类型提高类型安全性
• 测试边缘情况： 空购物车、缺少地址、无效数据
• 性能： 保持计算高效——每次结账都会运行这些计算
• 日志记录： 添加 console.log 以便调试，但尽量减少生产环境中的日志

扩展注册

扩展注册为必需步骤，共有两个必需步骤。

步骤 1：创建插件专属的扩展文件

每个服务插件都需要在其文件夹中有一个 extensions.ts 文件，其中包含与 SPI 类型对应的构建器方法：

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

export const ecomadditionalfeesMyFees = extensions.ecomAdditionalFees({
  id: "{{GENERATE_UUID}}",
  name: "My Additional Fees",
  source: "./extensions/backend/service-plugins/ecom-additional-fees/my-fees/plugin.ts",
});

重要：生成 UUID

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

构建器配置字段

所有构建器方法都接受以下三个字段：

字段	类型	描述
id	string	服务插件 ID，格式为 GUID。在项目的所有扩展中必须唯一。
name	string	服务插件名称（开发应用时会显示在应用控制面板中）。
source	string	服务插件处理程序文件的路径，该文件包含插件逻辑。

按 SPI 类型划分的构建器方法及其接受的字段：

SPI 类型	构建器方法	接受的字段
配送费率	ecomShippingRates()	id、name、source、description、learnMoreUrl、dashboardUrl、fallbackDefinitionMandatory、thumbnailUrl
额外费用	ecomAdditionalFees()	id、name、source
验证	ecomValidations()	id、name、source、validateInCart
折扣触发器	ecomDiscountTriggers()	id、name、source
礼品卡	ecomGiftCards()	id、name、source
支付设置	ecomPaymentSettings()	id、name、source、fallbackValueForRequires3dSecure
预订员工排序	bookingsStaffSortingProvider()	id、name、source、methodName、methodDescription、dashboardPluginId

只有 ecomShippingRates() 接受 description。向其他构建器传递不支持的字段会导致 TypeScript 错误。bookingsStaffSortingProvider() 要求提供 methodName 和 methodDescription 字段，并可选接受 dashboardPluginId。

步骤 2：在主扩展文件中注册

**重要：**创建插件专属的扩展文件后，必须阅读 wix-cli-extension-registration，并按照“应用注册”部分更新 src/extensions.ts。

如果未完成步骤 2，服务插件将不会在电子商务系统中启用。

测试服务插件

要测试服务插件扩展：

1. 发布一个版本，包含你的更改——新服务插件或对现有插件的更改，只有在构建并发布项目后才会生效
2. 触发对服务插件的调用，执行相关操作（例如，向购物车添加商品并查看购物车，以测试额外费用）