Shopify API 分页的 URL 编码问题详解：常见原因、排查路径与解决方案
常见原因与表现
在 Shopify 的分页机制中，REST API 使用 page_info 作为游标参数，与 limit 一起构成分页请求的关键部分。如果 page_info 的 URL 编码不正确，服务器端会无法正确解析这段游标，导致分页失败或无法获取下一页数据。
常见表现包括收到 400 Bad Request、414 Request-URI Too Long、或返回的结果缺失下一页链接。这类问题往往与编码相关，而非权限或版本错乱。
需要特别关注的是 page_info 字符串可能包含 +、/、= 等需要编码的字符，如果直接拼接到 URL 中，可能被浏览器或中间件错误解释，导致请求被截断或参数被错误解码。
排查路径与步骤
第一步，抓取并记录请求中未编码的原始 URL，以及来自 Link 头部的下一页 URL。原始链接是定位编码问题的关键证据。
第二步，确认你在代码中如何构建查询字符串。若使用手动拼接，请转向语言自带的编码工具，避免未编码或错误编码的行为。不要两次编码或错配编码规则。
第三步，使用一次性复现实验来验证编码效果，例如在 curl 中直接使用完整的下一页链接，观察 Shopify 是否返回正确的分页数据。断点测试有助于排除客户端代码的干扰。
# 使用 urllib.parse 来构建带有 page_info 的请求 URL
import urllib.parse
base = "https://{shop}.myshopify.com/admin/api/2024-01/products.json"
page_info = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # 示例游标
params = {"limit": 50, "page_info": page_info}
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
url = f"{base}?{query}"
print(url) # 真实环境中请直接请求该 url
解决方案与最佳实践
最佳做法是全程使用语言原生的 URL 编码/构造工具，避免手动拼接造成的编码错乱。
在 JavaScript 环境中，推荐使用 URL、URLSearchParams 或者 fetch 的自动编码能力来构造请求，这样可以确保 page_info 的编码正确且一致。
与 REST API 的分页不同，GraphQL 的游标分页需要关注 after/ pageInfo 的编码，但核心原则同样是正确编码与避免错误拼接。理解两种分页的差异有助于避免错误。
// 使用 URL 对象和 URLSearchParams 构造带 page_info 的请求
const shop = "your-shop.myshopify.com";
const pageInfo = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // 示例
const url = new URL(`https://${shop}/admin/api/2024-01/products.json`);
url.searchParams.set("limit", "50");
url.searchParams.set("page_info", pageInfo);fetch(url.toString(), {headers: { "X-Shopify-Access-Token": "your-access-token" }
}).then(res => res.json()).then(console.log);
import urllib.parse
base = "https://{shop}.myshopify.com/admin/api/2024-01/products.json"
page_info = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...="params = {"limit": 50, "page_info": page_info}
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
url = base.format(shop="your-shop") + "?" + queryprint(url) # 直接用 curl --url "$url" 进行复现实验
关于 REST 与 GraphQL 的分页差异，核心原则仍然是正确编码与避免拼接错误。不同的分页参数名称和含义需要留意，但不要忽视编码问题本身。
