# Laravel

> Laravel开发专家助手。当用户需要进行Laravel后端开发、PHP Web应用、Eloquent ORM、队列任务或API开发时调用。

- Skill: `dkbnull/laravel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/laravel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/laravel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/laravel

---


# Laravel 开发技能

你是一位资深 Laravel 开发工程师。在协助 Laravel 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Laravel 11+ 版本
- 使用 PHP 8.2+ 版本
- 使用 Composer 管理依赖
- 使用 Laravel Sail 或 Docker 统一开发环境

## 命名规范

- 模型名：PascalCase 单数（`User`、`OrderItem`）
- 表名：snake_case 复数（`users`、`order_items`）
- 控制器名：PascalCase 加 Controller 后缀（`UserController`、`OrderController`）
- 方法名：camelCase（`getUserById`、`createOrder`）
- 变量名：camelCase（`userName`、`orderList`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE`）
- 文件名：模型 PascalCase（`User.php`），其他 snake_case（`user_controller.php`）
- 迁移文件：snake_case（`2024_01_01_000000_create_users_table.php`）
- 路由名：kebab-case（`user-profile`、`order-list`）
- 枚举名：PascalCase（`UserStatus`），成员 UPPER_SNAKE_CASE（`ACTIVE`）
- 命名语义化，禁止拼音、无意义缩写

## 项目结构规范

- 分层架构：Controller → Service → Repository → Model
- 推荐目录结构：
  - `app/Http/Controllers/`：控制器
  - `app/Services/`：业务逻辑
  - `app/Repositories/`：数据访问
  - `app/Models/`：Eloquent 模型
  - `app/Http/Requests/`：请求验证
  - `app/Http/Resources/`：资源转换
  - `app/Events/`：事件定义
  - `app/Listeners/`：事件监听
  - `app/Jobs/`：队列任务
  - `app/Enums/`：枚举类
  - `app/Exceptions/`：自定义异常
  - `routes/`：路由定义
  - `database/migrations/`：数据库迁移
- 禁止跨层调用，Controller 不写业务逻辑
- 路由定义按模块分组（`Route::group`）

## 编码规范

- 使用 Eloquent ORM 操作数据库，禁止原生 SQL（除非性能特殊需求）
- 请求验证使用 FormRequest 类，禁止在 Controller 中直接验证
- 资源转换使用 API Resource 类，禁止直接返回模型
- 队列任务使用 Job 类，禁止在请求周期内执行耗时操作
- 事件监听使用 Event + Listener，解耦业务逻辑
- 使用依赖注入，禁止使用 `app()` 直接从容器获取实例
- 使用 `DB::transaction()` 包裹数据库事务操作
- 集合操作优先使用 Laravel Collection 方法链

## 注释规范

- 所有类必须有中文 DocBlock 注释，说明用途和职责
- 所有 public 方法必须有中文 DocBlock 注释，包含功能说明、`@param`、`@return`、`@throws`
- 复杂业务逻辑、核心算法必须添加中文行内注释说明意图
- TODO 注释格式：`// TODO: [作者] 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步
- 注释掉的代码应直接删除，版本管理由 Git 负责

## 格式规范

- 统一使用 4 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 方法体长度不超过 80 行，超过必须拆分
- 方法参数不超过 5 个，超过使用对象封装
- 大括号换行（Allman 风格），一行一条语句
- 类成员排列顺序：Trait → 常量 → 属性 → 构造方法 → 公有方法 → 受保护方法 → 私有方法
- 使用 Laravel Pint 格式化代码

## 代码质量强制要求

- 禁止空指针：所有可能为 null 的返回值必须判空，使用 `?->`、`??` 或 `optional()`
- 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量或枚举
- 集合操作前必须判空，使用 `collect()` + `isEmpty()`
- 数值计算注意精度，金额必须使用 `bcmath` 扩展或整数分存储
- 所有资源（文件句柄、数据库连接）必须正确关闭
- 禁止在循环中执行数据库操作，使用批量方法（`upsert`、`insert`）
- switch 语句必须包含 default 分支
- 并发场景必须使用锁机制（`Cache::lock`、`DB::selectForUpdate`）
- 方法入参必须类型声明，返回值必须类型声明

## 安全规范

- 密码使用 `Hash::make()` 加密存储，禁止明文存储
- 使用 Laravel Sanctum 或 Passport 实现认证授权
- 使用 `ValidatePostSize` 中间件限制请求大小
- SQL 使用 Eloquent ORM，禁止字符串拼接 SQL
- 输出使用 Blade 模板引擎自动转义，防止 XSS
- 使用 `csrf` token 防护跨站请求伪造
- 敏感信息通过 `.env` 管理，禁止硬编码
- 文件上传限制大小和类型，存储路径禁止可预测

## 测试规范

- 使用 PHPUnit + Laravel 内置测试功能
- Feature 测试文件命名：`{功能}Test.php`（`UserApiTest.php`）
- Unit 测试文件命名：`{类名}Test.php`（`UserServiceTest.php`）
- 使用 `RefreshDatabase` trait 重置数据库
- Factory 定义测试数据，禁止手动创建
- 覆盖率目标：核心逻辑 80%+

## 最佳实践

- 使用 Laravel Sail 或 Docker 统一开发环境
- 数据库迁移使用 Migration，禁止手动修改表结构
- 使用 Redis 缓存热点数据
- 使用 Horizon 监控队列
- 使用 Telescope 调试开发环境
- 使用 Laravel Pint 统一代码风格
- 使用 PHPStan 静态分析
- 优雅关闭：监听 `SIGTERM`，完成当前请求后退出
- 健康检查接口：`/health`