laravel-architecture

全面涵盖 Laravel 应用架构：项目结构 （Actions、Contracts、DTOs、Services、Repositories 布局）、服务容器与依赖注入、服务提供者与 Facades、环境与配置、开发环境（Sail、Valet、Homestead、Octane）、Artisan CLI、文件系统／进程／上下文、功能开关（Pennant）、MCP 服务、并发，以及生产部署（包括 Envoy、日志记录、错误处理和软件包编写）。

Laravel 架构模式

Agent 工作流（必须遵循）

在进行任何实现之前，并行启动 3 个 Agent，每个分别调用一次 Agent，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有架构
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 Laravel 模式
3. mcp__context7__query-docs - 检查服务容器和 DI 模式

实现之后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

Laravel 架构注重清晰的职责分离、依赖注入和易于维护的代码组织。本技能涵盖从项目结构到生产部署的所有内容。

适用场景

• 构建新的 Laravel 项目
• 实现服务、Repositories 和 Actions
• 设置依赖注入
• 配置开发环境
• 部署到生产环境

---

关键规则

1. 控制器保持精简 - 将业务逻辑委托给服务
2. 接口放在 app/Contracts/ - 绝不与实现放在一起
3. 优先使用 DI，而非 Facades - 使用构造函数注入以便测试
4. 文件行数不超过 FUSE_SOLID_MAX_LINES - 按照 SOLID 原则拆分较大的文件
5. 区分环境 - 绝不提交 .env

---

架构

app/
├── Actions/              # Single-purpose action classes
├── Contracts/            # Interfaces (DI)
├── DTOs/                 # Data transfer objects
├── Enums/                # PHP 8.1+ enums
├── Events/               # Domain events
├── Http/
│   ├── Controllers/      # Thin controllers
│   ├── Middleware/       # Request filters
│   ├── Requests/         # Form validation
│   └── Resources/        # API transformations
├── Jobs/                 # Queued jobs
├── Listeners/            # Event handlers
├── Models/               # Eloquent models only
├── Policies/             # Authorization
├── Providers/            # Service registration
├── Repositories/         # Data access layer
└── Services/             # Business logic

---

参考指南

核心架构

参考	适用场景
container.md	依赖注入、绑定、解析
providers.md	服务注册、引导
facades.md	静态代理、实时 Facades
contracts.md	接口、松耦合
structure.md	目录组织
lifecycle.md	请求处理流程

配置与设置

参考	适用场景
configuration.md	环境、配置文件
installation.md	新项目设置
upgrade.md	版本升级、破坏性变更
releases.md	发布说明、版本管理

开发环境

参考	适用场景
sail.md	Docker 开发
valet.md	macOS 原生开发
homestead.md	Vagrant（旧版）
octane.md	高性能服务端

实用工具

参考	适用场景
artisan.md	CLI 命令、自定义命令
helpers.md	全局辅助函数
filesystem.md	文件存储、S3、本地存储
processes.md	Shell 命令执行
context.md	请求范围内的数据共享

高级功能

参考	适用场景
pennant.md	功能开关
mcp.md	Model Context Protocol
concurrency.md	并行执行

运维

参考	使用场景
deployment.md	生产环境部署
envoy.md	SSH 任务自动化
logging.md	日志通道、格式
errors.md	异常处理
packages.md	创建软件包

---

模板

模板	用途
UserService.php.md	服务 + 仓库模式
AppServiceProvider.php.md	DI 绑定、引导
ArtisanCommand.php.md	CLI 命令、签名、I/O
McpServer.php.md	MCP 服务、工具、资源、提示词
PennantFeature.php.md	功能标志、A/B 测试
Envoy.blade.php.md	SSH 部署自动化
sail-config.md	Docker Sail 配置
octane-config.md	FrankenPHP、Swoole、RoadRunner

---

功能矩阵

功能	参考	优先级
服务容器	container.md	高
服务提供者	providers.md	高
目录结构	structure.md	高
配置	configuration.md	高
安装	installation.md	高
Octane（性能）	octane.md	高
Sail（Docker）	sail.md	高
Artisan CLI	artisan.md	中
部署	deployment.md	中
Envoy（SSH）	envoy.md	中
Facades	facades.md	中
Contracts	contracts.md	中
Valet（macOS）	valet.md	中
升级指南	upgrade.md	中
日志记录	logging.md	中
错误	errors.md	中
生命周期	lifecycle.md	中
文件系统	filesystem.md	中
辅助函数	helpers.md	低
Pennant（标志）	pennant.md	低
上下文	context.md	低
进程	processes.md	低
并发	concurrency.md	低
MCP	mcp.md	低
软件包	packages.md	低
发布	releases.md	低
Homestead	homestead.md	低

---

快速参考

服务注入

public function __construct(
    private readonly UserServiceInterface $userService,
) {}

服务提供者绑定

public function register(): void
{
    $this->app->bind(UserServiceInterface::class, UserService::class);
    $this->app->singleton(CacheService::class);
}

Artisan 命令

php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders

环境访问

$debug = env('APP_DEBUG', false);
$config = config('app.name');

---

Laravel 13 说明

更新后的技术栈

• Symfony 7.4 和 8.0 可并行使用（HttpFoundation、Console、Mailer）
• 最低要求 PHP 8.3（不再支持 8.2）
• Beanstalk 驱动需要 pda/pheanstalk 7.x / 8.x（不再支持 5.x）
• 当前稳定版本：13.33（2026 年 9 月）

Cache::touch() API

新增方法，可在不重新计算值的情况下刷新 TTL。

Cache::touch('user:123', 3600);
Cache::touch('user:123', now()->addHour());

用于动态路由的 Queue::route()

参见 [[laravel-queues]]，了解如何为每个作业类声明路由（Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts')），以及 Queue::forward()（13.26+）。

嵌套模型引导 → LogicException

Laravel 13 会在模型自身引导期间实例化模型（在模型的 boot() 或 trait 的 boot*() 中调用 new static()）时抛出 LogicException。请将该逻辑移出引导周期。

13.x 新增内容（13.1 → 13.33）

• php artisan dev（13.16+）：在单个终端中运行服务器、queue:listen、Pail 和 Vite；可通过 AppServiceProvider::boot() 中的 Illuminate\Foundation\DevCommands::artisan('horizon', 'horizon') 自定义，并可通过 php artisan dev:list 查看（需要 Node 22.13+）
• #[BindWhen(Impl::class, static fn () => ...)]（13.22+）：在接口上声明条件绑定——需要 PHP 8.5
• 大多数管理器均支持枚举（UnitEnum）（Cache::store()、Queue、Log、Mail、Auth::guard() 等）（13.3 → 13.7）
• 支持 Guzzle 8（13.26+）

Laravel 12 → 13 迁移

主题	之前（12）	之后（13）
PHP 最低版本	8.2	8.3
PHPUnit	11	12（支持 13）
Pest	3	4（PHP 8.4+ 时支持 5）
CSRF	VerifyCsrfToken	PreventRequestForgery（通过 Sec-Fetch-Site 检查来源）
缓存前缀	下划线	默认使用连字符（设置 CACHE_PREFIX、REDIS_PREFIX、SESSION_COOKIE 以保持向后兼容）
Beanstalk	pheanstalk 5.x	pheanstalk 7.x / 8.x
Symfony	7.x	7.4 / 8.0
模型引导	可接受	模型引导期间嵌套实例化 → LogicException
配置	—	新增 cache.serializable_classes（强化允许列表，默认值为 false）

# Backward-compatible cache prefixes when upgrading from L12
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session

// config/cache.php — deserialization hardening
'serializable_classes' => [
    App\DTO\PaymentDto::class,
    App\DTO\OrderDto::class,
],

最佳实践

应做

• 为 DTO 和值对象使用 final readonly class（PHP 8.3+）
• 通过构造函数属性提升注入，并使用 interface（依赖倒置）
• 使用 Context::add() 记录日志，在任务 / 请求间传递元数据
• 在生产环境中配置 serializable_classes
• 优先使用 app(Contract::class)，而非 App::make()（严格类型）

不应做

• 在模型自身的引导期间实例化模型（在 boot() 中使用 new static() → L13 中会触发 LogicException）
• 硬编码绝对路径（使用 base_path()、storage_path()）
• 混用 Repository 和 Service（每项职责各用一个）
• 使用 new ConcreteClass() 绕过容器
• 从 L12 升级时忽略缓存前缀的变化