gadget-best-practices

使用方法

此技能提供使用 Gadget 进行开发的快速参考模式和最佳实践。

📖 资源：

• 完整文档：docs.gadget.dev

阅读各个规则文件，了解详细说明和代码示例：

核心数据建模

• references/models.md - 数据模型设计模式和命名约定
• references/fields.md - 字段类型、验证和配置
• references/relationships.md - 关系模式（belongsTo、hasMany、hasManyThrough）
• references/data-access.md - 计算视图和计算字段（Gelly 聚合、分组、时间序列、访问控制）

后端逻辑

• references/actions.md - 模型操作与全局操作、钩子和模式
• references/routes.md - HTTP 路由及何时使用路由而非操作
• references/background-jobs.md - 入队操作和计划任务

访问控制与安全

• references/access-control.md - RBAC、权限筛选器和 Gelly 表达式
• references/shopify-multi-tenancy.md - Shopify 应用的店铺隔离模式

平台集成

• references/shopify-integration.md - Shopify 应用模式（webhook、同步触发器、metafield）
• references/bigcommerce-integration.md - BigCommerce 应用模式
• references/webhooks.md - Webhook 处理模式

前端开发

• references/frontend-hooks.md - 来自 @gadgetinc/react 的 React 钩子
• references/frontend-components.md - 自动组件和 UI 模式
• references/frontend-forms.md - 表单处理和验证

开发工作流

• references/ggt-cli.md - 标准 ggt 工作流（同步、检查、日志、环境、冲突处理、并行 worktree）
• references/testing.md - 与框架无关的测试设置、场景和 CI 门禁
• references/deployment.md - 部署工作流和环境
• references/environments.md - 环境变量和多环境策略
• references/project-structure.md - 文件组织和约定

API 与身份验证

• references/api-client.md - 使用 Gadget API 客户端（筛选、分页、关系）
• references/internal-api.md - 内部 API 用法、原子更新、事务安全写入以及管理员／会话上下文
• references/authentication.md - 用户身份验证模式
• references/error-codes.md - 常见 Gadget API 错误代码、可能原因和问题排查工作流