把限界上下文引入现有 Laravel 应用的实战手册 ​

<?php

declare(strict_types=1);

namespace App\Modules\Identity\Providers;

use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;

final class IdentityServiceProvider extends ServiceProvider
{
    /**
     * 该模块契约的具体绑定。
     * 其它模块只应引用 Shared 下的 Contract 类。
     */
    private const BINDINGS = [
        \App\Shared\Contracts\Identity\UserDirectory::class
            => \App\Modules\Identity\Services\UserDirectoryService::class,
        \App\Shared\Contracts\Identity\PasswordHasher::class
            => \App\Modules\Identity\Services\Argon2idPasswordHasher::class,
    ];

    public function register(): void
    {
        foreach (self::BINDINGS as $abstract => $concrete) {
            $this->app->bind($abstract, $concrete);
        }

        $this->mergeConfigFrom(__DIR__ . '/../config/identity.php', 'identity');
    }

    public function boot(): void
    {
        $this->loadRoutes();
        $this->loadMigrations();
        $this->loadFactories();
        $this->registerListeners();
    }

    private function loadRoutes(): void
    {
        Route::middleware('api')
            ->prefix('api')
            ->name('identity.api.')
            ->group(__DIR__ . '/../Routes/api.php');

        Route::middleware('web')
            ->name('identity.')
            ->group(__DIR__ . '/../Routes/web.php');
    }

    private function loadMigrations(): void
    {
        $this->loadMigrationsFrom(__DIR__ . '/../Database/Migrations');
    }

    private function loadFactories(): void
    {
        if (! $this->app->environment('production')) {
            \Illuminate\Database\Eloquent\Factories\Factory::guessFactoryNamesUsing(
                fn(string $modelName) => str_replace(
                    ['App\\Modules\\', '\\Models\\'],
                    ['App\\Modules\\', '\\Database\\Factories\\'],
                    $modelName
                ) . 'Factory'
            );
        }
    }

    private function registerListeners(): void
    {
        // 只监听自己的事件，跨上下文事件走中介者模式
        \Illuminate\Support\Facades\Event::listen(
            \App\Modules\Identity\Events\UserRegistered::class,
            \App\Modules\Identity\Listeners\SendWelcomeEmailSignal::class,
        );
    }
}

'providers' => [
    // Laravel 自带的 provider
    Illuminate\Auth\AuthServiceProvider::class,
    // ...

    // 模块 provider
    App\Modules\Identity\Providers\IdentityServiceProvider::class,
    App\Modules\Billing\Providers\BillingServiceProvider::class,
    App\Modules\Commerce\Providers\CommerceServiceProvider::class,
    App\Modules\Loyalty\Providers\LoyaltyServiceProvider::class,
    App\Modules\Notifications\Providers\NotificationsServiceProvider::class,

    // 应用级 provider（保持极简）
    App\Providers\AppServiceProvider::class,
],

<?php
// app/Modules/Identity/Events/UserRegistered.php

namespace App\Modules\Identity\Events;

use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

final class UserRegistered
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public readonly int $userId,
        public readonly string $email,
        public readonly string $name,
        public readonly \DateTimeImmutable $registeredAt,
    ) {}
}

<?php
// app/Modules/Identity/Services/RegistrationService.php

namespace App\Modules\Identity\Services;

use App\Modules\Identity\Events\UserRegistered;
use App\Modules\Identity\Models\User;
use App\Shared\Contracts\Identity\PasswordHasher;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;

final class RegistrationService
{
    public function __construct(
        private readonly PasswordHasher $hasher,
    ) {}

    public function register(string $email, string $password, string $name): User
    {
        return DB::transaction(function () use ($email, $password, $name) {
            $user = User::create([
                'email'    => $email,
                'password' => $this->hasher->hash($password),
                'name'     => $name,
            ]);

            Event::dispatch(new UserRegistered(
                userId:       $user->id,
                email:        $user->email,
                name:         $user->name,
                registeredAt: $user->created_at->toDateTimeImmutable(),
            ));

            return $user;
        });
    }
}

<?php
// app/Modules/Loyalty/Listeners/CreateLoyaltyAccountForNewUser.php

namespace App\Modules\Loyalty\Listeners;

use App\Modules\Identity\Events\UserRegistered;
use App\Modules\Loyalty\Models\LoyaltyAccount;
use Illuminate\Contracts\Queue\ShouldQueue;

final class CreateLoyaltyAccountForNewUser implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        LoyaltyAccount::create([
            'user_id'        => $event->userId,
            'tier'           => 'bronze',
            'points_balance' => 0,
            'enrolled_at'    => $event->registeredAt,
        ]);
    }
}

// app/Modules/Loyalty/Providers/LoyaltyServiceProvider.php
private function registerListeners(): void
{
    Event::listen(
        \App\Modules\Identity\Events\UserRegistered::class,
        \App\Modules\Loyalty\Listeners\CreateLoyaltyAccountForNewUser::class,
    );

    Event::listen(
        \App\Modules\Commerce\Events\OrderCompleted::class,
        \App\Modules\Loyalty\Listeners\AwardPointsForOrder::class,
    );
}

<?php
// app/Shared/QueryBus/Query.php
namespace App\Shared\QueryBus;

interface Query {}

// app/Shared/QueryBus/QueryHandler.php
namespace App\Shared\QueryBus;

interface QueryHandler
{
    public function handle(Query $query): mixed;
}

// app/Shared/QueryBus/QueryBus.php
namespace App\Shared\QueryBus;

use Illuminate\Contracts\Container\Container;

final class QueryBus
{
    public function __construct(
        private readonly Container $container,
        private readonly array $handlers,   // query 类 => handler 类
    ) {}

    public function ask(Query $query): mixed
    {
        $queryClass = $query::class;

        if (! isset($this->handlers[$queryClass])) {
            throw new \RuntimeException("No handler registered for query $queryClass");
        }

        /** @var QueryHandler $handler */
        $handler = $this->container->make($this->handlers[$queryClass]);

        return $handler->handle($query);
    }
}

<?php
// app/Shared/Contracts/Identity/Queries/GetUserSummary.php
// （放在 Shared 下，因为是跨上下文契约）
namespace App\Shared\Contracts\Identity\Queries;

use App\Shared\QueryBus\Query;

final class GetUserSummary implements Query
{
    public function __construct(
        public readonly int $userId,
    ) {}
}

// app/Shared/Contracts/Identity/UserSummary.php
namespace App\Shared\Contracts\Identity;

final class UserSummary
{
    public function __construct(
        public readonly int $userId,
        public readonly string $email,
        public readonly string $name,
        public readonly ?string $preferredLanguage,
        public readonly bool $isActive,
    ) {}
}

<?php
// app/Modules/Identity/QueryHandlers/GetUserSummaryHandler.php
namespace App\Modules\Identity\QueryHandlers;

use App\Modules\Identity\Models\User;
use App\Shared\Contracts\Identity\Queries\GetUserSummary;
use App\Shared\Contracts\Identity\UserSummary;
use App\Shared\QueryBus\Query;
use App\Shared\QueryBus\QueryHandler;

final class GetUserSummaryHandler implements QueryHandler
{
    public function handle(Query $query): UserSummary
    {
        assert($query instanceof GetUserSummary);

        $user = User::findOrFail($query->userId);

        return new UserSummary(
            userId:            $user->id,
            email:             $user->email,
            name:              $user->name,
            preferredLanguage: $user->preferred_language,
            isActive:          $user->is_active,
        );
    }
}

<?php
// app/Modules/Billing/Services/InvoiceRenderer.php
namespace App\Modules\Billing\Services;

use App\Modules\Billing\Models\Invoice;
use App\Shared\Contracts\Identity\Queries\GetUserSummary;
use App\Shared\QueryBus\QueryBus;

final class InvoiceRenderer
{
    public function __construct(
        private readonly QueryBus $queryBus,
    ) {}

    public function render(Invoice $invoice): array
    {
        // 通过查询总线向 Identity 问客户数据，不直接 import User
        $user = $this->queryBus->ask(new GetUserSummary($invoice->user_id));

        return [
            'invoice_number' => $invoice->number,
            'customer_name'  => $user->name,
            'customer_email' => $user->email,
            'line_items'     => $invoice->items->map(...)->all(),
            'total'          => $invoice->total,
        ];
    }
}

// bootstrap/app.php 或单独的 QueryBusServiceProvider
$this->app->singleton(\App\Shared\QueryBus\QueryBus::class, function ($app) {
    return new \App\Shared\QueryBus\QueryBus(
        $app,
        handlers: [
            \App\Shared\Contracts\Identity\Queries\GetUserSummary::class
                => \App\Modules\Identity\QueryHandlers\GetUserSummaryHandler::class,

            \App\Shared\Contracts\Commerce\Queries\GetOrderTotals::class
                => \App\Modules\Commerce\QueryHandlers\GetOrderTotalsHandler::class,

            // ...
        ],
    );
});

<?php
// app/Modules/Billing/Models/UserReadModel.php
namespace App\Modules\Billing\Models;

use Illuminate\Database\Eloquent\Model;

final class UserReadModel extends Model
{
    protected $table = 'users';
    protected $guarded = [];

    /**
     * 本模型只读。Billing 绝不写入 users 表。
     * 用断言守住这条红线。
     */
    public static function boot(): void
    {
        parent::boot();

        static::saving(function () {
            throw new \LogicException(
                'Billing 模块不能写 users 表，请派发 Identity 事件或使用查询总线。'
            );
        });

        static::deleting(function () {
            throw new \LogicException(
                'Billing 模块不能删除用户，请派发 Identity 事件。'
            );
        });
    }
}

$overdue = Invoice::overdue()
    ->join('users', 'users.id', '=', 'invoices.user_id')
    ->select('invoices.*', 'users.email', 'users.name')
    ->get();

// app/Modules/Billing/Database/Migrations/...create_billing_customer_projection.php
Schema::create('billing_customer_projection', function (Blueprint $table) {
    $table->unsignedBigInteger('user_id')->primary();
    $table->string('email');
    $table->string('name');
    $table->string('preferred_language')->nullable();
    $table->boolean('is_active')->default(true);
    $table->timestamps();
});

// 更新投影表的监听器
final class UpdateBillingCustomerProjection
{
    public function handleRegistered(UserRegistered $event): void
    {
        BillingCustomerProjection::updateOrCreate(
            ['user_id' => $event->userId],
            [
                'email' => $event->email,
                'name'  => $event->name,
                // ...
            ]
        );
    }

    public function handleEmailChanged(UserEmailChanged $event): void
    {
        BillingCustomerProjection::where('user_id', $event->userId)
            ->update(['email' => $event->newEmail]);
    }
}

<?php
// app/Modules/Identity/Tests/Unit/RegistrationServiceTest.php
namespace App\Modules\Identity\Tests\Unit;

use App\Modules\Identity\Events\UserRegistered;
use App\Modules\Identity\Models\User;
use App\Modules\Identity\Services\RegistrationService;
use App\Shared\Contracts\Identity\PasswordHasher;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

final class RegistrationServiceTest extends TestCase
{
    public function test_successful_registration_creates_user_and_dispatches_event(): void
    {
        Event::fake();

        $hasher = $this->mock(PasswordHasher::class);
        $hasher->shouldReceive('hash')->andReturn('hashed-password');

        $service = $this->app->make(RegistrationService::class);

        $user = $service->register('alice@example.com', 'password', 'Alice');

        $this->assertInstanceOf(User::class, $user);
        $this->assertEquals('alice@example.com', $user->email);

        Event::assertDispatched(UserRegistered::class, fn($event) =>
            $event->userId === $user->id
            && $event->email === 'alice@example.com'
        );
    }
}

<?php
// app/Modules/Billing/Tests/Integration/IdentityContractTest.php
namespace App\Modules\Billing\Tests\Integration;

use App\Modules\Identity\Models\User;
use App\Shared\Contracts\Identity\Queries\GetUserSummary;
use App\Shared\Contracts\Identity\UserSummary;
use App\Shared\QueryBus\QueryBus;
use Tests\TestCase;

final class IdentityContractTest extends TestCase
{
    public function test_get_user_summary_returns_expected_shape(): void
    {
        $user = User::factory()->create([
            'email' => 'alice@example.com',
            'name'  => 'Alice',
        ]);

        /** @var QueryBus $bus */
        $bus = $this->app->make(QueryBus::class);

        $summary = $bus->ask(new GetUserSummary($user->id));

        $this->assertInstanceOf(UserSummary::class, $summary);
        $this->assertEquals('alice@example.com', $summary->email);
        $this->assertEquals('Alice', $summary->name);
    }
}