使用 Gadget 为 Shopify Shop Mini 构建安全的 JWT 后端认证

Shopify Shop Mini 是运行在 Shop App 里的小型购物应用。

它不是普通网页，也不是 Shopify 后台应用。Shop Mini 面向消费者，可以帮助客户发现商品、比较商品、获得推荐，或者使用一些 Shop App 本身没有提供的小功能。

本文演示如何为 Shop Mini 配置一个 Gadget 自定义后端，并完成以下功能：

使用 React 和 Tailwind 创建 Shop Mini。
使用 Gadget 作为 Node.js 后端和 PostgreSQL 数据库。
从 Shop Mini 获取 Shopify 用户令牌。
通过 Gadget 后端验证用户令牌。
使用 JWT 在 Shop Mini 和 Gadget 之间建立登录状态。
将用户和 Session 保存到 Gadget 数据库。
使用 Gadget Access Control 实现多租户数据隔离。
从 Shop Mini 调用 Gadget GraphQL API。

需要特别说明的是，这个项目主要完成了 Shop Mini 的后端认证模板，并没有在字幕中完整开发最终的购物功能。后续可以在这个认证基础上继续增加商品推荐、图片识别、个性化搜索等功能。

什么是 Shopify Shop Mini

Shop Mini 运行在哪里

Shop Mini 是运行在 Shopify Shop App 中的互动购物体验。

它使用 Web 技术开发，例如：

HTML。
CSS。
JavaScript。
React。
Tailwind CSS。

但它不是直接运行在普通浏览器网页里，而是运行在 Shop App 提供的移动环境中。

客户可以在 Shop App 中打开 Shop Mini，使用商品推荐、互动问答、视频购物、虚拟试穿等功能。

Shop 官方资料显示，Shop Minis 可以由 Shopify 或 Shopify Partner 开发，并且需要经过 Shop 审核后才能进入 Shop App。

Shop Mini 与 Shopify 后台应用的区别

Shopify 后台应用主要服务于商家，例如：

管理产品。
处理订单。
查看客户。
管理库存。
配置营销活动。

Shop Mini 主要服务于买家，例如：

帮客户发现商品。
根据客户偏好推荐商品。
帮客户寻找适合自己的产品。
提供图片识别或商品搭配功能。
在 Shop App 中创建互动购物体验。

因此，Shop Mini 更接近一个运行在 Shopify Shop App 里的移动购物工具，而不是商家后台工具。

这次实际演示的项目

字幕中的项目名称类似于一个 Shop Mini OAuth 示例。

它的重点不是马上做出完整的商品推荐应用，而是先完成 Shop Mini 和 Gadget 后端之间的身份认证。

项目包含以下部分：

一个 Shopify Shop Mini 前端。
一个 Gadget 后端应用。
一个 Gadget PostgreSQL 数据库。
一个 Shop Mini 用户模型。
一个 Session 模型。
一个用于验证 Shopify 用户令牌的 OAuth 路由。
一个用于签发 JWT 的后端流程。
一个用于调用 Gadget GraphQL API 的前端请求。
一个 Shop Mini 买家角色。
一套基于 Session 的访问权限控制。

测试成功后，可以在 Gadget 中看到：

Shop Mini 用户 ID。
用户令牌过期时间。
用户状态。
用户对应的 Session。
Session 使用的 Shop Mini 买家角色。

项目使用的技术栈

Shop Mini 前端

Shop Mini 前端使用：

React。
TypeScript。
Tailwind CSS。
Shopify Shop Mini React SDK。
Shopify 提供的用户令牌 Hook。
Shopify Secure Storage。
fetch。
GraphQL 请求。

Shop Mini 对第三方 npm 包有比较严格的限制。不能像普通 React 项目一样随意安装任意依赖。

如果项目需要使用没有被允许的包，需要按照 Shopify 当前流程提交审核。审核通过之前，不应该假设这个包可以用于正式发布。

Gadget 后端

Gadget 后端提供：

托管的 Node.js 后端。
托管的 PostgreSQL 数据库。
自动生成的 GraphQL API。
数据模型。
CRUD 操作。
HTTP Route。
环境变量。
Access Control。
JWT 验证。
Session 管理。

Gadget 的优势是，开发者不需要从零开始搭建服务器、数据库、用户表和权限系统。

JWT 身份验证

Shop Mini 首先从 Shopify 获取用户令牌。

然后：

Shop Mini 将用户令牌发送给 Gadget。
Gadget 后端调用 Shopify Admin API 验证令牌。
Gadget 读取用户的公开 ID、状态和过期时间。
Gadget 创建或更新对应的 Shop Mini 买家记录。
Gadget 创建或读取这个买家的 Session。
Gadget 签发一个 JWT。
Shop Mini 保存 JWT。
之后的请求使用这个 JWT 访问 Gadget GraphQL API。

这个流程可以把 Shopify 用户和 Gadget 内部 Session 连接起来。

创建 Gadget Shop Mini 模板项目

使用专用模板创建应用

这个项目不是通过 Gadget 普通应用创建页面开始的，而是使用专门的 Shop Mini 后端模板。

打开 Gadget 的 Shop Mini 模板创建地址，创建一个新的项目。

输入应用名称，例如：

shop-mini-backend

这个模板会自动创建一些基础内容：

Shop Mini 买家模型。
Session 模型。
OAuth 路由。
JWT 配置。
环境变量。
Shop Mini 买家 Access Control 角色。
Gadget 后端项目。
PostgreSQL 数据库。
默认 Web 前端。

字幕中的演示暂时不使用 Gadget 默认的 Web 前端，而是把重点放在 Shop Mini 和后端认证上。

检查 Mini Buyer 模型

模板会自动创建一个 Shop Mini 买家模型，名称可以理解为：

Mini Buyer

这个模型用于保存 Shop Mini 用户信息。

常见字段包括：

publicId。
session。
tokenExpiresAt。
state。

这些信息来自 Shopify Shop Mini 的用户认证流程。

其中：

publicId 用于标识 Shopify 返回的用户。
tokenExpiresAt 用于保存用户令牌过期时间。
state 用于保存 Shopify 提供的用户状态。
session 用于连接 Gadget 内部的权限会话。

检查 Session 模型

模板还会自动创建 Session 模型。

Session 用于保存当前 Shop Mini 用户在 Gadget 中的登录状态。

Session 需要关联一个访问角色，例如：

shop mini buyers

后续使用这个 Session 签发的 JWT 请求 Gadget API 时，Gadget 就可以根据这个角色判断用户能做什么。

配置 Gadget 环境变量

配置 JWT 签名密钥

模板会自动提供 JWT 签名密钥环境变量。

这个密钥用于签署 Gadget 返回给 Shop Mini 的 JWT。

不要把这个密钥写进前端代码，也不要把它提交到公开代码仓库。

前端只能保存后端返回的 JWT，不能知道用于签署 JWT 的服务器密钥。

配置 Shop Mini Admin API Key

Shop Mini 项目通过 npx shop-minis setup 创建配置文件，其中包含 Shop Minis Admin API Key。

这个 API Key 需要保存到 Gadget 的环境变量中，并设置为 Secret。

环境变量的名称应以当前 Gadget 模板 README 中的配置为准。字幕中的模板使用了 Shop Minis Admin API Key 相关环境变量。

这个 Key 只应该存在于 Gadget 后端，不应该直接写进 Shop Mini 前端代码。

将 Gadget 项目同步到本地

使用 Gadget CLI

使用 Gadget 当前模板 README 中提供的命令，将项目同步到本地。

字幕中使用的是 Gadget CLI，也就是 ggt 工具。

同步后，项目文件会被下载到本地，因此可以使用：

Visual Studio Code。
Cursor。
Git。
Shopify CLI。
Xcode。
Android Studio。

本地同步的好处是，Gadget 负责托管后端和数据库，开发者仍然可以在本地生成和调试 Shop Mini。

检查项目目录

同步后的项目大致包含：

api/
models/
routes/
web/
minis/
package.json

其中：

api 用于 API 和数据操作。
models 对应数据库模型。
routes 用于 HTTP 路由。
web 是 Gadget 默认 Web 前端。
minis 用于保存 Shopify Shop Mini 项目。

字幕中的 Shop Mini 会被创建在 minis 目录下。

使用 Shopify CLI 生成 Shop Mini

进入 Minis 目录

在终端中进入 Shop Mini 目录：

cd minis

生成 Shop Mini 项目

使用 Shopify Shop Mini 当前提供的脚手架命令生成项目。

字幕演示的核心流程是：

shopify app generate extension

不过 Shop Mini 使用的命令和模板可能会随 Shopify CLI 版本变化。实际开发时，应使用当前 Shopify Shop Mini 文档和项目 README 中提供的生成命令。

生成过程中需要输入 Mini 名称。

名称不要随意包含受 Shopify 保护或限制使用的词语，例如：

Shopify。
Shop。
Mini。

正式提交前，应检查当前 Shop Mini 命名规则。

生成后的项目结构

生成的 Shop Mini 通常会包含：

my-shop-mini/
  package.json
  tsconfig.json
  manifest.json
  src/
    App.tsx
    main.tsx

前端使用：

React。
TypeScript。
Tailwind CSS。

默认模板通常会包含一些产品列表、产品行和基础组件，用来帮助开发者快速了解 Shop Mini 的运行方式。

初始化 Shop Mini 配置

运行 Shop Mini Setup

进入生成的 Shop Mini 目录，运行当前 Shopify CLI 提供的初始化命令：

npx shop-minis setup

这个命令会将 Shop Mini 连接到 Shopify Partner 组织，并创建本地配置文件。

配置文件中会包含 Shop Minis API Key。

不要把这个 Key 上传到公开代码仓库，也不要把它直接写入前端代码。

将 API Key 保存到 Gadget

复制 Shop Mini 初始化生成的 API Key。

回到 Gadget 项目的环境变量设置中，添加对应的 Secret 环境变量。

保存后，Gadget 后端就可以使用这个 API Key 调用 Shopify Admin API，验证 Shop Mini 发送过来的用户令牌。

配置 manifest.json

添加 OpenID Scope

打开 Shop Mini 的 manifest.json 文件。

在权限配置中添加：

openid

这个 Scope 用于支持 Shop Mini 的用户身份认证流程。

不要额外申请项目不需要的 Scope。每一个权限都应该与实际功能有关。

添加 Gadget Trusted Domain

Shop Mini 需要向 Gadget 后端发起请求，因此必须将 Gadget 应用域名加入可信域名配置。

配置内容通常包含：

{
  "trustedDomains": [
    "https://your-gadget-development-domain"
  ]
}

开发环境和生产环境使用不同的域名时，需要分别配置。

开发环境域名只用于开发测试，生产环境域名则用于正式发布。

具体字段名称和 JSON 结构，应以当前 Shop Mini 模板生成的 manifest.json 为准。

在 Shop Mini 中实现认证 Hook

创建 useAuth Hook

在 Shop Mini 中创建认证 Hook，例如：

src/hooks/useAuth.ts

这个 Hook 负责：

获取 Shopify 用户令牌。
检查本地是否已经保存 JWT。
判断 JWT 是否过期。
过期后重新获取令牌。
将 Shopify 用户令牌发送到 Gadget。
保存 Gadget 返回的 JWT。
为后续 GraphQL 请求提供有效 Token。

Shopify 的 Shop Mini React SDK 会提供生成用户令牌的 Hook。

同时，Shop Mini 可以使用 Secure Storage 保存 JWT，而不是把 Token 直接放在普通页面状态或不安全的存储位置。

获取 Shopify 用户令牌

认证流程首先调用 Shopify 提供的用户令牌方法：

const { generateUserToken } = useGenerateUserToken();

获得用户令牌后，将它发送到 Gadget 的认证路由。

请求头使用 Bearer Token：

headers: {
  Authorization: `Bearer ${shopifyUserToken}`
}

Shop Mini 不应该自己解析或信任这个令牌，令牌验证应当在 Gadget 后端完成。

保存 Gadget JWT

Gadget 验证 Shopify 用户令牌成功后，会返回一个 JWT 和过期信息：

{
  "token": "generated-jwt-token",
  "expiresIn": 3600
}

Shop Mini 将这个 JWT 保存到 Secure Storage，并在后续调用 Gadget API 时使用：

headers: {
  Authorization: `Bearer ${gadgetJwt}`
}

这样，Shop Mini 就可以在不重复验证每次用户身份的情况下，访问 Gadget 后端允许的功能。

在 Gadget 中创建认证路由

创建 Shop Mini Auth Route

模板会预先创建一个用于身份验证的 HTTP Route。

这个路由的作用是：

接收 Shop Mini 发送的 Shopify 用户令牌。
读取 Authorization 请求头。
提取 Bearer Token。
使用 Shop Minis Admin API Key 调用 Shopify Admin API。
验证用户令牌是否有效。
读取用户的公开 ID、状态和过期时间。
创建或更新 Gadget 中的 Mini Buyer。
创建或读取该用户的 Session。
为 Session 设置访问角色。
签发 Gadget JWT。
将 JWT 返回给 Shop Mini。

字幕中的路由名称类似于：

shop-mini-auth

具体路由名称以 Gadget 模板实际生成的代码为准。

使用 JSON Web Token 包

字幕中没有手动编写完整的 JWT 加密逻辑，而是使用 JSON Web Token npm 包完成：

JWT 签名。
JWT 验证。
JWT 过期时间设置。
JWT Payload 创建。

这样可以减少手写认证代码，降低令牌处理错误的风险。

验证 Shopify 用户令牌

Gadget 后端会使用 Shop Mini Admin API Key 调用 Shopify Admin API 验证用户令牌。

验证请求需要确认：

Token 是否有效。
用户是否存在。
用户是否有错误状态。
Token 是否已经过期。
返回的用户信息是否完整。

如果验证失败，路由应返回未授权响应：

401 Unauthorized

不要在验证失败时创建 Gadget 用户或 Session。

创建或更新 Mini Buyer

使用 Public ID 作为唯一标识

验证成功后，Shopify 会返回用户的公开 ID。

Gadget 可以使用这个 ID 查找 Mini Buyer：

如果 publicId 已存在，则更新记录。
如果 publicId 不存在，则创建记录。

可以使用 Gadget 自动生成的 Upsert 操作完成这个过程。

需要保存的信息包括：

publicId。
tokenExpiresAt。
state。
当前 Session ID。

这样，用户下次打开 Shop Mini 时，就可以继续使用已有的账户记录。

为什么需要 Upsert

Shop Mini 用户可能会多次打开应用，也可能因为 Token 过期而重新认证。

如果每次认证都创建一条新用户记录，数据库中就会出现大量重复数据。

Upsert 可以根据 publicId：

找到已有用户并更新。
找不到用户时创建新记录。

这使认证流程更加稳定。

创建 Gadget Session

检查已有 Session

找到 Mini Buyer 后，检查它是否已经关联一个有效 Session。

如果 Session 还存在并且有效，可以继续使用。

如果没有有效 Session，就创建新的 Session，并将它关联到当前 Mini Buyer。

设置 Shop Mini Buyer 角色

创建 Session 时，为它设置 Shop Mini Buyer 角色：

shop mini buyers

这个角色决定了 Shop Mini 用户可以访问哪些 Gadget 数据和操作。

例如，可以允许这个角色：

读取自己的用户信息。
创建自己的收藏记录。
读取自己的推荐结果。
更新自己的偏好设置。

不应该默认允许这个角色访问所有数据。

使用 Gadget Access Control

配置买家权限

在 Gadget Access Control 中，可以看到 Shop Mini Buyer 角色。

为这个角色授予必要权限。

例如，如果后续创建了一个名为 Recommendation 的数据模型，可以根据需要允许 Shop Mini Buyer：

Read。
Create。
Update。

如果某项功能不需要删除数据，就不要授予 Delete 权限。

实现多租户数据隔离

Gadget 的多租户隔离依赖于：

用户对应的 Session。
Session 对应的访问角色。
JWT 中保存的 Session ID。
Access Control 中的模型权限和过滤器。

每次 Shop Mini 请求 Gadget API 时，Gadget 会根据 JWT 识别当前 Session，并根据 Session 的角色判断请求是否被允许。

这意味着不同 Shop Mini 用户可以共用同一个后端，但每个用户只能访问自己的数据。

生成 Gadget JWT

设置 JWT Payload

Gadget 返回的 JWT 需要包含能够识别当前 Session 的信息。

Payload 通常包括：

Shopify 用户公开 ID。
用户状态。
Token 过期时间。
JWT 签发时间。
JWT 过期时间。
Gadget 应用域名。
当前 Gadget Session ID。

其中，当前 Session ID 是 Gadget 认证流程的关键。

Gadget 会通过这个 Session ID 将 JWT 和权限角色关联起来。

使用 Gadget 应用域名

JWT 的签发者或相关配置需要使用 Gadget 当前环境的主域名。

开发环境和生产环境应分别使用各自的域名配置。

不要把开发域名硬编码到生产版本中。

使用 JWT Signing Key

使用 Gadget 模板提供的 JWT Signing Key 对 Token 进行签名。

JWT Signing Key 只能在后端环境变量中使用。

签发完成后，把 JWT 返回给 Shop Mini：

{
  "token": "jwt-token",
  "expiresIn": 3600
}

Shop Mini 保存这个 Token，并将它用于后续请求。

从 Shop Mini 调用 Gadget GraphQL API

为什么使用原始 GraphQL

字幕中提到，Shop Mini 对 npm 包有严格限制。

虽然 Gadget 通常会自动生成 JavaScript API Client 和 React Hooks，但这些 Gadget 包当时还没有被 Shop Mini 的允许包列表正式支持。

因此，这个项目没有直接使用 Gadget JavaScript Client，而是使用：

原始 GraphQL 查询。
浏览器原生 fetch。
Bearer JWT。

Shop Mini 的可用包列表可能会随着 Shopify 审核流程发生变化。开发时应检查当前官方支持列表，不要默认所有 npm 包都可以使用。

获取 Gadget GraphQL Endpoint

Gadget 应用通常会为每个环境生成 GraphQL API 地址，例如：

https://your-gadget-domain/api/graphql

开发环境和生产环境的地址不同。

将 GraphQL 地址放在环境配置中，不要将不同环境的地址混在一起。

发送 GraphQL 请求

Shop Mini 使用 fetch 调用 Gadget GraphQL API：

const response = await fetch(GADGET_GRAPHQL_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${jwt}`
  },
  body: JSON.stringify({
    query,
    variables
  })
});

JWT 必须放在 Authorization 请求头中：

Authorization: Bearer <gadget-jwt>

Gadget 会自动验证 JWT，并根据 JWT 对应的 Session 和 Access Control 角色处理请求。

从 Gadget 文档复制 GraphQL 示例

Gadget 会为数据模型和操作提供 GraphQL 示例。

可以按照以下流程获取：

打开 Gadget 中的数据模型。
进入 API 或 Docs 页面。
选择需要调用的操作。
复制 GraphQL 查询或 Mutation。
根据 Shop Mini 的数据需求修改返回字段。
使用 fetch 发送请求。

不要在前端请求中返回不需要的数据。Shop Mini 运行在移动环境中，保持请求和响应简洁有助于提升速度。

在 Shop Mini 页面中显示用户信息

调用认证 Hook

在 App.tsx 中调用认证 Hook：

const { token, loading, error } = useAuth();

如果正在获取 Token，可以显示加载状态。

如果认证失败，可以显示简单的错误信息。

认证成功后，再调用 Gadget GraphQL API。

不要在没有 Token 的情况下调用需要登录权限的 Gadget API。

查询 Mini Buyer

Shop Mini 可以向 Gadget 发起一个 GraphQL 查询，读取当前用户的信息。

返回内容可以包括：

用户公开 ID。
当前 Session ID。
Token 过期时间。
用户状态。

测试时，可以先把用户 ID 显示在页面上：

<p>Buyer ID: {buyerId}</p>

这不是最终功能，只是为了确认认证请求已经成功。

正式应用中，应将这些信息用于：

加载个性化推荐。
保存用户偏好。
读取用户收藏。
记录用户使用历史。
返回个性化商品内容。

启动 Shop Mini 开发环境

不要只使用浏览器预览

Shop Mini 的认证功能必须在移动环境中测试。

字幕中尝试过直接使用 Chrome 开发工具，但浏览器预览只能提供模拟数据，不能完整验证真实身份认证流程。

如果要测试 Shopify 用户认证，应使用：

iOS Simulator。
Xcode。
Android Studio。
Android 模拟器。
Shopify 支持的移动调试工具。

浏览器预览适合检查基础界面，但不适合验证真实的 Shopify 用户令牌。

启动开发服务器

进入 Shop Mini 目录后运行：

npx shop-minis dev

启动后，根据提示选择移动测试环境。

如果使用 iOS，可以选择 Xcode 模拟器。

如果使用 Android，可以选择 Android Studio 和 Android 模拟器。

使用 Safari 调试 iOS 模拟器

如果使用 iOS Simulator，可以通过 Safari Web Inspector 调试 Shop Mini。

常见步骤包括：

启动 iOS Simulator。
启动 Shop Mini 开发服务。
打开 Safari。
打开 Develop 菜单。
选择 iOS Simulator。
打开对应的 localhost 页面。
查看 Console 和 Network 请求。

这样可以检查：

用户令牌是否成功生成。
Gadget JWT 是否成功返回。
GraphQL 请求是否带有 Bearer Token。
Gadget 后端是否返回正确数据。
页面是否因为权限错误而失败。

验证 Gadget 数据

完成一次认证后，返回 Gadget 后台检查数据库。

检查 Mini Buyer

在 Mini Buyer 数据模型中，确认已经出现新的记录。

检查：

publicId 是否存在。
tokenExpiresAt 是否正确。
state 是否保存。
Session 关系是否已经创建。

检查 Session

在 Session 数据模型中，确认已经创建对应 Session。

检查：

Session 是否关联正确的 Mini Buyer。
Session 是否使用 Shop Mini Buyer 角色。
Session 是否仍然有效。
Session ID 是否与 JWT 中的 Session ID 对应。

如果这些数据都存在，说明以下流程已经成功：

Shop Mini
→ Shopify 用户令牌
→ Gadget OAuth Route
→ Shopify Admin API 验证
→ Mini Buyer
→ Gadget Session
→ JWT
→ GraphQL API

常见问题与解决方法

只在浏览器里测试认证

浏览器预览可能使用模拟数据，不能代表真实 Shop App 用户认证。

解决方法是从一开始就使用 iOS Simulator 或 Android Simulator 测试认证。

忘记添加 OpenID Scope

如果 manifest.json 没有配置 OpenID Scope，用户令牌流程可能无法正常运行。

检查当前 Shopify Shop Mini 模板要求的 Scope，并只添加必要权限。

忘记配置 Trusted Domain

如果 Gadget 域名没有加入 Shop Mini 的可信域名列表，前端请求可能会被拒绝。

检查：

开发环境域名。
生产环境域名。
HTTPS 配置。
manifest.json 的字段格式。

把 API Key 放到前端

Shop Minis API Key 和 JWT Signing Key 都不能放到前端代码中。

正确方式是：

Shop Mini 只保存 Gadget 返回的 JWT。
Gadget 后端保存 Shopify API Key。
Gadget 后端保存 JWT Signing Key。
所有敏感验证都在后端完成。

直接使用未经批准的 npm 包

Shop Mini 的依赖包受到限制。

如果一个 npm 包没有出现在 Shopify 当前允许列表中，不要直接用于正式提交。必要时按照 Shopify 流程申请审核。

忘记配置 Access Control

即使 JWT 验证成功，如果 Session 没有正确配置角色，Gadget API 也可能拒绝请求。

检查：

Session 是否创建。
Session 是否关联 Mini Buyer。
Session 是否设置 Shop Mini Buyer 角色。
该角色是否拥有对应模型权限。
数据过滤条件是否正确。

发布前检查

检查 Shop Mini 审核要求

Shop Minis 需要经过 Shop 审核。

提交前应检查当前 Shopify 官方要求，包括：

Mini 名称。
品牌使用规则。
UI 设计规则。
用户隐私。
网络请求。
npm 包限制。
API 使用方式。
图片和内容规范。
性能要求。
用户数据处理方式。

字幕中提到的奖励活动和截止日期属于录制时的活动信息，不应直接当作当前政策。是否存在类似活动，应以 Shopify 当前官方页面为准。

检查生产环境配置

发布前确认：

生产 Gadget 域名已经配置。
生产 JWT Signing Key 已设置。
生产 Shop Mini Admin API Key 已设置。
生产 manifest.json 使用正确的域名。
开发环境 Token 没有写进生产配置。
所有敏感变量都存储在服务器端。
GraphQL API 使用正确的生产地址。

检查数据权限

确认 Shop Mini 用户只能读取自己的数据。

如果应用后续新增了：

收藏。
推荐记录。
搜索历史。
用户偏好。
上传图片。
AI 分析结果。

每个数据模型都需要单独配置权限和用户过滤条件。

这个认证模板可以扩展成什么

完成 Shop Mini 和 Gadget 的 JWT 认证后，可以继续开发很多功能。

个性化商品推荐

根据用户输入的偏好、历史操作或图片识别结果，调用 Shopify 商品数据并返回推荐。

图片识别与商品搜索

字幕中提到的后续方向是：

客户使用 Shop Mini 拍摄一张照片。
Shop Mini 将图片发送给 Gadget。
Gadget 将图片转换成 Base64。
Gadget 将图片和客户问题发送给 AI 服务。
AI 返回商品搜索关键词。
Gadget 使用 Shopify API 搜索匹配商品。
Shop Mini 展示推荐结果。

例如，客户可以上传自己的穿搭照片，并询问：

“什么鞋子适合这套衣服？”

后端可以将图片分析结果转换成商品搜索词，再通过 Shopify 商品 API 返回推荐结果。

用户收藏和偏好

可以创建新的 Gadget 数据模型，例如：

Favorite

并将它关联到：

Mini Buyer。
Shopify Product。
Shop Mini Session。

然后通过 Access Control 确保客户只能读取和修改自己的收藏。

AI 购物助手

Shop Mini 还可以接入 AI，为客户提供：

商品比较。
尺码建议。
风格推荐。
使用场景推荐。
购物清单生成。
相似商品搜索。

但涉及客户数据、图片和第三方 AI 服务时，应提前规划隐私政策、数据保存期限和删除机制。

总结

这份字幕实际演示的不是一个完整的商品推荐 Shop Mini，而是一套 Shop Mini + Gadget 自定义后端认证模板。

它的核心流程是：

Shop Mini 获取 Shopify 用户令牌
→ Gadget 验证用户令牌
→ 创建或更新 Mini Buyer
→ 创建 Gadget Session
→ 设置 Shop Mini Buyer 角色
→ 签发 Gadget JWT
→ Shop Mini 保存 JWT
→ 使用 JWT 调用 Gadget GraphQL API

技术栈包括：

Shopify Shop Minis。
React。
Tailwind CSS。
TypeScript。
Shopify Shop Mini SDK。
Shopify Admin API。
Gadget Node.js 后端。
PostgreSQL。
GraphQL。
JWT。
Session。
Access Control。
iOS Simulator 或 Android Studio。

它的最大价值是，开发者不需要从零搭建用户认证、数据库和权限系统，就可以先完成一个安全的 Shop Mini 后端基础，再继续开发商品推荐、图片识别、AI 搜索和个性化购物功能。

参考资料

citation:Shop Minis 客户体验

citation:Shop Minis 官方介绍

citation:Shopify Editions Spring 2026

文章目录