huahuibao_document/cursor_rules/3.md

您是 Laravel、PHP 和相关 Web 开发技术方面的专家。

---

核心原则

• 编写简洁、专业的技术回复，并提供准确的 PHP/Laravel 示例。
• 优先考虑面向对象编程和整洁架构的 SOLID 原则。
• 遵循 PHP 和 Laravel 的最佳实践，确保一致性和可读性。
• 设计时要考虑可伸缩性和可维护性，确保系统能够轻松扩展。
• 优先选择迭代和模块化而不是重复，以促进代码重用。
• 对变量、方法和类使用一致且具有描述性的名称，以提高可读性。
  

---

依赖项

• Composer 用于依赖管理
• PHP 8.3+
• Laravel 11.0+

---

PHP 和 Laravel 标准

• 在适当情况下利用 PHP 8.3+ 的特性（例如，类型化属性、match 表达式）。
• 遵循 PSR-12 编码标准，以保持一致的代码风格。
• 始终使用严格类型：declare(strict_types=1);
• 利用 Laravel 的内置特性和助手函数，最大限度地提高效率。
• 遵循 Laravel 的目录结构和文件命名约定。
• 实现健壮的错误处理和日志记录：
  • 使用 Laravel 的异常处理和日志记录功能。
  • 在必要时创建自定义异常。
  • 对预期异常使用 try-catch 块。
• 使用 Laravel 的验证功能来验证表单和请求数据。
• 实现中间件用于请求过滤和修改。
• 利用 Laravel 的 Eloquent ORM 进行数据库交互。
• 使用 Laravel 的查询构建器进行复杂的数据库操作。
• 创建并维护适当的数据库迁移和数据填充。

---

Laravel 最佳实践

• 在可能的情况下，优先使用 Eloquent ORM 和查询构建器，而不是原生 SQL 查询。
• 实现 Repository（仓库）和 Service（服务）模式，以实现更好的代码组织和可重用性。
• 利用 Laravel 的内置认证和授权功能（Sanctum、Policies）。
• 利用 Laravel 的缓存机制（Redis、Memcached）来提高性能。
• 使用任务队列和 Laravel Horizon 来处理长时间运行的任务和后台处理。
• 使用 PHPUnit 和 Laravel Dusk 实现全面的测试，包括单元测试、功能测试和浏览器测试。
• 使用 API 资源和版本控制来构建健壮且可维护的 API。
• 使用 Laravel 的异常处理程序和日志记录门面实现适当的错误处理和日志记录。
• 利用 Laravel 的验证功能，包括表单请求（Form Requests），以确保数据完整性。
• 实现数据库索引并使用 Laravel 的查询优化功能来提高性能。
• 在开发中使用 Laravel Telescope 进行调试和性能监控。
• 利用 Laravel Nova 或 Filament 进行快速管理面板开发。
• 实施适当的安全措施，包括 CSRF 保护、XSS 防御和输入净化。

---

代码架构

• 命名约定：
  • 对文件夹、类和文件使用一致的命名约定。
  • 遵循 Laravel 的约定：模型使用单数，控制器使用复数（例如，User.php, UsersController.php）。
  • 类名使用 PascalCase，方法名使用 camelCase，数据库列使用 snake_case。
• 控制器设计：
  • 控制器应为 final 类，以防止继承。
  • 使控制器为只读（即，没有属性修改）。
  • 避免直接在控制器中注入依赖项。相反，使用方法注入或服务类。
• 模型设计：
  • 模型应为 final 类，以确保数据完整性并防止继承带来的意外行为。
• 服务：
  • 在 app 目录中创建 Services 文件夹。
  • 将服务组织为特定于模型的服务和其他所需的服务。
  • 服务类应为 final 且只读。
  • 将复杂业务逻辑放在服务中，保持控制器精简。
• 路由：
  • 保持路由一致且有组织。
  • 为每个主要模型或功能区域创建单独的路由文件。
  • 将相关路由分组在一起（例如，所有用户相关路由在 routes/user.php 中）。
• 类型声明：
  • 始终为方法和函数使用显式返回类型声明。
  • 为方法参数使用适当的 PHP 类型提示。
  • 在必要时利用 PHP 8.3+ 的特性，如联合类型和可空类型。
• 数据类型一致性：
  • 在整个代码库中保持数据类型声明的一致性和明确性。
  • 对属性、方法参数和返回类型使用类型提示。
  • 利用 PHP 的严格类型来及早捕获类型相关错误。
• 错误处理：
  • 使用 Laravel 的异常处理和日志记录功能来处理异常。
  • 在必要时创建自定义异常。
  • 对预期异常使用 try-catch 块。
  • 优雅地处理异常并返回适当的响应。

---

关键点

• 遵循 Laravel 的 MVC 架构，以明确分离业务逻辑、数据和表示层。
• 使用表单请求（Form Requests）实现请求验证，以确保安全和经过验证的数据输入。
• 使用 Laravel 的内置认证系统，包括 Laravel Sanctum 用于 API 令牌管理。
• 确保 REST API 遵循 Laravel 标准，使用 API 资源以实现结构化和一致的响应。
• 利用任务调度和事件监听器来自动化重复任务和解耦逻辑。
• 使用 Laravel 的数据库门面实现数据库事务，以确保数据一致性。
• 使用 Eloquent ORM 进行数据库交互，强制执行关系并优化查询。
• 实现 API 版本控制以提高可维护性和向后兼容性。
• 使用 Redis 和 Memcached 等缓存机制优化性能。
• 使用 Laravel 的异常处理程序和日志记录功能，确保健壮的错误处理和日志记录。