Shopify App 开发完整流程

Shopify 生态适合做可复制的 SaaS：有清晰的授权模型、Webhook 事件和应用市场分发渠道。我们做过订单同步、库存管理和 AI 商品文案三类 App，共性是主链路一致，差异在领域建模和稳定性打磨。很多团队卡在 OAuth 通了但 Webhook 脏数据、或上架后第一个大促就超卖——根因通常是多租户和幂等没做扎实。Partner 文档很全，但生产级应用还要自己补对账、限流和租户隔离。

主链路：从 Partner 到上架

Partner 后台创建应用，配置 App URL 和 Redirect URL。商家安装时走 OAuth 2.0，用 shop 参数换 access token，加密存入 PostgreSQL，按 shop domain 隔离。业务调用 Admin API 读订单、写库存；需要前端嵌入时用 App Bridge 和 Polaris 保持体验一致。Webhook 订阅 orders/create、inventory_levels/update 等 topic，Handler 验签、幂等、异步入队。计费接入 Shopify Billing API，应用商店物料准备截图、隐私政策和测试账号。app/uninstalled 事件要监听，及时停任务并清理租户数据。上架审核会测 OAuth 流程和 GDPR webhook，缺一项就会打回。

架构要点：店铺即租户

每个 shop domain 对应独立凭证、配置和数据分区。Webhook 必须验签、去重、对账，否则订单库存同步会脏。队列 Worker 带 shop 上下文，重试不串店。本地开发用 ngrok 或 Cloudflare Tunnel 暴露 HTTPS，Partner 后台填对应 URL。Token 过期和 scope 变更要有刷新或重装引导。PostgreSQL 存 webhook_events 和 sync_cursor，支撑增量 API 拉取和对账补洞。Admin API 有速率限制，Bulk Operation 适合大批量商品同步，实时场景才走 GraphQL 分页。多店铺共用一套 Worker 池时，按 shop 公平调度，防止大单店占满队列。

产品建议：先打穿一个场景

不要第一天就做全能 ERP。先选高频痛点，例如多仓库存同步或跨平台订单汇总，做到稳定、可观测、售后响应快，再扩展模块。Shopify 应用的胜负往往在 Webhook 可靠性和对账完整性，而不只是功能列表长度。AI 功能接在后端异步队列，按店铺控额度，避免 Demo 好看、账单失控。把 PostgreSQL 当真相源，把平台 API 当补充，是长期可维护的起点。售后文档写清「平台延迟时系统如何对账」，比功能宣传更能减少 churn。OAuth 阶段注意 offline access token 的存储加密和 rotation；Webhook 阶段注意五秒内 ACK；上架阶段准备可复现的测试店铺和数据。我们推荐的里程碑是：第一周打通安装和单 topic Webhook，第二周完成幂等与 PostgreSQL 落库，第三周上线对账和基础报表，第四周才加 AI 或高级功能。顺序反过来，往往要在生产环境补课，成本翻倍。Billing 接入前算清「单店毛利」，Webhook 和对账的运维成本也要摊进定价。Polaris 组件保持与 Admin 一致，减少商家学习成本；错误页写清「去 Shopify 后台核对」的链接，比笼统的 500 更能建立信任。Shopify App 本质是 SaaS 产品，技术主链路只是起点，稳定交付才是复购理由。Partner Dashboard 里的 API 健康度和错误日志要每日扫一眼，429 和 401 往往是 token 或限流问题的最早信号，早发现比大促当天救火省力十倍。从 Partner 创建到首次安装成功，尽量控制在半天内可演示；商家耐心很短，OAuth 报错一次就可能卸载。把 PostgreSQL schema 设计、Webhook 订阅和 Billing 开关写成 checklist，每次上新店走一遍，踩坑会少很多。Review 阶段重点看三点：token 是否按 shop 加密存储、Webhook 是否五秒内 ACK、卸载事件是否清理租户数据——Shopify 审核和真实商家都会测这三项。做到这些，App 才算跨过「能跑」到「能卖」的门槛。

小结

Shopify App 的长期成本往往不在首屏功能，而在权限范围、Webhook 可靠性与版本升级路径。把安装、授权、卸载与数据清理写成标准清单，能显著减少后期客服与合规风险。建议每个重大能力上线前都走一遍「新店安装到首单同步」的全链路验收。

实践中把上述清单变成可勾选的发布门禁，比事后补救更省时间。