Gadget Shopify Sync API 实战：限制同步数量与时间范围

在开发 Shopify 应用时，通常需要把 Shopify 店铺中的产品、订单、客户或库存数据同步到应用自己的数据库中。

如果店铺只有几个产品，完整同步一次并不麻烦。但在开发测试阶段，或者面对拥有大量产品的店铺时，一次同步全部数据可能会带来几个问题：

• 同步时间过长。
• 开发环境消耗更多资源。
• 测试数据太多，不容易检查。
• Shopify API 请求数量增加。
• 数据库中出现大量暂时用不到的记录。
• 应用安装流程变慢。

Gadget Shopify Sync API 提供了更细的同步控制方式。开发者可以指定：

• 只同步最近的几条父级记录。
• 按更新时间或创建时间排序。
• 只同步某个时间点之后发生变化的数据。
• 在后台手动选择同步最近数据或全部数据。

本文演示如何使用 syncLast、syncLastBy 和 syncSince 控制 Shopify 数据同步。

这份项目实际演示了什么

在应用安装时限制首次同步

字幕中的示例配置在 Shopify Shop 安装 Action 的成功回调中。

当应用安装到 Shopify 店铺后，Gadget 会启动 Shopify 数据同步。开发者可以在这个安装流程中指定：

只同步最近 2 条产品记录

这样，开发环境就不会在安装应用时同步整个产品目录。

默认同步最近更新的产品

示例配置为：

syncLast: 2
syncLastBy: updatedAt

含义是：

按照 updatedAt 排序，只同步最近更新的 2 条父级产品记录

测试后，Gadget 数据库中只出现两个 Shopify 产品。

改为同步最近创建的产品

如果将排序字段改为：

syncLastBy: createdAt

同步逻辑就会变成：

按照 createdAt 排序，只同步最近创建的 2 条父级产品记录

这个选项适合测试“最近新建的产品”，而不是测试“最近修改过的产品”。

项目使用的技术栈

Gadget Shopify 应用

项目使用 Gadget 作为 Shopify 应用后端和数据同步平台。

Gadget 负责：

• 管理 Shopify 应用连接。
• 保存 Shopify 产品数据。
• 执行 Shopify 数据同步。
• 管理产品与变体模型。
• 处理 Shopify 安装流程。
• 提供同步 Action 和 API。
• 将数据写入托管数据库。

Shopify 产品模型

Shopify 产品是本项目的父级模型。

产品通常包含：

• 产品标题。
• 产品描述。
• 产品状态。
• 产品图片。
• 产品选项。
• 产品变体。
• 产品时间字段。

Shopify 产品变体模型

Shopify Product Variant 是产品的子级记录。

例如，一个产品可能有：

• Small、Medium、Large 三个尺码。
• Black、White 两种颜色。
• 多个价格和库存组合。

产品和变体之间存在父子关系：

Product
└── Product Variant
└── Product Variant
└── Product Variant

这条父子关系是理解 Gadget 同步范围的关键。

配置 syncLast

syncLast 的作用

syncLast 用于指定要同步多少条父级记录。

示意配置：

{
  syncLast: 2
}

这表示只同步最近的两条父级记录。

对于产品同步来说，父级记录就是 Product，而不是 Product Variant。

syncLast 不会限制所有记录数量

假设同步配置为：

{
  syncLast: 2
}

Shopify 中最近有两个产品：

Product A
Product B

其中 Product A 有 3 个变体，Product B 有 100 个变体。

同步结果会是：

2 个 Product
103 个 Product Variant

也就是说，syncLast 限制的是父级产品数量，而不是所有数据库记录的总数量。

Gadget 会同步这两个产品对应的全部变体，不会只取两个变体，也不会把变体拆成另一批只同步一部分。

为什么要按父级记录限制

父级限制更符合 Shopify 商品目录的结构。

如果只同步一个产品，就应该同时获得这个产品的完整变体信息，否则产品价格、库存和选项可能不完整。

因此，syncLast 的实际含义是：

限制同步多少个父级资源，同时保留这些资源的完整子记录

配置 syncLastBy

按更新时间同步

如果没有指定 syncLastBy，同步通常会使用更新时间字段。

为了让配置更清楚，可以显式指定：

{
  syncLast: 2,
  syncLastBy: "updatedAt"
}

这个配置会同步最近更新的两个产品。

适合以下场景：

• 测试最近修改的产品。
• 检查产品编辑后的同步结果。
• 验证应用是否可以读取最新商品信息。
• 快速同步开发店铺中刚刚调整的产品。

按创建时间同步

也可以使用创建时间：

{
  syncLast: 2,
  syncLastBy: "createdAt"
}

这个配置会同步最近创建的两个产品。

适合以下场景：

• 测试新建产品。
• 导入刚刚添加的商品。
• 验证产品安装流程。
• 在开发店铺中只抓取最新测试数据。

两种排序方式的区别

如果产品创建后长期没有修改，updatedAt 和 createdAt 得到的结果可能不同。

因此，在写同步逻辑前，先明确你真正需要的是：

最近创建的产品

还是：

最近更新的产品

在 Shopify 安装流程中使用

找到 Shopify Shop 安装 Action

在 Gadget 中打开 Shopify Shop 安装相关的 Action。

这个 Action 会在应用安装到 Shopify 店铺后执行。字幕中的配置位于安装成功后的处理逻辑中。

在安装成功后调用 Shopify 数据同步，并传入同步限制参数。

示意配置如下：

{
  syncLast: 2,
  syncLastBy: "updatedAt"
}

实际 Action 名称和参数结构可能根据 Gadget 项目模板不同而变化，应以当前项目自动生成的 API 和文档为准。

安装到开发店铺

选择一个 Shopify Development Store 安装应用。

安装完成后，Gadget 会启动同步流程。

如果同步参数是：

syncLast = 2
syncLastBy = updatedAt

那么 Gadget 数据库中应该只出现最近更新的两个父级产品。

检查 Product 数据

打开 Gadget 中的 Shopify Product 数据模型。

确认：

• 产品记录数量符合限制。
• 产品是最近更新的记录。
• 产品标题和状态正确。
• 产品的时间字段符合预期。

检查 Product Variant 数据

再打开 Shopify Product Variant 数据模型。

此时变体数量可能大于产品数量，这是正常现象。

例如：

2 个产品
20 个产品变体

并不表示 syncLast 失效。

它只说明这两个产品一共包含 20 个变体。

Gadget 编辑器中的同步选项

Sync all data

在 Gadget 安装页面中，可以通过下拉菜单选择：

Sync all data

这个操作会同步全部可用数据。

适合以下情况：

• 正式初始化开发环境。
• 需要完整测试产品目录。
• 需要构建完整的本地索引。
• 需要验证全部父子记录关系。

但如果店铺产品很多，不建议在每次开发测试时都使用完整同步。

Sync recent data

Gadget 编辑器中的：

Sync recent data

默认只同步最近的 10 条父级记录。

这和代码中显式设置 syncLast 的思路类似。

例如：

Sync recent data
→ 同步最近 10 个 Product
→ 同步这 10 个 Product 的全部 Variant

因此，后台页面显示 10 个产品，但变体可能超过 10 条。

两个按钮的区别

如果需要不同的数量，应该使用同步 API 配置，而不是依赖后台按钮的默认值。

使用 syncSince 做时间增量同步

syncSince 的作用

除了按数量限制同步，还可以按时间限制同步。

syncSince 用于指定一个时间点，只同步这个时间点之后的数据。

示意配置：

{
  syncSince: "2026-09-01T00:00:00Z"
}

它表达的意思是：

只同步 2026 年 9 月 1 日之后发生变化的记录

适合以下场景：

• 每天同步前一天的数据。
• 应用中断后从指定时间恢复。
• 只同步最近一段时间的变更。
• 避免重复同步整个产品目录。
• 构建定期增量同步任务。

syncSince 与 syncLast 的区别

如果你只需要开发环境中的少量测试数据，可以使用：

syncLast

如果你需要同步某个时间点之后的变化，可以使用：

syncSince

不要同时依赖错误的时间字段

如果业务关心的是“最近修改过的产品”，就应使用更新时间逻辑。

如果业务关心的是“最近新建的产品”，就应使用创建时间逻辑。

不要因为字段名称相似，就把创建时间和更新时间混用。

同步 API 的默认行为

不设置限制时会同步全部数据

字幕特别强调，如果调用同步 API 时没有指定：

syncLast

或：

syncSince

默认行为仍然是同步全部数据。

也就是说，下面这种调用没有数量限制：

{}

如果你只想同步少量数据，必须显式传入同步限制。

不能假设默认就是最近数据

后台页面中的 Sync recent data 默认同步最近 10 条父级记录，但这不代表所有同步 API 默认都只同步 10 条。

需要区分：

后台按钮的默认行为

和：

同步 API 的默认行为

在代码中，如果没有写 syncLast 或 syncSince，就不要假设它会自动限制数据量。

任何 Shopify 模型都可以使用

不只适用于产品

字幕中提到，这套同步配置不仅适用于 Shopify Product。

只要是 Gadget 支持的 Shopify 模型，都可以根据当前模型和 API 能力使用同步限制。

例如：

• Product。
• Product Variant。
• Customer。
• Order。
• Collection。
• Inventory 相关模型。
• Shopify 其他支持同步的资源。

具体可用字段和排序方式，应以当前 Gadget 模型设置和 Shopify API 支持情况为准。

Gadget 处理排序兼容性

即使某个 Shopify API 资源本身不支持按照指定时间字段排序，Gadget 也可能在后台完成排序和筛选，再返回最近创建或最近更新的记录。

这意味着开发者不需要为每个模型都手动实现一套排序逻辑。

不过，生产环境仍应通过实际测试确认：

• 返回记录是否符合预期。
• 时间字段是否存在。
• 分页和同步是否完整。
• 子记录是否正确关联。

开发环境中的推荐同步策略

第一次安装只同步少量数据

开发阶段可以使用：

{
  syncLast: 2,
  syncLastBy: "updatedAt"
}

这样能快速获得少量产品，方便测试：

• 产品读取。
• 产品详情。
• 产品变体。
• 产品图片。
• 数据关联。
• UI 渲染。

需要新建商品时切换为 createdAt

如果你刚刚创建了几个测试产品，可以临时使用：

{
  syncLast: 2,
  syncLastBy: "createdAt"
}

这样更容易找到刚创建的测试产品。

产品目录准备好后再同步全部

当数据模型、权限和应用逻辑已经稳定后，再执行：

Sync all data

不要在每次修改代码后都同步完整产品目录。

生产环境中的推荐同步策略

初始同步与持续同步分开设计

生产应用通常需要区分两种任务：

初始同步

和：

持续更新

初始同步用于把店铺已有数据导入应用。

持续更新用于处理之后新增或修改的数据。

初始同步可以根据店铺规模选择：

• 全量同步。
• 分批同步。
• 按时间范围同步。
• 按数量限制同步。

持续更新则可以结合：

• Shopify Webhook。
• 定时增量同步。
• syncSince。
• Gadget 数据同步任务。

Shopify 官方资料也将实时同步和周期性导入视为不同场景，产品变化频繁的大型目录通常需要更及时的数据更新策略。

避免把测试配置直接上线

开发阶段的配置可能是：

{
  syncLast: 2
}

上线后如果忘记修改，生产应用就只会同步两个产品。

发布前检查：

• 是否仍然设置了开发数量限制。
• 是否需要全量初始化。
• 是否应该使用 syncSince。
• 是否需要根据店铺规模分批同步。
• 是否需要通过 Webhook 处理后续变化。

处理产品和变体数据

父级产品决定同步范围

同步数量限制只应用于父级产品。

例如：

syncLast: 2

表示选择两个 Product。

然后，Gadget 会同步这两个产品下的全部 Product Variant。

变体不会被单独截断

如果第一个产品有 100 个变体，第二个产品有 5 个变体：

2 个 Product
105 个 Product Variant

这是预期行为。

系统不会把第一个产品的变体只截取一部分，因为这样可能导致产品数据不完整。

需要控制变体数量怎么办

如果应用只需要少量变体，就不能简单依赖 syncLast。

可以考虑：

• 只同步少量父级产品。
• 在应用查询时筛选变体。
• 只保存业务需要的变体字段。
• 设计单独的变体处理流程。
• 根据库存或状态在应用层过滤。

不要误以为 syncLast 可以限制所有父级和子级记录的总数量。

实际测试步骤

测试同步两个产品

在 Shopify 开发店铺中准备多个产品，并修改其中一些产品。

配置：

{
  syncLast: 2,
  syncLastBy: "updatedAt"
}

安装应用并等待同步完成。

然后检查 Gadget Product 数据模型。

预期结果：

Product 数量为 2

这两个产品应该是最近更新的两个产品。

检查产品变体

打开 Product Variant 数据模型。

预期结果是：

变体数量可能大于 2

只要这些变体都属于那两个同步进来的产品，结果就是正确的。

测试 Sync recent data

在 Gadget 安装页面点击：

Sync recent data

然后检查 Product 数据。

预期结果是最近 10 个父级产品。

如果产品变体数量超过 10，不需要认为同步出错。

测试 Sync all data

从同步按钮的下拉菜单中选择：

Sync all data

等待同步完成后，检查 Product 数量是否与 Shopify 店铺目录一致。

产品量较大时，同步可能需要更长时间，应避免在开发测试中频繁执行全量同步。

测试 syncSince

设置一个时间点：

{
  syncSince: "2026-09-01T00:00:00Z"
}

然后检查只有该时间点之后创建或更新的记录进入同步结果。

测试时要注意时区和时间字段，最好统一使用 ISO 8601 和 UTC 时间。

常见错误

误以为 syncLast 限制所有记录

错误理解：

syncLast: 2

等于只同步两条数据库记录。

正确理解：

syncLast: 2

只限制两个父级记录，父级记录的所有子记录仍然会被同步。

忘记指定 syncLast

如果代码中没有指定 syncLast 或 syncSince，同步 API 默认可能会执行全量同步。

开发环境中建议显式配置限制，避免一次导入过多数据。

把 Sync recent data 当成 API 默认行为

后台按钮默认同步最近 10 条父级记录，但这不代表代码中的同步 API 也默认只同步 10 条。

代码和后台按钮需要分别理解和测试。

把 createdAt 和 updatedAt 混淆

如果你要测试最近修改的商品，应使用 updatedAt。

如果你要测试最近新建的商品，应使用 createdAt。

只检查产品，不检查变体

产品同步完成后，必须同时检查 Product Variant。

因为产品本身可能只有几条，但变体数量可能非常多。

总结

这份字幕演示的是 Gadget Shopify Sync API 的同步范围控制功能。

核心参数包括：

syncLast
syncLastBy
syncSince

它们分别用于：

• 限制最近同步的父级记录数量。
• 指定按创建时间还是更新时间排序。
• 只同步某个时间点之后的数据。

最重要的行为是：

syncLast 只限制父级记录，不限制子级记录

例如：

同步 2 个 Product
→ 同步这 2 个 Product 的全部 Product Variant

此外，Gadget 编辑器中的同步按钮也有不同含义：

• Sync recent data 默认同步最近 10 条父级记录。
• Sync all data 执行全量同步。
• 同步 API 如果没有指定 syncLast 或 syncSince，默认仍可能同步全部数据。

在开发阶段，建议先使用少量产品进行测试，减少同步时间和资源消耗。等数据模型与应用逻辑稳定后，再根据生产店铺规模选择全量同步、时间增量同步或 Webhook 持续更新。

参考资料

citation:Get product variant data

citation:Setting up agentic storefronts and choosing product data sync methods

citation:Shopify Winter ’25 产品数据更新