CatchAdmin 模块化开发

CatchAdmin 模块化架构详解，让业务功能开发更高效、更灵活

在使用 CatchAdmin 进行项目开发前，首先需要了解系统最核心的设计理念——模块化架构。CatchAdmin 将所有业务功能都拆分为独立的功能模块，每个模块具有完整的 MVC 结构，支持独立开发、测试和部署。这种设计让开发者能够：

• 高效协作：不同开发者可以并行开发不同模块
• 代码复用：开发完成的模块可以在项目间共享
• 维护便捷：模块间解耦，降低维护成本
• 扩展灵活：根据业务需求随时添加或移除模块

重要提醒

CatchAdmin 的模块信息统一存储在 storage/app/modules.json 配置文件中。如果遇到以下问题，请首先检查此文件：

• 模块路由无法访问
• 模块功能突然失效
• 模块在管理界面中消失

该文件是模块系统的核心配置，务必妥善备份和维护。

CatchAdmin 模块工作原理

CatchAdmin 采用类似 Laravel Package 的模块管理机制。所有模块都存放在项目的 modules 目录下，每个模块都是一个独立的功能单元。

模块安装：通过 Artisan 命令快速安装模块

php artisan catch:module:install <module>

安装流程：

1. 命令执行后在 storage/app 目录生成 modules.json 配置文件
2. 系统自动注册模块的服务提供者、路由和其他资源
3. 模块立即可用，无需重启应用

CatchAdmin 的模块系统借鉴了 Laravel 社区的成熟设计理念，从 2.x 到 3.x 版本保持了良好的兼容性，让有经验的开发者能够快速上手。

实战：开发新模块

以下通过创建一个实际模块来演示 CatchAdmin 模块开发的完整流程。

第一步：创建模块

CatchAdmin 提供了可视化的模块创建界面，让模块初始化变得简单直观：

1. 进入 CatchAdmin 后台管理界面
2. 导航到"开发工具" → "模块管理"
3. 点击"新建模块"，填写模块基本信息：
   • 模块名称（如：test）
   • 模块描述
   • 模块关键词
   • 开发者信息
4. 点击"创建"按钮

系统将自动生成完整的模块文件结构，以 test 模块为例：

生成的模块结构分析：

modules/Test/
├── Http/              # 控制器层：处理 HTTP 请求和响应
├── Models/            # 数据模型层：数据库交互和业务逻辑
├── database/          # 数据库相关
│   ├── migrations/    # 数据库迁移文件
│   └── seeds/         # 数据填充文件
├── Providers/         # 服务提供者：模块的核心注册点
└── route.php          # 路由定义文件

核心组件说明：

• Http 目录：存放控制器和中间件，处理业务逻辑
• Models 目录：数据模型，定义数据结构和关系
• database 目录：数据库相关文件，支持版本控制
• Providers 目录：服务提供者，类似 Laravel Package 的核心机制
• route.php：模块路由定义，支持 RESTful API 设计

深入理解服务提供者（Provider）

服务提供者是 CatchAdmin 模块的核心，负责模块的初始化和资源注册：

namespace Modules\Test\Providers;

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

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

Provider 功能特性：

CatchAdmin 的服务提供者继承自 CatchModuleServiceProvider，默认自动加载模块路由。同时提供以下扩展功能：

1. 事件系统集成

CatchAdmin 支持模块级别的事件监听，与 Laravel 事件系统完全兼容。通过 $events 数组注册模块专属事件：

class TestServiceProvider extends CatchModuleServiceProvider
{
    protected $events = [];
}

2. 中间件支持

模块可以注册中间件，用于权限验证、数据过滤等场景。实现 middlewares 方法即可：

class TestServiceProvider extends CatchModuleServiceProvider
{
    protected function middlewares(): array
    {
        return [];
    }
}

中间件注意事项

通过 Provider 注册的中间件会作用于整个应用，而非仅当前模块。因此在注册全局中间件时需要谨慎考虑其影响范围，避免对其他模块造成不必要的限制。

建议：优先在路由级别使用中间件，只在确实需要全局作用时才在 Provider 中注册。

模块分发与安装器

模块共享

如果开发的模块仅供当前项目使用，可以跳过此部分。 以下内容适用于希望将模块贡献给 CatchAdmin 社区或在多个项目间复用的场景。

为什么需要安装器？

CatchAdmin 的模块安装器（Installer）是实现模块标准化分发的关键组件。它解决了以下问题：

• 模块依赖管理（Composer 包）
• 数据库结构同步（migrations）
• 配置文件处理
• 权限菜单导入

安装器实现

安装器通常放置在模块根目录下，以权限模块为例：

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.
    }
}

安装器核心方法说明：

1. info() 方法：定义模块基本信息，包括名称、描述、关键词等
2. requirePackages() 方法：处理模块依赖的 Composer 包
3. removePackages() 方法：卸载时清理相关依赖

依赖包管理示例：

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

权限菜单导出

对于包含后台管理功能的模块，CatchAdmin 提供了菜单导出命令，自动生成权限相关的 seed 文件：

php artisan catch:export:menu <module> <table?>

• table 可选参数，默认是 permissions 表

使用场景：

• 模块包含后台管理界面
• 需要自定义权限控制
• 计划分发给其他开发者使用

示例：导出权限模块的完整菜单结构

php artisan catch:export:menu permissions

模块分发流程总结：

1. ✅ 完善模块功能开发
2. ✅ 创建标准化安装器
3. ✅ 导出权限菜单（如需要）
4. ✅ 编写模块使用文档
5. ✅ 测试安装和卸载流程

完成以上步骤后，你的模块就可以与 CatchAdmin 社区分享了！👏

社区贡献：欢迎开发者将优质模块贡献给社区，共同构建更强大的 CatchAdmin 生态系统。