laravel-modules 实战指南:用模块化架构组织大型 Laravel 应用

原创2026-10-14 22:04:261,859 阅读
文章标签:后端插件系统代码生成CLI

laravel-modules 实战指南:用模块化架构组织大型 Laravel 应用

laravel-modules 是一个面向大型 Laravel 应用的模块化管理包,它将"模块(Module)"抽象为一种近似于 Laravel 独立包的结构——每个模块自带视图、控制器、模型、路由与配置文件,从而把单体应用拆解为边界清晰的业务单元。本文将以本仓库(nwidart/laravel-modules)的 README.md 为骨架,结合 config/config.php、src 源码与 tests 测试,系统讲解安装、自动加载、模块发现注册机制、核心配置、命令行用法与生命周期管理,帮助你从"会用"进阶到"理解其原理"。

一、模块是什么:理解 laravel-modules 的核心模型

官方文档对 laravel-modules 的定位非常直白:它用于管理大型 Laravel 应用,而一个模块(Module)就像是一个迷你版的 Laravel 包——拥有自己的视图、控制器、模型、迁移、语言包与路由。

这与 Laravel 生态中常见的"按功能目录分块"思路有本质区别:每个模块是自包含的单元,可以被独立启用、禁用、删除,也可以被当成一个可复用的包独立分发。模块的元信息记录在模块根目录下的 module.json 清单文件中,json.stub 展示了它的标准结构:

{
    "name": "$STUDLY_NAME$",
    "alias": "$LOWER_NAME$",
    "description": "",
    "keywords": [],
    "priority": 0,
    "providers": [
        "$MODULE_NAMESPACE$\\$STUDLY_NAME$\\$PROVIDER_NAMESPACE$\\$STUDLY_NAME$ServiceProvider"
    ],
    "files": []
}

从 src/Json.php 可以看到,module.json 会被解析为 Json 对象缓存到内存,供模块按 key 读取(如 name、alias、providers、priority、files)。测试目录 tests/stubs/valid/Recipe/module.json 给出了一个真实可用的模块清单示例,其中 providers 声明了模块的服务提供者,files 声明了模块启动时需要 include 的辅助文件——这些字段正是模块注册流程的数据来源。

版本兼容矩阵

README 给出 laravel-modules 各主版本与 Laravel 的对应关系,这是选择安装版本的第一依据:

Laravel laravel-modules
5.4 ^1.0
5.5 ^2.0
5.6 ^3.0
5.7 ^4.0
5.8 ^5.0
6.0 ^6.0
7.0 ^7.0
8.0 ^8.0
9.0 ^9.0
10.0 ^10.0
11.0 ^11.0
12.0 ^12.0
13.0 ^13.0

README 声明本包已在 Laravel 11 上得到支持与测试;而当前仓库的 composer.json 中 require-dev 已引入 laravel/framework: ^13.0、php: ^8.3,branch-alias 为 13.x-dev,说明仓库开发主线正面向 Laravel 13。安装时应以你项目的 Laravel 版本为基准,从表中选取对应主版本。

与 pingpong/modules 的关系

laravel-modules 是 pingpong/modules(已不再维护)的重新发布、重新组织并持续维护的版本,而它相对原包有一个关键优势:配套的测试体系。仓库 tests 目录下覆盖了激活器、命令、生成器、仓储、辅助函数等大量测试用例,这保证了重构与升级的可靠性。

二、安装与配置

通过 Composer 安装

composer require nwidart/laravel-modules

安装完成后,包会自动注册服务提供者与别名(alias),无需手动修改 config/app.php。这一点可以从 composer.json 的 extra.laravel 段得到验证:

"extra": {
    "laravel": {
        "providers": [
            "Nwidart\\Modules\\LaravelModulesServiceProvider"
        ],
        "aliases": {
            "Module": "Nwidart\\Modules\\Facades\\Module"
        }
    }
}

服务提供者指向 src/LaravelModulesServiceProvider.php,别名指向 src/Facades/Module.php。

发布配置文件

如果需要自定义模块路径、命名空间、生成规则等,可以发布包的配置文件:

php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"

发布后得到 config/modules.php。从 src/ModulesServiceProvider.php 的 registerNamespaces() 可以看到,该提供者除了发布配置,还支持发布 stubs(发布到 stubs/nwidart-stubs)与 Vite 辅助脚本(vite-module-loader.js,发布到项目根目录),分别对应 --tag 为 config、stubs、vite 的发布操作。

三、模块自动加载:v11.0 之后的新方式

这是 README 重点强调的破坏性变更,务必注意:

从 v11.0 开始,"Modules\\": "modules/" 这样的 PSR-4 自动加载配置已不再需要,如果 composer.json 中仍存在应予以删除。

默认情况下,模块类不会自动加载。v11.0 推荐的做法是借助 wikimedia/composer-merge-plugin,将各模块自己的 composer.json 合并进主应用的 Composer 配置,从而让模块内的类被自动加载。在项目根 composer.json 的 extra 段添加:

"extra": {
    "laravel": {
        "dont-discover": []
    },
    "merge-plugin": {
        "include": [
            "Modules/*/composer.json"
        ]
    }
},

首次安装时的插件信任提示

重要:首次安装时,Composer 会询问是否信任 wikimedia/composer-merge-plugin:

Do you trust "wikimedia/composer-merge-plugin" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]

应当回答 y,允许该插件执行;否则需要手动在 composer.json 中启用:

"config": {
    "allow-plugins": {
        "wikimedia/composer-merge-plugin": true
    }
}

若 "wikimedia/composer-merge-plugin": false,模块将不会被自动加载。

这一点与当前仓库 composer.json 的自身配置完全一致——它在 require 中声明了 wikimedia/composer-merge-plugin: ^2.1,并在 config.allow-plugins 中将其设为 true。

Tip:配置完成后记得运行 composer dump-autoload,重新生成自动加载映射。实际上 module:make 命令在创建模块后也会自动执行一次 composer dump-autoload,见 ModuleMakeCommand.php。

四、模块的发现与注册机制(源码级)

理解 laravel-modules 的原理,关键在于看透它"扫描清单 → 构建 manifest → 批量注册"的三段式流程。

1. 扫描:以 module.json 为识别标志

src/FileRepository.php 的 scan() 方法遍历扫描路径,用 glob 匹配每个目录下的 module.json:

$manifests = (array) $this->getFiles()->glob("{$path}/module.json");

扫描路径由 getScanPaths() 决定(FileRepository.php):默认包含 paths.modules(即 base_path('Modules')),当配置项 scan.enabled 为 true 时还会并入 scan.paths(默认是 vendor/*/*,便于从 Packagist 安装模块)。每个命中 module.json 的目录都会通过 createModule() 创建为模块实例(Laravel 下对应 src/Laravel/LaravelFileRepository.php 与 src/Laravel/Module.php)。

2. 构建 manifest:过滤启用状态并按优先级排序

src/ModuleManifest.php 会读取所有 module.json,仅保留当前处于启用状态的模块(通过 ActivatorInterface::hasStatus($module['name'], true) 判断),并按 priority 字段升序排序,最后扁平化收集所有 providers。

3. 注册:ProviderRepository 批量加载

src/ModulesServiceProvider.php 的 registerModules() 把 manifest 中的 providers 交给 Laravel 的 ProviderRepository 加载,并调用 registerFiles() include 各模块清单中 files 字段声明的辅助文件。由此,每个模块的服务提供者、别名(aliases)、辅助文件(files)都被纳入应用生命周期。

在 Laravel 环境下,模块自身的注册细节见 src/Laravel/Module.php:registerProviders() 使用独立的缓存路径加载模块提供者;registerAliases() 通过 AliasLoader 注册别名;getCachedServicesPath() 还针对 Laravel Vapor 提供了可写路径的维护模式支持(对应配置项 vapor_maintenance_mode)。

五、核心配置项详解(config/modules.php)

发布后的配置基于 config/config.php,下面按功能块拆解关键参数。

5.1 命名空间与路径

  • namespace:默认 'Modules',即模块的根命名空间。
  • paths.modules:默认 base_path('Modules'),模块生成与扫描的根目录。
  • paths.assets:默认 public_path('modules'),模块静态资源发布目录。
  • paths.migration:默认 base_path('database/migrations'),module:publish-migration 的发布目标。
  • paths.app_folder:默认 'app/',应用目录名,可改为 src/ 或 App/。
  • paths.generator:声明各类型代码(controller、model、migration、seeder、provider、routes、views、tests 等)在模块内的生成路径,以及 generate 开关——设为 false 则生成模块时不会创建该目录。例如默认只开启 provider、route-provider、controller、config、factory、migration、seeder、assets、views、routes、test-feature、test-unit 等目录,而 actions、casts、model、request、event、jobs 等默认不生成(按需手动开启)。

5.2 stubs(生成模板)

'stubs' => [
    'enabled' => false,
    'path' => base_path('vendor/nwidart/laravel-modules/src/Commands/stubs'),
    'files' => [
        'routes/web' => 'routes/web.php',
        'routes/api' => 'routes/api.php',
        'views/index' => 'resources/views/index.blade.php',
        'views/master' => 'resources/views/components/layouts/master.blade.php',
        'scaffold/config' => 'config/config.php',
        'composer' => 'composer.json',
        'assets/js/app' => 'resources/assets/js/app.js',
        'assets/sass/app' => 'resources/assets/sass/app.scss',
        'vite' => 'vite.config.js',
        'package' => 'package.json',
    ],
    // ...
],
  • enabled 为 false 时使用包内置模板;置为 true 并自定义 path 即可使用自己的模板目录(也可以通过 php artisan vendor:publish --tag=stubs 先发布)。
  • files 定义了生成模块时默认创建的文件及其目标路径。
  • replacements 定义模板占位符的替换规则,例如 routes/web 替换 LOWER_NAME、STUDLY_NAME、PLURAL_LOWER_NAME、KEBAB_NAME、MODULE_NAMESPACE、CONTROLLER_NAMESPACE,composer 还额外支持 VENDOR、AUTHOR_NAME、AUTHOR_EMAIL、APP_FOLDER_NAME 等。
  • 从配置注释可以看出,replacements 支持自定义替换类:将大写 KEY 映射为继承 Nwidart\Modules\Support\ReplacementKeyCommand 的类,该类实现 handle(): string 返回替换文本,从而注入动态值(对应源码 ModuleGenerator.php 的分支处理)。
  • gitkeep 为 true 时,生成的空目录会放入 .gitkeep 文件。

5.3 自动发现与注册开关

  • auto-discover.migrations(默认 true):自动把所有已启用模块的迁移目录注册到 Laravel Migrator。LaravelModulesServiceProvider.php 通过 collect(Module::allEnabled()) 遍历模块并调用 $migrator->path(...) 完成注册。
  • auto-discover.translations(默认 false):为已启用模块的语言目录注册翻译命名空间与 JSON 路径(对应 LaravelModulesServiceProvider.php)。
  • register.translations(默认 true):控制模块自身 boot() 时是否加载 Resources/lang 翻译(见 src/Module.php)。
  • register.files(默认 'register'):决定模块清单中 files 字段在 register 还是 boot 阶段加载。

5.4 激活器(Activator)

'activators' => [
    'file' => [
        'class' => FileActivator::class,
        'statuses-file' => base_path('modules_statuses.json'),
    ],
],
'activator' => 'file',

模块的启用/禁用状态由 Activator 管理。默认使用文件激活器 src/Activators/FileActivator.php,状态持久化在项目根目录的 modules_statuses.json 中;配置注释也提示可以扩展数据库等类型的激活器(唯一必需参数是 class)。服务容器会在 LaravelModulesServiceProvider.php 中按 modules.activator 指定的类型实例化对应激活器。

5.5 其他配置

  • vapor_maintenance_mode:Vapor 环境下把缓存 services 路径切换到可写位置(env('VAPOR_MAINTENANCE_MODE', false))。
  • commands:通过 ConsoleServiceProvider::defaultCommands()->merge([...]) 决定注册哪些 Artisan 命令,可在此追加自定义命令。
  • scan:enabled(默认 false)与 paths(默认 base_path('vendor/*/*')),用于从 vendor 目录扫描模块。
  • composer:生成 composer.json 时使用的 vendor(env('MODULE_VENDOR', 'nwidart'))与作者信息(MODULE_AUTHOR_NAME / MODULE_AUTHOR_EMAIL),composer-output 控制是否输出 composer 命令结果。
  • inertia:默认前端框架,支持 "vue"、"react"、"svelte",默认 "vue",供 Inertia 相关 make 命令在未指定 --vue/--react/--svelte 时使用。

六、命令行工具一览

所有默认命令在 src/Providers/ConsoleServiceProvider.php 的 defaultCommands() 中注册,可分为以下几类:

Actions(模块状态与运维):module:enable、module:disable、module:list、module:use、module:unuse、module:install、module:update、module:delete、module:dump、module:list-commands、module:check-lang、module:model-show、module:model-prune。

Database(模块级数据库操作):module:migrate、module:migrate-fresh、module:migrate-refresh、module:migrate-reset、module:migrate-rollback、module:migrate-status、module:seed。

Make(模块内代码生成):module:make 及其衍生命令,包括 module:make-controller、module:make-model、module:make-migration、module:make-seed、module:make-provider、module:make-event、module:make-listener、module:make-job、module:make-mail、module:make-notification、module:make-request、module:make-resource、module:make-rule、module:make-policy、module:make-middleware、module:make-command、module:make-test、module:make-factory、module:make-observer、module:make-enum、module:make-cast、module:make-exception、module:make-interface、module:make-trait、module:make-service、module:make-action、module:make-class、module:make-helper、module:make-repository、module:make-replacement、module:make-scope、module:make-channel、module:make-component、module:make-component-view、module:make-view、module:make-event-provider、module:make-route-provider、module:make-inertia-page、module:make-inertia-component 等。

Publish(资源发布):module:publish、module:publish-config、module:publish-migration、module:publish-translation、module:publish-inertia。

Other:module:composer-update、module:setup(安装向导)、module:v6:migrate(面向旧版本迁移,见 LaravelModulesV6Migrator.php)、module:update-phpunit-coverage。

常用命令示例

创建模块(同时可生成控制器、迁移、Seeder 等资源):

php artisan module:make Blog

创建纯模块(不含资源文件)或 API 模块、Inertia 模块:

php artisan module:make Blog --plain
php artisan module:make Blog --api
php artisan module:make Blog --inertia

相关选项在 ModuleMakeCommand.php 中定义,还包括 --disabled(创建后不启用)、--force(已存在时强制覆盖)、--author-name/--author-email/--author-vendor(覆盖 composer.json 作者信息)。

启用与禁用模块:

php artisan module:enable Blog
php artisan module:disable Blog

查看模块列表、切换当前操作的模块上下文:

php artisan module:list
php artisan module:use Blog

针对模块执行迁移与数据填充:

php artisan module:migrate Blog
php artisan module:seed Blog

注意:src/Facades/Module.php 提供 Module::prohibitDestructiveCommands(),可一键禁用 module:migrate-fresh、module:migrate-refresh、module:migrate-reset 三个破坏性命令,适用于生产环境防护。

七、模块生命周期与启用状态管理

状态机与事件

src/Module.php 定义了模块的核心生命周期:

  • isEnabled() / isDisabled() 通过激活器查询当前状态;
  • enable() 依次触发 modules.{lower_name}.enabling 与 modules.{lower_name}.enabled 事件,disable() 对应 disabling / disabled(事件常量定义在 src/Constants/ModuleEvent.php);
  • delete() 触发 deleting / deleted 事件,并删除整个模块目录。

以 module:enable Blog 为例,EnableCommand.php 会先展示当前状态,再调用 $module->enable()——命令的输入输出可通过 EnableCommandTest.php 及快照文件验证。

文件激活器的工作方式

src/Activators/FileActivator.php 将模块名映射为布尔值,以 JSON 形式写入 modules_statuses.json(JSON_PRETTY_PRINT)。读取时若文件不存在视为全空;hasStatus() 对未记录模块默认返回"未启用"(即 $status === false 时为 true)。启用/禁用/删除模块都会触发一次 writeJson() 持久化。FileActivatorTest.php 及其快照(snapshots)对状态文件的读写行为有完整覆盖。

八、辅助函数与 Facade

全局辅助函数

src/helpers.php 提供开箱即用的全局函数:

// 判断模块是否启用(默认返回 bool;第二个参数传 true 返回模块实例)
module('Blog');              // bool
module('Blog', true);        // Module 实例

// 拼接模块内路径
module_path('Blog', 'Http/Controllers/BlogController.php');

// Vite 资源入口(支持按模块隔离构建目录与热更新文件)
module_vite('Blog', 'resources/js/app.js');

其中 module() 通过 app('modules') 获取仓储实例,模块不存在时安全返回 false。

Module Facade

Module 门面(src/Facades/Module.php)代理到 modules 容器别名,即 LaravelFileRepository,可调用 Module::all()、Module::allEnabled()、Module::find('Blog')、Module::enable('Blog')、Module::assetPath('Blog')、Module::getOrdered() 等方法(完整方法签名见 Facade 的 @method 注释块)。

Blade 指令

src/LaravelModulesServiceProvider.php 在 boot() 中注册了 @module() Blade 指令,用于视图条件渲染:

@module('Blog')
    {{-- 仅当 Blog 模块启用时渲染 --}}
@endmodule

版本信息

同一提供者还通过 AboutCommand::add('Laravel-Modules', ...) 把包版本写入 php artisan about 输出,方便在命令行快速核对安装版本。

九、模块内部的结构与标准 ServiceProvider

由 module:make 生成的模块,其 module.json 中的 providers 指向模块自己的 ServiceProvider(见 json.stub 与 ModuleGenerator.php)。包为此提供了基类 src/Support/ModuleServiceProvider.php,它要求子类定义 $name 与 $nameLower 两个属性,并在 boot() 中自动完成:

  • 注册模块命令($commands 数组)与命令调度(通过可选 configureSchedules(Schedule $schedule) 方法);
  • 注册翻译(resource_path('lang/modules/{nameLower}') 或模块内 lang 路径);
  • 递归合并模块 config/ 目录下的 PHP 配置(自动去重相邻段,config.php 映射到 config/{nameLower}.php 并支持发布);
  • 注册视图命名空间与 View\Components 组件命名空间;
  • 加载模块迁移目录。

与之配套的 provider.stub 是生成的 ServiceProvider 模板;web.stub 展示了模块路由文件模板——默认在 auth、verified 中间件组内注册资源路由,并以 $PLURAL_LOWER_NAME$、$LOWER_NAME$ 等占位符完成命名。

十、测试与质量保障

相对已停止维护的 pingpong/modules,测试是 laravel-modules 的核心卖点。仓库测试组织清晰:

composer.json 的 scripts 提供 composer test(phpunit)、composer lint(pint)等质量入口,require-dev 中还包括 phpstan、php-cs-fixer 与 spatie/phpunit-snapshot-assertions。这意味着你可以放心升级主版本,回归成本由测试体系兜底。

总结

laravel-modules 的核心价值在于:把"目录分块"升级为"自包含模块",并通过 module.json 清单、Composer 合并插件自动加载、Manifest 批量注册、Activator 状态管理四条主线,让模块的创建、启用、禁用、删除与迁移都变得可命令化、可配置化。使用本文档时,请以 README 中的版本兼容表确定安装版本,在 Laravel 11 及以上记住"不再需要 Modules\\ PSR-4 前缀、改用 composer-merge-plugin"这一关键差异,再结合 config/config.php 的配置说明与 src 源码按需定制,即可在大型项目中落地一套稳定、可测试的模块化架构。

登录后查看全文
laravel-modules