shopware6-best-practices

Shopware 6 最佳实践

面向 Shopware 6.6+ 开发的全面最佳实践指南，专为协助代理开发人员的 AI Agent 和大模型设计。包含 22 个类别中的 77 条规则，按影响程度排序，为自动重构和代码生成提供指导。

适用场景

在以下情况下参考这些指南：

• 开发自定义 Shopware 6 插件
• 创建或修改 Store API 或 Admin API 端点
• 使用数据抽象层（DAL）
• 实现事件订阅者和装饰器
• 配置消息队列处理程序
• 编写数据库迁移
• 优化性能（缓存、Elasticsearch）
• 实施安全措施
• 编写单元测试和集成测试
• 自定义店面模板和 JavaScript
• 构建管理模块和组件
• 创建包含 webhook 和操作的 Shopware 应用
• 实现支付或配送集成
• 构建 CMS 元素和区块
• 创建用于自动化的 CLI 命令
• 设置多渠道或 B2B 商店
• 配置开发环境和 CI/CD

按优先级划分的规则类别

优先级	类别	影响	前缀
1	插件架构	严重	plugin-
2	自定义与扩展	严重	custom-
3	性能与缓存	严重	perf-
4	安全	严重	security-
5	数据抽象层	高	dal-
6	API 开发	高	api-
7	测试	高	test-
8	事件系统	中高	event-
9	数据库与迁移	中高	db-
10	消息队列	中	queue-
11	依赖注入	中	di-
12	日志记录	中	logging-
13	配置	中	config-
14	计划任务	中	scheduled-
15	店面开发	高	storefront-
16	管理界面开发	高	admin-
17	应用系统	高	app-
18	集成模式	高	integration-
19	CLI 命令	中	cli-
20	多渠道与 B2B	中高	multichannel-
21	DevOps 与工具	中	devops-
22	常见模式	高	pattern-

快速参考

1. 插件架构（严重）

• plugin-structure - 遵循正确的插件目录结构和 composer.json
• plugin-services - 使用适当的标签正确注册服务

2. 自定义与扩展（严重）

• custom-decorator-pattern - 使用装饰器模式，以确保服务自定义在升级后仍然安全
• custom-event-subscribers - 使用适当的优先级正确实现事件订阅者

3. 性能与缓存（严重）

• perf-http-cache - 正确配置 HTTP 缓存及其失效机制
• perf-dal-optimization - 优化 DAL 查询，避免 N+1 问题
• perf-elasticsearch - 在大型目录中正确使用 Elasticsearch

4. 安全（严重）

• security-input-validation - 使用 RequestDataBag 和验证器验证所有输入
• security-authentication - 正确实现路由身份验证
• security-authorization - 使用 ACL 检查权限
• security-csrf-protection - 为店面实现 CSRF 保护
• security-sql-injection - 使用 DAL 或参数化查询

5. 数据抽象层（高）

• dal-criteria-usage - 正确使用 Criteria 对象及筛选器和分页
• dal-associations - 显式加载关联，避免 N+1 查询
• dal-write-operations - 使用批量操作和正确的同步模式
• dal-entity-extensions - 扩展实体，而不修改核心代码
• dal-custom-entities - 正确创建自定义实体定义

6. API 开发（高）

• api-store-api-routes - 创建可装饰的 Store API 路由
• api-admin-api-routes - 创建具备适当 ACL 的 Admin API 端点
• api-response-handling - 以一致的方式处理响应和错误
• api-rate-limiting - 配置速率限制以提供保护
• api-versioning - 为 API 添加版本，以保持向后兼容

7. 测试（高）

• test-unit-tests - 使用适当的模拟编写单元测试
• test-integration-tests - 正确使用 IntegrationTestBehaviour
• test-store-api-tests - 使用 HTTP 测试测试 Store API 路由
• test-fixtures - 创建可复用的测试固件

8. 事件系统（中高）

• event-business-events - 创建与 Flow Builder 兼容的事件
• event-flow-actions - 实现可配置的工作流操作

9. 数据库与迁移（中高）

• db-migrations - 实施安全的数据库迁移

10. 消息队列（中）

• queue-message-handlers - 实现异步消息处理
• queue-worker-config - 为生产环境配置工作进程
• queue-low-priority - 将低优先级后台任务分开处理

11. 依赖注入（中）

• di-service-container - 正确使用 Symfony DI

12. 日志记录（中）

• logging-best-practices - 实施结构化日志记录

13. 配置（中）

• config-plugin-settings - 正确实现插件配置

14. 定时任务（中）

• scheduled-tasks - 实现可靠的定时任务

15. 店面开发（高）

• storefront-controller-pattern - 使用页面加载器扩展 StorefrontController
• storefront-twig-extension - 使用 sw_extends 和区块实现模板继承
• storefront-js-plugins - JavaScript 插件注册与生命周期
• storefront-themes - 主题结构、继承与配置
• storefront-scss-variables - SCSS 变量与响应式混合宏
• storefront-http-client - 从 JS 发起 AJAX 请求和 Store API 调用

16. 管理后台开发（高）

• admin-module-structure - 模块注册、路由与导航
• admin-components - Vue 组件模式与模板
• admin-data-handling - 在管理后台使用 Repository 工厂和 Criteria API
• admin-acl-permissions - 基于 ACL 控制 UI 可见性和操作
• admin-mixins-composables - 混入、指令与可扩展性
• admin-extension-api - 应用 iframe 模块与 Extension SDK

17. 应用系统（高）

• app-manifest - 完整的 manifest.xml 配置
• app-webhooks - Webhook 处理与签名验证
• app-custom-actions - 带通知、模态框和重定向的操作按钮
• app-payment-methods - 用于支付、完成、捕获和退款的应用支付处理器
• app-custom-fields - 通过 manifest 定义自定义字段
• app-scripts - 基于 Twig 的应用脚本与钩子点

18. 集成模式（高）

• integration-payment-handler - 同步/异步支付处理器模式
• integration-shipping-method - 配送计算器与配送时间
• integration-cms-elements - 使用数据解析器创建 CMS 元素
• integration-import-export - 导入/导出配置文件与转换器
• integration-external-api - 支持重试与缓存的 HTTP 客户端模式

19. CLI 命令（中）

• cli-commands - 创建带参数和选项的自定义命令
• cli-command-lifecycle - 配置/初始化/交互/执行生命周期
• cli-progress-output - SymfonyStyle、进度条与格式化

20. 多渠道与 B2B（中高）

• multichannel-saleschannel - 销售渠道感知与可见性
• multichannel-b2b-patterns - 公司处理、角色与预算
• multichannel-pricing - 货币、客户群组与税费处理
• multichannel-context - 上下文类型、作用域与权限

21. DevOps 与工具链（中等）

• devops-development-setup - Dockware、docker-compose、Makefile 模式
• devops-deployment - 部署脚本、构建和回滚
• devops-static-analysis - PHPStan、PHP-CS-Fixer、Rector 配置
• devops-debugging - Profiler、Xdebug、日志记录和数据收集器
• devops-ci-cd - GitHub Actions 和 GitLab CI 工作流

22. 常见模式（高）

• pattern-error-handling - 自定义异常和错误页面
• pattern-translations - 代码片段和实体翻译
• pattern-media-handling - 媒体服务、上传和缩略图
• pattern-rule-builder - 用于定价/配送的自定义规则条件
• pattern-upgrade-migration - 感知版本的代码和更新迁移

核心原则

装饰器模式是关键

切勿修改核心文件。始终使用：

• 装饰器用于服务
• 事件订阅器用于钩子
• 实体扩展用于数据

使用 DAL，而非原始 SQL

使用 Shopware 的数据抽象层，而非原始 SQL：

• 类型安全和验证
• 自动处理关联
• 内置版本控制和翻译

性能优先

如果使用不当，Shopware 可能会变慢：

• 在生产环境中启用 HTTP 缓存
• 对 1 万以上的商品使用 Elasticsearch
• 仅加载所需的关联
• 使用消息队列处理繁重任务

使用方法

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

rules/plugin-structure.md
rules/custom-decorator-pattern.md
rules/perf-http-cache.md
rules/security-input-validation.md
rules/dal-criteria-usage.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 其他背景信息和参考资料

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md