Laravel实践用社区规范吗

本文目录导读：

1. 编码风格规范（必须遵守）
2. 架构与目录结构规范（关键）
3. 数据库与迁移规范
4. 路由与中间件规范
5. 艺术化命令 (Artisan Commands) 与任务规范
6. 如何确保你的代码符合社区规范？

这是一个很好的问题！在 Laravel 社区中，确实有一套被广泛认可和遵循的实践规范，严格来说没有官方强制推行的“唯一规范”，但大多数高质量的 Laravel 项目、包和团队都遵循一套约定俗成的“社区规范”。

这套规范主要源于 Laravel 的设计哲学（约定优于配置、优雅代码、关注点分离）以及创始人 Taylor Otwell 和社区的推荐。

以下是一份 Laravel 实践中的核心社区规范清单，按重要性排列：

编码风格规范（必须遵守）

这是 Laravel 社区最基础、最严格的规范，主要遵循 PSR-2（现已升级为 PSR-12）以及 Laravel 特有的扩展。

• 工具：使用 laravel/pint（Laravel 9+ 官方推荐）或 friendsofphp/php-cs-fixer 自动修复代码风格。
• 关键点：
  • 使用 4 个空格缩进，禁止使用 Tab。
  • 花括号 必须放在新行（类、方法）或同一行（控制结构如 if/else），Laravel 社区倾向于控制结构的括号放在同一行。
  • 命名规范：
    • 类：PascalCase（如 UserController）
    • 方法/函数：camelCase（如 getUserById）
    • 变量：camelCase（如 $userName）
    • 配置文件、迁移文件、Seeder 类：snake_case（如 create_users_table）
    • 路由名称：kebab-case 或 snake_case（如 users.index, user-profile.show），推荐 snake_case 因为与控制器方法名更一致。
    • 表单请求验证类：通常用 PascalCase 且包含 Request 后缀（如 StoreUserRequest）。

架构与目录结构规范（关键）

Laravel 的默认目录结构是社区规范的基础。不要随意修改自动加载的目录。

• 控制器：推荐使用 单动作控制器 或 资源控制器。
  • ResourceController：对于标准的 CRUD，使用 php artisan make:controller UserController --resource。
  • SingleActionController：对于单一入口（如仪表盘、登录页），创建 __invoke() 方法，文件名通常为 ShowDashboardController。
• 模型：
  • 遵循 Eloquent 命名规范：模型类名用单数（User），表名用复数（users）。
  • 定义 $fillable 或 $guarded 属性以防止 Mass Assignment（批量赋值）漏洞。
  • 将 关联关系、查询作用域 (Scopes)、访问器和修改器 放在模型内部。
• 服务层：对于复杂业务逻辑，创建 Service 类（如 UserService），控制器应该很薄，负责接收请求和响应。
• 仓储 (Repository) 模式：不是 Laravel 官方推荐的通用模式，社区存在分歧，对于简单的 CRUD，直接使用 Eloquent 模型，如果你使用仓储模式，确保它抽象了查询逻辑，但不要把 Eloquent 替换掉（直接返回集合或模型）。
• Form Requests：使用 php artisan make:request StoreUserRequest 创建专用的表单请求验证类，将验证逻辑从控制器中分离。

数据库与迁移规范

• 迁移文件名：使用 create_table_name_table 格式（如 2023_01_01_000000_create_users_table.php）。
• 列定义：使用 Schema 构建器，而不是原始 SQL，命名一致：snake_case（如 first_name, created_at）。
• 外键：在迁移中明确声明外键约束。
• 时间戳：使用 Laravel 内置的 $table->timestamps()，不要手动创建。
• 软删除：使用 $table->softDeletes() 生成 deleted_at 字段，模型类需要 use SoftDeletes trait。

路由与中间件规范

• 路由分组：根据功能或模块分组（如 Route::prefix('admin')->...）。
• 名称空间：使用合理的名称空间（如 App\Http\Controllers\Admin\）。
• 中间件：将验证逻辑、权限检查等放在中间件中，而不是控制器中。
• 命名：路由名称用 snake_case 或 kebab-case，如 Route::get('users', ...)->name('users.index')。

艺术化命令 (Artisan Commands) 与任务规范

• 命令名：使用 model:action 格式（如 user:create, report:generate）。
• Job (队列任务)：命名 PascalCase（如 SendWelcomeEmail），每个 Job 应该只做一件事。
• Event 与 Listener：Event 命名 PascalCase（如 UserRegistered），Listener 命名 PascalCase（如 SendWelcomeEmailListener）。

如何确保你的代码符合社区规范？

1. 使用 Laravel Pint：Laravel 9 内置，运行 ./vendor/bin/pint 自动修复大部分编码风格问题。
2. 遵循“Laravel 之道”：阅读官方文档和 Laravel News 博客。
3. 查看开源项目：看 Laravel 官方团队开发的项目（如 Laravel Horizon、Laravel Cashier）或社区高星项目（如 Spatie 的包），它们的代码就是规范。
4. 使用 PHPStan 或 Larastan：进行静态分析，发现潜在的错误和不一致。
5. 代码审查：在团队中强制执行这些规范。

“用社区规范吗？” 答案是：是的，强烈建议使用，并且这是 Laravel 生态健康发展的基石。

不遵循的后果：

• 代码审查困难,别人看不懂。
• 无法使用一些社区工具和包（它们假定你遵循规范）。
• 你的代码在 Laravel 世界中会显得非常“野路子”，难以维护。
• 自动格式化工具（Pint）会直接报错或强制修改你的代码。

一句话：遵循社区规范，你的代码会更容易被其他 Laravel 开发者理解、重用和维护。 这是进入专业 Laravel 开发的“通关密码”。