CatchAdmin 专业版文档

主题

CatchAdmin 模块化开发指南 ​

在开始使用 CatchAdmin 做后台项目开发前，首先需要深入了解 CatchAdmin 框架的一个最核心功能 - 模块化架构。CatchAdmin 采用了先进的模块化设计理念，将后台系统中的所有业务功能都拆分为独立的、可重用的功能模块。这种组件化架构使得开发者之间可以方便地进行模块共享和协作开发。

CatchAdmin 模块化架构如何工作 ​

CatchAdmin 框架的模块化组件通常存放在 modules 目录下，采用类似 Laravel Package 的组织结构。通过下面的 Artisan 命令可以方便地进行模块安装管理

shell
php artisan catch:module:install

根据 Artisan 命令行控制台显示的交互式提示，选择相应的 CatchAdmin 模块组件进行安装

CatchAdmin 模块安装命令运行完成后，系统会在 storage/app 目录下自动生成 module.json 模块配置文件，该 JSON 文件包含了所有已安装模块的详细信息和状态数据。 Laravel Admin - catchadmin模块架构图

为了深入了解 CatchAdmin 模块化开发的具体工作流程，下面通过一个完整的新模块开发示例来详细说明

CatchAdmin 模块化组件开发实战 ​

CatchAdmin 模块化开发可以通过可视化的模块创建工具开始 Laravel Admin - catchadmin 创建模块

在 CatchAdmin 后台管理系统中，点击开发工具的模块管理菜单，然后选择新建模块功能。按照模块化开发规范填入模块的相关信息（模块名、描述、依赖关系等）后，点击创建即可。自动生成模块化组件的标准目录结构和文件。以下以创建一个 test 模块为例 Laravel Admin - catchadmin 管理模块Laravel Admin - catchadmin 管理模块 如图可以看到已经生成了Test模块

  • Http 目录：CatchAdmin 模块的主要开发区域，包含控制器和中间件
  • Models 数据模型存放目录，遵循 Laravel Eloquent ORM 规范
  • database 数据库相关目录，包含 migration 数据迁移和 seed 数据填充脚本
  • Providers 模块服务提供者，这是模块化架构的核心，路由注册、Artisan 命令、配置加载都需要通过服务提供者进行
  • route.php 模块路由配置文件。这个也可以当作模块路由的入口文件。后期如果拆分路由，例如你拆开一个 api.php，只需要在 route.php 种 require api.php 即可加载 api 路由
  • Installer.php 模块安装器，管理模块的安装和卸载逻辑 下面深入解析 CatchAdmin 模块化架构中最关键的 ServiceProvider 组件
php
namespace Modules\Test\Providers;

use Catch\CatchAdmin;
use Catch\Providers\CatchModuleServiceProvider;

class TestServiceProvider extends CatchModuleServiceProvider
{
    public function moduleName(): string|array
    {
        return 'common';
    }
}

在 CatchAdmin 模块化架构中，ServiceProvider 默认情况下会自动进行路由注册和加载。除了基本的路由管理，还额外提供了多个高级功能

  • 事件管理 在 CatchAdmin 模块中集成 Laravel 事件系统，如果需要为模块注册特定的事件监听器，这个功能与 Laravel 框架提供的默认事件机制保持一致。ServiceProvider 提供了一个标准化的 $events 数组配置
php
class TestServiceProvider extends CatchModuleServiceProvider
{
    protected $events = [];
}
  • HTTP 中间件 如果需要为 CatchAdmin 模块注册自定义的 HTTP 中间件组件，需要在 ServiceProvider 中实现 middlewares 方法
php
class TestServiceProvider extends CatchModuleServiceProvider
{
    protected function middlewares(): array
    {
        return [];
    }
}

CatchAdmin 中间件作用域说明

在 ServiceProvider 中注册的 middlewares 是全局生效的，会影响 CatchAdmin 系统中的所有模块路由，因此需要谨慎使用。

如果只需要中间件作用于当前模块，建议直接在模块的路由配置文件中设置即可。

CatchAdmin 模块自动加载机制 ​

CatchAdmin 模块化架构的依赖管理和启动机制依赖于一个核心的配置文件 storage/app/module.json。这个 JSON 配置文件管理着所有模块的状态控制，包括模块的启用、禁用、依赖关系等。 为了提升开发灵活性，CatchAdmin 框架提供了一个可配置的模块自动加载机制，

js
// 在 .env 文件中修改
CATCH_MODULE_AUTOLOAD = true
php
// 在模块配置中修改
[
    'module' => [
        'autoload' => env('CATCH_MODULE_AUTOLOAD', false),
    ],
]

CatchAdmin 模块依赖管理与组件关系 ​

在模块化开发中，某些复杂的业务模块可能需要依赖其他基础模块的功能组件，这时需要在安装时同步检查和安装依赖模块。CatchAdmin 的模块安装器提供了优雅的依赖管理机制。以商城模块的实际开发场景为例

php

namespace Modules\Shop;

use Catch\Support\Module\Installer as ModuleInstaller;
use Modules\Shop\Providers\ShopServiceProvider;

class Installer extends ModuleInstaller
{
    // 添加模块依赖
    protected function dependencies(): array
    {
        return ['member'];
    }
}

CatchAdmin 模块安装与管理命令 ​

shell
php artisan catch:module:install

使用 Artisan 命令行工具进行 CatchAdmin 模块安装，根据控制台显示的可用模块列表选择安装即可

批量安装所有 CatchAdmin 模块 ​

为了提升开发效率，CatchAdmin 支持一次性批量安装所有可用模块组件

shell
php artisan catch:module:install --all

CatchAdmin 模块安装器与组件分享 ​

CatchAdmin 模块分享说明

如果只是为了个人或内部团队开发 CatchAdmin 模块，不需要发布到开源社区的话，可以跳过下面的模块分享配置步骤。

如果希望将自己开发的 CatchAdmin 模块贡献给社区，供其他 PHP 开发者使用，需要为模块创建一个标准化的安装器组件。按照 CatchAdmin 模块化规范，安装器通常约定存放在模块的根目录下。可以参考权限管理模块的安装器实现案例

php
namespace Modules\Permissions;

use Catch\Support\Module\Installer as ModuleInstaller;

class Installer extends ModuleInstaller
{
    protected function info(): array
    {
        // TODO: Implement info() method.
        return [
            'title' => '权限管理',
            'name' => 'permissions',
            'path' => 'permissions',
            'keywords' => '权限, 角色, 部门',
            'description' => '权限管理模块',
            'provider' => PermissionsServiceProvider::class
        ];
    }

    protected function requirePackages(): void
    {
        // TODO: Implement requirePackages() method.
    }

    protected function removePackages(): void
    {
        // TODO: Implement removePackages() method.
    }
}

CatchAdmin 模块安装器需要实现数个关键方法来提供模块元数据信息。主要通过 info 方法返回模块的基本信息，如果模块需要额外的 Composer 包依赖，则需要在 requirePackages 方法中实现依赖包的自动安装逻辑

php
protected function requirePackages(): void
{
    // TODO: Implement requirePackages() method.
    $this->composer()->require('package/name')
}

对于采用动态菜单管理的 CatchAdmin 模块，还需要将模块的后台管理菜单信息导出为可分享的数据格式。CatchAdmin 提供了专用的 Artisan 命令来处理菜单导出

shell
php artisan catch:export:menu <module> <table?>
  • table 参数为可选项，默认指向 CatchAdmin 的 permissions 数据表

对指定的 CatchAdmin 模块进行菜单数据导出，并自动生成相应的 Laravel Seeder 数据填充文件。这个功能主要用于模块打包发布阶段，对于不需要与其他开发者共享的内部模块，可以忽略此步骤

php
php artisan catch:export:menu permissions

完成以上步骤后，就可以将自己开发的 CatchAdmin 模块组件分享给全球的 PHP 开发者使用了！👏 请积极参与 CatchAdmin 开源社区建设，共同推动 PHP 模块化开发的发展。