custom-development-guide

name	custom-development-guide
description	高级定制开发指南 - 主题定制、App开发、Liquid模板、Storefront API、性能优化、代码审查
version	1.0.0
author	Shopilot
argument-hint	<feature-type> [complexity]
disable-model-invocation	false
user-invocable	true

Custom Development Guide 💻

释放Shopify定制开发潜力，构建独特电商体验

高级定制开发指南为开发者提供完整的Shopify定制开发知识体系，从主题定制到App开发，从Liquid模板到API集成，打造专业的开发能力。

---

🎯 核心功能

1. 主题定制最佳实践

架构设计:
  主题结构:
    ├── layout/          # 布局模板
    ├── templates/       # 页面模板
    ├── sections/        # 可配置区块
    ├── snippets/        # 可复用片段
    ├── assets/          # 静态资源
    ├── config/          # 配置文件
    └── locales/         # 语言文件

  设计系统:
    颜色系统:
      - 主色: [品牌主色]
      - 辅助色: [辅助色彩]
      - 中性色: [灰度系统]
      - 语义色: [成功/警告/错误]

    排版系统:
      - 字体家族: [字体栈]
      - 字号层级: [h1-h6/body]
      - 行高系统: [层级关系]
      - 字重系统: [粗细层级]

    间距系统:
      - 基础单位: [基准值]
      - 间距层级: [spacing scale]
      - 布局网格: [grid system]
      - 响应式断点: [breakpoints]

  性能优化:
    资源优化:
      - 图片懒加载: [Lazy loading]
      - 代码分割: [Code splitting]
      - 资源压缩: [Minification]
      - CDN加速: [CDN delivery]

    渲染优化:
      - 关键CSS: [Critical CSS]
      - 预加载: [Preloading]
      - 预连接: [Preconnecting]
      - 首屏优化: [Above the fold]

2. App开发指南

开发流程:
  项目初始化:
    - Shopify CLI: [shopify app init]
    - 技术栈选择: [Node.js/Remix/React]
    - 数据库设计: [Prisma/SQLite/PostgreSQL]
    - 认证配置: [API Key/Secret]

  核心功能:
    API集成:
      - Admin API: [后台管理]
      - Storefront API: [前台数据]
      - GraphQL: [查询接口]
      - REST Admin: [传统接口]

    Webhook处理:
      - 订单事件: [orders/create]
      - 客户事件: [customers/create]
      - 产品事件: [products/update]
      - 退款事件: [refunds/create]

    数据同步:
      - 定时同步: [Cron jobs]
      - 实时同步: [Webhooks]
      - 增量同步: [Polling]
      - 批量处理: [Bulk operations]

  发布流程:
    测试:
      - 本地测试: [Local development]
      - 店铺测试: [Test store]
      - 功能测试: [Feature testing]
      - 性能测试: [Performance testing]

    提交:
      - 代码审查: [Code review]
      - 安全扫描: [Security scan]
      - 合规检查: [Compliance check]
      - 文档完善: [Documentation]

    发布:
      - App Store: [Public listing]
      - 自定义App: [Custom app]
      - 版本管理: [Version control]
      - 更新策略: [Update strategy]

3. Liquid模板开发

Liquid语法:
  基础语法:
    输出: {{ variable }}
    标签: {% tag %}
    注释: {% comment %} ... {% endcomment %}
    过滤器: {{ variable | filter }}

  对象访问:
    产品对象: product
      - product.title
      - product.description
      - product.price
      - product.images
      - product.variants

    订单对象: order
      - order.name
      - order.customer
      - order.line_items
      - order.total_price

    客户对象: customer
      - customer.first_name
      - customer.email
      - customer.orders
      - customer.addresses

  控制结构:
    条件判断:
      {% if condition %}
      {% elsif condition %}
      {% else %}
      {% endif %}

    循环:
      {% for item in array %}
      {% endfor %}

    Case语句:
      {% case variable %}
      {% when value %}
      {% else %}
      {% endcase %}

  高级特性:
    - 模板继承: [{% layout %}]
    - 包含片段: [{% render %}]
    - 表单生成: [{% form %}]
    - 条件渲染: [{% if %}]

4. Storefront API使用

API架构:
  认证方式:
    - Storefront API Token: [公共访问]
    - Customer Access Token: [客户认证]
    - Multipass: [SSO集成]

  核心查询:
    产品查询:
      query {
        product(handle: "product-handle") {
          id
          title
          description
          priceRange {
            minVariantPrice {
              amount
            }
          }
          images(first: 10) {
            edges {
              node {
                src
              }
            }
          }
          variants(first: 10) {
            edges {
              node {
                id
                price {
                  amount
                }
              }
            }
          }
        }
      }

    购物车查询:
      query {
        cart {
          id
          createdAt
          lines(first: 10) {
            edges {
              node {
                quantity
                merchandise {
                  ... on ProductVariant {
                    id
                    price {
                      amount
                    }
                  }
                }
              }
            }
          }
          cost {
            totalAmount {
              amount
            }
          }
        }
      }

    变更操作:
      - cartCreate: [创建购物车]
      - cartLinesAdd: [添加商品]
      - cartLinesUpdate: [更新数量]
      - cartLinesRemove: [删除商品]
      - cartDiscountCodesUpdate: [应用折扣]

  最佳实践:
    - 查询优化: [按需获取字段]
    - 缓存策略: [减少请求]
    - 错误处理: [优雅降级]
    - 性能监控: [请求跟踪]

5. 性能优化

优化策略:
  前端优化:
    资源加载:
      - 图片优化: [WebP/AVIF]
      - 字体优化: [Subset/Preload]
      - CSS优化: [Critical Path]
      - JS优化: [Tree Shaking]

    渲染性能:
      - 虚拟滚动: [长列表]
      - 懒加载: [图片/组件]
      - 防抖节流: [事件处理]
      - 代码分割: [Route Splitting]

  后端优化:
    数据查询:
      - 索引优化: [查询加速]
      - 批量查询: [减少请求]
      - 缓存策略: [Redis/CDN]
      - 查询优化: [N+1问题]

    API性能:
      - 批量操作: [Bulk API]
      - 并发处理: [Async operations]
      - 连接池: [Connection pooling]
      - 超时控制: [Timeout handling]

  监控指标:
    核心指标:
      - LCP: [最大内容绘制]
      - FID: [首次输入延迟]
      - CLS: [累积布局偏移]
      - TTI: [可交互时间]

    工具:
      - Lighthouse: [性能评分]
      - WebPageTest: [详细分析]
      - Chrome DevTools: [实时监控]
      - Shopify Analyzer: [平台分析]

6. 代码审查清单

审查要点:
  代码质量:
    可读性:
      - 命名规范: [清晰易懂]
      - 代码格式: [统一风格]
      - 注释文档: [必要说明]
      - 结构清晰: [逻辑分明]

    可维护性:
      - 模块化: [高内聚低耦合]
      - 可复用: [DRY原则]
      - 可扩展: [易于修改]
      - 可测试: [单元测试]

  安全检查:
    数据安全:
      - 输入验证: [防止注入]
      - 输出转义: [防止XSS]
      - 敏感数据: [加密存储]
      - 访问控制: [权限验证]

    API安全:
      - 认证授权: [Token验证]
      - 速率限制: [防滥用]
      - 数据过滤: [最小权限]
      - 日志审计: [操作追踪]

  性能审查:
    - 查询效率: [避免N+1]
    - 缓存使用: [合理缓存]
    - 资源加载: [按需加载]
    - 内存管理: [避免泄漏]

  最佳实践:
    Shopify规范:
      - 主题规范: [Theme guidelines]
      - API规范: [API best practices]
      - 安全规范: [Security guidelines]
      - 性能规范: [Performance guidelines]

    行业标准:
      - 代码规范: [ESLint/Prettier]
      - Git规范: [Commit conventions]
      - 测试覆盖: [Test coverage]
      - 文档完整: [API docs]

---

🛠️ 开发工具

必备工具

CLI工具:
  Shopify CLI:
    安装: npm install -g @shopify/cli
    功能:
      - 项目初始化
      - 本地开发
      - 主题部署
      - App开发

  Theme Kit:
    安装: brew tap shopify/shopify && brew install themekit
    功能:
      - 主题上传
      - 文件监听
      - 多环境部署
      - 版本管理

开发环境:
  代码编辑:
    - VS Code: [推荐]
    - WebStorm: [专业]
    - Sublime: [轻量]

  浏览器工具:
    - Chrome DevTools: [调试]
    - React DevTools: [React]
    - Shopify Theme Inspector: [主题]

  版本控制:
    - Git: [版本控制]
    - GitHub: [代码托管]
    - GitLab: [CI/CD]

测试工具:
  单元测试:
    - Jest: [JavaScript测试]
    - Vitest: [Vite测试]
    - Mocha: [Node.js测试]

  E2E测试:
    - Cypress: [E2E测试]
    - Playwright: [现代E2E]
    - Puppeteer: [浏览器自动化]

---

📚 学习路径

初级阶段

1. Liquid基础 (1-2周)
   ├─ 语法基础
   ├─ 对象和过滤器
   ├─ 模板结构
   └─ 简单定制

2. 主题定制 (2-3周)
   ├─ 主题结构
   ├─ Section开发
   ├─ 主题设置
   └─ 样式定制

3. Storefront API (2-3周)
   ├─ GraphQL基础
   ├─ 常用查询
   ├─ 购物车功能
   └─ 产品展示

中级阶段

1. App开发 (4-6周)
   ├─ 项目搭建
   ├─ Admin API
   ├─ Webhook处理
   └─ 数据存储

2. 高级Liquid (3-4周)
   ├─ 复杂逻辑
   ├─ 性能优化
   ├─ 模板继承
   └─ 自定义过滤器

3. 集成开发 (4-5周)
   ├─ 第三方API
   ├─ 支付集成
   ├─ 物流集成
   └─ 营销工具

高级阶段

1. 架构设计 (4-6周)
   ├─ 系统架构
   ├─ 数据建模
   ├─ 性能架构
   └─ 安全架构

2. 性能优化 (3-4周)
   ├─ 前端优化
   ├─ 后端优化
   ├─ 缓存策略
   └─ 监控体系

3. 工程化 (4-5周)
   ├─ CI/CD
   ├─ 测试体系
   ├─ 代码质量
   └─ 团队协作

---

🎨 使用场景

场景1: 自定义主题开发

需求: 开发品牌定制主题

步骤:
1. 设计系统建立
2. 主题架构设计
3. Component开发
4. 页面模板开发
5. 响应式适配
6. 性能优化
7. 测试和上线

场景2: 功能App开发

需求: 开发业务功能App

步骤:
1. 需求分析
2. 技术选型
3. API设计
4. 功能开发
5. 集成测试
6. 发布部署

场景3: 性能优化项目

需求: 提升网站性能

步骤:
1. 性能分析
2. 瓶颈识别
3. 优化方案
4. 实施优化
5. 效果验证
6. 持续监控

场景4: 第三方集成

需求: 集成第三方服务

步骤:
1. 集成方案设计
2. API对接
3. 数据同步
4. 错误处理
5. 测试验证
6. 上线监控

---

🔗 相关 Skills

• /prime-page-builder - 落地页生成器
• /checkout-optimizer - 结账流程优化
• /prime-product-desc - 产品描述创作
• /social-proof-builder - 社交证明构建
• /personalized-recommendation - 个性化推荐

---

📊 成功指标

开发效率

• 开发速度提升 > 50%
• 代码复用率 > 60%
• Bug修复时间缩短 > 40%

代码质量

• 代码测试覆盖率 > 80%
• 代码审查通过率 > 95%
• 安全漏洞 = 0

性能表现

• 页面加载速度 < 2秒
• Lighthouse分数 > 90
• Core Web Vitals通过率 = 100%

---

Code with confidence, build with excellence! 💻

版本: 1.0.0 更新: 2026-04-12 作者: Shopilot Team