mcpField
L
laravel-best-practices

laravel-best-practices

github.com/paulofelipem开发1440 次安装30 周前更新
代码仓库

关于 laravel-best-practices

面向 Laravel 开发者和编码 Agent 的实践指南，包含 40 条按影响排序的规则，涵盖架构、安全、性能、测试和部署。各规则文件提供说明与代码示例，便于针对性实施或审查。

主要功能

  1. 0140 条优先级排序规则
  2. 02涵盖 10 个类别
  3. 03规则专属代码示例
  4. 04Laravel Boost 兼容说明

适用场景

  1. 01审查 Laravel 架构与安全
  2. 02重构控制器、服务或模型
  3. 03改善数据库与查询性能

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paulofelipem/agent-laravel-skills --skill laravel-best-practices

安装后在 Claude Code 中输入/laravel-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
metadata.json
README.md
AGENTS.md
rules/
_template.md
api-versioning.md
api-use-dto-serialization.md
api-use-interceptors.md
api-use-pipes.md
devops-graceful-shutdown.md
arch-use-repository-pattern.md
arch-avoid-circular-deps.md
arch-single-responsibility.md
db-use-migrations.md
devops-use-config-module.md
arch-use-events.md
db-use-transactions.md
arch-feature-modules.md
db-avoid-n-plus-one.md
devops-use-logging.md
di-avoid-service-locator.md
di-interface-segregation.md
error-handle-queue-errors.md
di-prefer-constructor-injection.md
di-use-interfaces-tokens.md
error-use-exception-handler.md
di-liskov-substitution.md
di-scope-awareness.md
error-throw-http-exceptions.md
micro-use-queues.md

详细介绍

Laravel 最佳实践

Laravel 应用的综合最佳实践指南。包含 10 个类别的 40 条规则，并按影响程度排序，以指导自动重构和代码生成。

适用场景

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

  • 编写新的 Laravel 控制器、服务或模型
  • 实现身份验证和授权
  • 审查代码中的架构和安全问题
  • 重构现有 Laravel 代码库
  • 优化性能或数据库查询
  • 构建微服务或基于队列的架构

按优先级划分的规则类别

优先级类别影响前缀
1架构CRITICALarch-
2依赖注入CRITICALdi-
3错误处理HIGHerror-
4安全HIGHsecurity-
5性能HIGHperf-
6测试MEDIUM-HIGHtest-
7数据库与 ORMMEDIUM-HIGHdb-
8API 设计MEDIUMapi-
9微服务MEDIUMmicro-
10DevOps 与部署LOW-MEDIUMdevops-

快速参考

1. 架构（CRITICAL）
  • arch-avoid-circular-deps - 避免服务提供者之间的循环依赖
  • arch-feature-modules - 按领域/功能组织，而非按技术层组织
  • arch-single-responsibility - 使用职责明确的服务，避免“万能服务”
  • arch-use-repository-pattern - 抽象数据库逻辑，便于测试
  • arch-use-events - 使用事件驱动架构实现解耦
2. 依赖注入（CRITICAL）
  • di-avoid-service-locator - 避免将 app() 辅助函数用作服务定位器
  • di-interface-segregation - 接口隔离原则（ISP）
  • di-liskov-substitution - 里氏替换原则（LSP）
  • di-prefer-constructor-injection - 优先使用构造函数注入，而非门面/辅助函数注入
  • di-scope-awareness - 理解 singleton/bind/scoped 绑定
  • di-use-interfaces-tokens - 将接口绑定到实现
3. 错误处理（HIGH）
  • error-use-exception-handler - 集中处理异常
  • error-throw-http-exceptions - 使用恰当的 HTTP 异常
  • error-handle-queue-errors - 正确处理队列和作业错误
4. 安全（HIGH）
  • security-auth-jwt - 使用 Sanctum/Passport 进行安全身份验证
  • security-validate-all-input - 使用 Form Requests 验证输入
  • security-use-guards - 使用身份验证守卫、门和策略
  • security-sanitize-output - 防止 XSS 攻击
  • security-rate-limiting - 实施速率限制
5. 性能（HIGH）
  • perf-service-provider-lifecycle - 正确处理服务提供者的 boot/register 生命周期
  • perf-use-caching - 实施缓存策略
  • perf-optimize-database - 优化数据库查询
  • perf-lazy-loading - 使用延迟集合和路由缓存
6. 测试（MEDIUM-HIGH）
  • test-use-testcase-refresh-database - 使用 Laravel TestCase 和 RefreshDatabase
  • test-e2e-http - 使用 Laravel 进行 HTTP/功能测试
  • test-mock-external-services - 使用门面模拟外部依赖
7. 数据库与 ORM（MEDIUM-HIGH）
  • db-use-transactions - 管理事务
  • db-avoid-n-plus-one - 使用预加载避免 N+1 查询问题
  • db-use-migrations - 使用迁移修改架构
8. API 设计（MEDIUM）
  • api-use-dto-serialization - 使用 API Resources 和序列化
  • api-use-interceptors - 使用中间件处理横切关注点
  • api-versioning - 制定 API 版本控制策略
  • api-use-pipes - 使用 Form Requests 转换输入
9. 微服务（MEDIUM）
  • micro-use-patterns - 使用消息和事件模式
  • micro-use-health-checks - 为编排提供健康检查
  • micro-use-queues - 使用队列处理后台作业
10. DevOps 与部署（LOW-MEDIUM）
  • devops-use-config-module - 使用 config() 配置环境
  • devops-use-logging - 使用通道进行结构化日志记录
  • devops-graceful-shutdown - 实现零停机部署

使用方法

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

rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md

每个规则文件都包含：

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

仅在需要了解特定规则的完整实现细节时，才阅读 AGENTS.md 或单个 rules/*.md 文件。不要预先加载这些文件。

完整汇编文档

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

Laravel Boost 兼容性

如果已安装 Laravel Boost，其核心指南已涵盖以下规则，可跳过：

security-validate-all-input、security-auth-jwt、db-avoid-n-plus-one、 db-use-migrations、perf-use-caching、test-use-testcase-refresh-database、 devops-use-logging、api-versioning

评论

支持 Markdown