Laravel Operations
资料标注事实核验时间：2026-07。
本文档定位为 Laravel 11+ 开发的权威参考，涵盖架构决策、Eloquent 模式、认证策略、队列配置和测试方法。
一、架构决策
文档提供应用类型决策树：
全栈 Web（HTML 响应）：简单 CRUD、小团队可选单体架构（Blade + Eloquent 直接使用），业务逻辑超过 20 行时使用 action 类；需要丰富交互时选 Livewire（服务端驱动响应式），可叠加 Alpine.js 处理客户端微交互；希望具备 SPA 体验的 React/Vue 团队可选 Inertia.js，保留服务端路由。
API 后端（JSON 响应）：单一消费方（移动端/SPA）可用纯 API + Sanctum SPA 认证；多消费方或公开 API 可用 RESTful API + token 认证；复杂图查询可考虑 GraphQL（lighthouse-php/lighthouse）。
大型团队/复杂领域：领域驱动可选模块化单体（app/Modules/{Domain}/），每个模块含 Models、Actions、Events、Jobs、Http/，共享部分放 app/Shared/；需要独立部署时可用微服务，高吞吐服务可用 Laravel Octane。
业务逻辑模式：简单 CRUD（少于 20 行）直接在控制器中使用 Eloquent；可复用操作（下单、开发票）使用 action 类，单一公共 handle() 或 execute() 方法；复杂查询、多数据源使用 Repository 模式（接口 + Eloquent 实现）；横切操作（审计、缓存）使用 Service 类，构造函数注入并在 ServiceProvider 中绑定。
文档给出 Action 类、Repository、Service 与直接 Eloquent 的适用对照表。
二、Eloquent 速查
关系：列出 hasOne、hasMany、belongsTo、belongsToMany、hasManyThrough、morphTo、morphMany、morphToMany 的写法与外键约定。
预加载：防止 N+1，控制器中始终使用 with()，示例 Post::with(['author','comments.author','tags'])->paginate(15)；支持 load()、loadMissing()、withCount() 以及约束预加载。
查询作用域：局部作用域 scopeActive(Builder $query)，动态作用域 scopeOfType(Builder $query, string $type)。
批量赋值：推荐使用 $fillable 白名单；$guarded 是拒绝名单，文档明确提示生产代码中绝不要设置 guarded = []。
三、Artisan 命令速查
列出常用命令及用途与选项，包括 make:model Post -mfs、make:controller PostController -r、make:request、make:job、make:event、make:listener、make:notification、make:policy、make:middleware、make:command；migrate、migrate:rollback、migrate:fresh --seed、db:seed、tinker、route:list、route:cache、config:cache、view:cache、optimize、queue:work、queue:listen、queue:failed、queue:retry all、schedule:run、schedule:work、key:generate、test、test --parallel、vendor:publish 等。
四、认证决策
SPA（Vue/React）+ Laravel API 后端：使用 Sanctum SPA 认证，基于 Cookie（同域或子域），CSRF cookie 端点为 GET /sanctum/csrf-cookie，token 不存入 localStorage（防 XSS）。
移动应用或第三方 API 消费方：使用 Sanctum API token（Bearer），createToken($name, $abilities)，支持 token 能力细粒度控制，可通过 token:prune 计划任务设置过期。
传统服务端渲染 Web 应用：需要快速获得认证页面用 Breeze（composer require laravel/breeze --dev）；需要团队、2FA、资料管理用 Jetstream（composer require laravel/jetstream）；需要无头认证（API + 自定义 UI）用 Fortify，actions 位于 app/Actions/Fortify/。
自定义/企业：LDAP/SAML 可用 socialiteproviders/saml2，OAuth 社交登录用 laravel/socialite，自定义 guard 可实现 Guard 与 UserProvider 契约。
文档附 Sanctum 快速配置示例：config/sanctum.php 的 stateful 域配置、token 创建、tokenCan() 能力检查、auth:sanctum 中间件保护路由。
五、队列决策
开发/测试：sync 驱动，立即执行，无需 worker（QUEUE_CONNECTION=sync）。
小型应用、无 Redis：database 驱动，需执行 php artisan queue:table && migrate，适合每分钟少于 100 个任务。
中高吞吐、自托管：Redis 驱动（predis 或 phpredis），配合 Laravel Horizon 监控，支持优先级、暂停、指标。
AWS 基础设施/大规模：SQS 驱动，托管、自动扩缩，可配合 Laravel Vapor 实现无服务器。
任务模式：基本 dispatch、链式（Bus::chain）、批处理（Bus::batch 带 then/catch 回调）、限流（RateLimited）、唯一任务（ShouldBeUnique）、重试配置（$tries、$backoff、retryUntil()）。
任务调度：routes/console.php（Laravel 11+）中 Schedule::job、Schedule::command、Schedule::call；使用 withoutOverlapping() 防止重叠、onOneServer() 仅单服务器运行（需 Redis/database 缓存驱动）。
六、测试速查
测试类型：Feature 测试（Tests\TestCase，可用数据库，测 HTTP 端点与全栈）、Unit 测试（PHPUnit\Framework\TestCase，无应用启动）、Browser 测试（Laravel\Dusk\TestCase，通过 ChromeDriver 使用真实浏览器）。
数据库 trait：RefreshDatabase（每次测试 migrate fresh，较慢）、DatabaseTransactions（每次测试回滚，较快）。
Pest 语法（Laravel 11+ 推荐）：describe、beforeEach、it 及断言示例。
常用断言：HTTP 响应（assertStatus、assertOk、assertCreated、assertNoContent、assertUnauthorized、assertForbidden、assertNotFound、assertRedirect）；JSON（assertJson、assertJsonPath、assertJsonCount、assertJsonStructure、assertJsonMissing）；数据库（assertDatabaseHas、assertDatabaseMissing、assertDatabaseCount、assertSoftDeleted）。
七、常见陷阱
文档以表格列出问题、原因与修复，包括：N+1 查询（使用 with() 预加载，开发期可启用 Model::preventLazyLoading()）；批量赋值漏洞（始终定义 $fillable，生产环境不要用 $guarded = []）；update() 时 created_at 不更新；队列任务因模型序列化失败（使用 SerializesModels，必要时在 handle() 中重新查询）；计划任务时区不一致（设置 APP_TIMEZONE，调度项使用 ->timezone()）；中间件顺序影响认证与节流结果；路由模型绑定跳过软删除记录（Route::bind 配合 withTrashed()）；服务容器接口未绑定实现（AppServiceProvider::register()）；迁移外键顺序；CSRF 阻止 API 路由（API 路由注册在 routes/api.php）；缓存后 env() 返回 null（应用代码中经 config() 访问）；Blade @stack 渲染顺序（需要靠前的脚本用 @prepend）；事件监听器未触发（检查 EventServiceProvider::$listen 或 Laravel 11 的 Event::discover()）。
八、参考文件
references/eloquent-queries.md：关系、查询构建器、作用域、访问器、修改器、事件、软删除、分页、性能、集合、工厂。
references/architecture.md：服务容器、提供者、门面、中间件、事件、通知、任务、调度、Blade 组件、Livewire、Inertia。
references/testing-auth.md：PHPUnit/Pest 设置、HTTP 测试、数据库测试、fake、Sanctum、Fortify、策略、表单请求、Dusk。
九、参见
sql-ops：查询优化、索引策略、原生 SQL 模式。 postgres-ops：PostgreSQL 特性、JSON 列、全文搜索。 testing-ops：通用测试理念、TDD、CI 集成。 docker-ops：Laravel 应用容器化、Docker Compose、生产环境搭建。
十、关键外部资源
Laravel 11 文档、Pest PHP、Laravel Horizon（队列监控）、Laravel Telescope（本地调试与请求/查询监控）、Laravel Octane（高性能服务）、Laravel Forge（服务器管理）、Laravel Vapor（无服务器部署）。
价格、收费模式、许可等信息暂未提供。