---
url: /docs/5.0/server/modules.md
---
# CatchAdmin 模块化开发

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

:::info
v5.0 引入了插件机制，完全可以通过把模块打包放到插件市场共享给其他客户。目前 v5 还是保留了模块得概念，主要针对后台模块。
:::

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

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

### CatchAdmin 模块工作原理

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

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

```shell
php artisan catch:module:install <module>
```

**安装流程**：
CatchAdmin 的模块系统借鉴了 Laravel 社区的成熟设计理念，从 2.x 到 5.x 版本保持了良好的兼容性，让有经验的开发者能够快速上手。
![模块架构图](https://z3.ax1x.com/2021/04/26/gSrLz6.png)

### 实战：开发新模块

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

**第一步：创建模块**

CatchAdmin 提供了可视化的模块创建界面，让模块初始化变得简单直观：
![pSlN1y9.md.png](https://s1.ax1x.com/2023/01/16/pSlN1y9.md.png)

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

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

![pSlN2Y8.md.png](https://s1.ax1x.com/2023/01/16/pSlN2Y8.md.png)
![pSlNv6J.png](https://s1.ax1x.com/2023/01/16/pSlNv6J.png)

**生成的模块结构分析**：

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

**核心组件说明**：

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

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

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

```php
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` 数组注册模块专属事件：

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

**2. 中间件支持**

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

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

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

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

### 模块分发与安装器

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

**为什么需要安装器？**

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

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

**安装器实现**

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

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

**安装器核心方法说明**：

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

**依赖包管理示例**：

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

**权限菜单导出**

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

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

* table 可选参数，默认是 `permissions` 表

**使用场景**：

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

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

```php
php artisan catch:export:menu permissions
```

**模块分发流程总结**：

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

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

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