Laravel
Middleware 不再只用于路由,而是可以用于任意方法。goaop/goaop-laravel-bridge 2.0 为你的类挂上 behavior,其余的交给 Laravel 的容器、配置和 Artisan。
本页译自英文,以英文页面为准。 阅读原文
Middleware(中间件)是 Laravel 最好的设计之一。请求依次穿过一组小巧的类,每个类只添加一件事(认证、限流、会话),而不必改动你的控制器。桥接包 goaop/goaop-laravel-bridge 2.0 把这个思路带到了应用中的每一个方法和属性上,无论是 public、protected 还是 private。你只需把 behavior(行为)编写一次,指明它作用于哪里,它就会作为动态 middleware 包裹这些调用运行:在服务、action、job 以及 app/ 中的任何其他类里都是如此。
use App\Attributes\Transactional;
final class OrderService{ public function __construct(private readonly Inventory $inventory) {}
#[Transactional] public function place(Cart $cart): Order { $order = Order::create(['customer_id' => $cart->customerId]); $order->lines()->createMany($cart->lines()); $this->inventory->reserve($cart);
return $order; }}namespace App\Behaviors;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect{ #[Around('@execution(App\Attributes\Transactional)')] public function inTransaction(MethodInvocation $invocation): mixed { return DB::transaction(fn () => $invocation->proceed()); }}整个模式就是这样。如果你写过 middleware 的 handle($request, $next),你已经懂了:$invocation->proceed() 就是你的 $next($request)。现在,每个标记了 #[Transactional] 的方法都会作为一个整体提交或回滚,而 OrderService 里仍然只有业务逻辑。你不需要基类、接口、装饰器,也不需要调用 app()->extend()。
为什么它用起来就像 Laravel 的一部分
Section titled “为什么它用起来就像 Laravel 的一部分”- 像其他包一样安装。 执行
composer require,包自动发现(package discovery)就会注册服务提供者。只有一个可发布的配置文件config/go_aop.php,并支持用GOAOP_*环境变量覆盖。 - Behavior class(行为类)就是容器服务。 Laravel 容器在某个 behavior class 的 behavior 第一次运行时构建它。构造函数注入可以用,facade、
config()以及应用绑定的所有服务也都可以用。 - 在你注册其他一切的地方注册它们。 在配置中列出一个类,或者在服务提供者中给服务打上
goaop.aspect标签,这样扩展包也能贡献自己的 behavior。 - 生产环境的工作交给 Artisan。
php artisan aop:warmup在部署时构建缓存,如果你愿意,还可以用并行的 worker。它能嵌入你现有的部署流程,放在composer install和php artisan optimize之后即可。php artisan about会显示缓存位置和调试模式。 - 开发时没有构建步骤。 开启
debug后,修改过的类会在下一个请求时重新编译,断点在你的原始文件中照常生效。
Behavior 能触及而装饰器触及不到的地方
Section titled “Behavior 能触及而装饰器触及不到的地方”装饰器包裹的是你从容器中解析出来的对象,所以它只能看到 public 方法,而且只在那条路径上生效。Behavior 则是在类加载时直接挂到类本身上,因此:
- 每个实例都有。 来自容器的对象和你用
new创建的对象表现完全一样。类型声明、instanceof和类名都不变,因为根本不存在包装对象。 - 任何种类的方法都适用。 private、protected、
final和静态方法,以及final和readonly类中的方法(Intercept anything)。 - 属性也可以。 通过原生的 PHP 8.4 属性钩子,拦截 public、protected 和 private 属性的读写,包括构造函数提升的属性:
access(private App\Domain\Order->status)或@access(App\Attributes\Audited)(属性上的 behavior)。 - 一条规则就能覆盖整个命名空间。
execution(public App\Services\**->*(*))会选中App\Services下的每个 public 方法,包括你下个月才添加的类(matching rule(匹配规则))。 - 开销很小。 没有 behavior 的方法和属性没有任何额外开销。带有 behavior 的方法或属性每次调用的开销不到 1 µs(实测开销)。
- 它就是纯 PHP。 不需要 PECL 扩展,也没有
eval()。编译后的类是storage/framework/aop中普通的.php文件,你可以直接阅读(Pure PHP)。
- PHP 8.4 或更高版本
- Laravel 12 或 13
goaop/framework^4.0(用注解声明 behavior),随桥接包一起安装
composer require goaop/goaop-laravel-bridge包自动发现会自动注册服务提供者。如果你想修改配置,就发布它:
php artisan vendor:publish --tag=goaop-config你的第一个 behavior
Section titled “你的第一个 behavior”Behavior class(在 API 里叫 aspect(切面))是一个实现了 Go\Aop\Aspect 的普通类。它的每个带有 #[Before]、#[After]、#[Around] 或 #[AfterThrowing] 的 public 方法就是一个 behavior,而该注解中的字符串就是它的 matching rule(在 API 里叫 pointcut(切入点)):它指明 behavior 在哪里运行。
-
创建一个注解来标记方法,或者跳过这一步,按名称选择方法(见下一节)。
app/Attributes/Transactional.php namespace App\Attributes;use Attribute;#[Attribute(Attribute::TARGET_METHOD)]final class Transactional {} -
编写 behavior class。 本页开头的
TransactionalBehavior已经是完整的。#[Around]让 behavior 代替方法运行,@execution(App\Attributes\Transactional)会选中每个带有该注解的方法。 -
在
config/go_aop.php中注册 behavior class:config/go_aop.php 'aspects' => [App\Behaviors\TransactionalBehavior::class,], -
用
#[Transactional]标记一个方法,然后调用它。下一个请求就会在事务中运行它。
按规则挂载 behavior
Section titled “按规则挂载 behavior”Behavior 并不要求目标上带有注解。Matching rule 可以按名称、命名空间或可见性选择方法,于是应用的整整一层都能获得这个 behavior,而无需改动其中任何一个类:
namespace App\Behaviors;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;use Go\Lang\Attribute\Before;use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect{ #[Before('execution(public App\Services\**->*(*))')] public function logCall(MethodInvocation $invocation): void { Log::debug('Calling ' . $invocation->getMethod()->getName()); }
#[Around('execution(public App\Services\PaymentService->charge(*))')] public function measureCharge(MethodInvocation $invocation): mixed { $start = hrtime(true); try { return $invocation->proceed(); } finally { Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms'); } }}logCall() 在 App\Services 下每个 public 方法之前运行。measureCharge() 包裹一个方法并为它计时,方法抛出异常时也是如此。四种注解、call context(调用上下文,即 $invocation)和完整的规则语法见 行为与匹配规则。完整的分步示例见 缓存行为 和 日志行为。
注册 behavior class
Section titled “注册 behavior class”你从不需要自己把 behavior class 交给引擎。在启动阶段,在所有服务提供者完成注册之后、你的应用代码运行之前,桥接包会从两个来源收集它们。
配置列表。 像上面的步骤那样,在 config/go_aop.php 中列出这个类。列出的类在内核启动时就会被注册,而不会加载这个类。Laravel 容器在它的某个 behavior 第一次被调用时才解析它,所以 behavior class 可以依赖那些只有在应用完全启动后才存在的服务。一个请求如果没有运行它的任何 behavior,就永远不会创建它。
goaop.aspect 标签。 在你的某个服务提供者中给服务打标签:
use App\Behaviors\ServiceTimingBehavior;use Psr\Log\LoggerInterface;
// in register()$this->app->singleton(ServiceTimingBehavior::class, function ($app) { return new ServiceTimingBehavior($app->make(LoggerInterface::class));});$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');当 behavior class 的构造过程不简单,或者某个扩展包要在不改动你配置的情况下贡献 behavior class 时,使用标签。打了标签的服务会在桥接包的服务提供者启动时被解析,因为 Laravel 的标签只能通过解析其服务来枚举。对于构造函数开销大或依赖启动过程的 behavior class,优先使用配置列表。
两种来源可以同时使用;重复的只会注册一次。被发现的类如果没有实现 Go\Aop\Aspect,会以一个说明清楚的异常失败。Laravel 容器作为 PSR-11 委托容器挂接到内核的容器上,因此 behavior 和 behavior class 的工厂都可以通过它查找应用服务。
config/go_aop.php 中的主要选项。每一项都可以通过环境变量覆盖。
| 选项 | 默认值 | 用途 |
|---|---|---|
debug |
GOAOP_DEBUG → APP_DEBUG |
源码变化时重新编译,断点在原始文件中生效;生产环境中请保持关闭 |
appDir |
base_path() |
编译器可以触及的根目录 |
cacheDir |
storage_path('framework/aop')(GOAOP_CACHE_DIR) |
编译后的源码和代理的缓存位置 |
cacheFileMode |
0770(GOAOP_CACHE_PERMISSIONS,八进制数字,例如 "770") |
缓存文件的 chmod 权限 |
parsedFilesLimit |
100(GOAOP_PARSED_FILES_LIMIT) |
编译期间保留在内存中的已解析源文件数量(每个约 0.2 MB);也是 aop:warmup --cached-files 的默认值 |
includePaths |
[app_path()] |
只有这些目录会被编译 |
excludePaths |
[] |
永远不编译这些目录 |
features |
0(GOAOP_FEATURES) |
Go\Aop\Features 标志的位掩码:INTERCEPT_INCLUDES = 4,PREBUILT_CACHE = 64,PARTIAL_REFLECTION = 256 |
aspects |
[] |
要注册的 behavior class |
作用于函数调用和对象创建的 behavior 由各自的 matching rule 驱动,不需要任何标志。php artisan about 会显示框架缓存的当前位置和调试模式。
部署:php artisan aop:warmup
Section titled “部署:php artisan aop:warmup”php artisan aop:warmup如果不预热,每个类会在首次加载时编译。在部署时运行 aop:warmup,可以预先把它们全部编译好;关闭 debug 时推荐这样做。有文件无法编译时,命令会以非零状态退出,这样部署脚本就会停下,而不会发布一个不完整的缓存。传入 --fail-fast 可以在第一个错误处停止。
php artisan aop:warmup --workers=8php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aopphp artisan aop:warmup --preload--workers=N在并行的 worker 进程中编译。每个 worker 都是你自己的artisan,所以它以相同的环境、配置和 behavior class 启动。--cache-dir=DIR在运行中的版本旁边构建新版本的缓存。这样构建的缓存是完整的,并且与位置无关。--preload写出一个opcache.preload脚本:正在构建的缓存目录中的_preload.php,或者由--preload=FILE指定的文件。
要让容器镜像附带编译好的脚本,在预热之后、php artisan optimize 之后,在最终镜像中预先填充 opcache.file_cache:
php artisan optimizemkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \ -d opcache.file_cache=/var/cache/opcache \ artisan aop:warmup-opcache --file-cache=/var/cache/opcache使用 PREBUILT_CACHE 的生产环境
Section titled “使用 PREBUILT_CACHE 的生产环境”composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cachephp artisan optimize # the cached configuration carries GOAOP_FEATURESphp artisan aop:warmup设置 GOAOP_FEATURES=64(PREBUILT_CACHE)后,请求永远不会触发编译。包含路径(include paths)下缓存中缺失的类会以 WeavingException 失败,所以每次部署都要运行 aop:warmup。Laravel 的缓存命令(package:discover、optimize、optimize:clear,以及 config、event、route 和 view 的缓存与清除命令)不处理任何请求,所以它们从原始源码加载类。这就是上面的顺序能够成立的原因。
配置一旦被缓存,就不再读取 env()。请在生产环境下运行 optimize(或 config:cache),并带上 GOAOP_FEATURES。完整的检查清单见 生产环境与性能。
- Compile step(编译步骤)在启动阶段开始时启动。在此之前加载的类(非常早期的引导代码、其他包
register()的内部实现、你自己的服务提供者)无法获得 behavior。 - 只有
appDir和includePaths下的类会被纳入考虑。vendor 代码不会被编译。 - 通过
excludePaths排除异常处理器:发生致命错误时,在冷缓存下可能无法加载被编译的处理器。
© 2026 Alexander Lisachenko
