跳到主要内容

模块

超级管理员 → 模块 页面显示在您的 LeadHub 安装中已注册的所有自定义模块的状态。

LeadHub 不附带任何内置功能模块 — 模块系统是一个面向开发者的扩展点，允许您在不修改核心代码库的情况下向平台添加新功能。

什么是模块系统？​

LeadHub 使用 nWidart/laravel-modules 实现 HMVC（分层模型-视图-控制器） 架构。

HMVC 将代码组织为自包含模块，每个模块都有各自的路由、控制器、模型、视图、数据库迁移和服务提供者——本质上是一个加载到主应用程序中的 Laravel 迷你应用。这意味着：

  • 您可以添加全新功能（新的 UI 页面、新的 API 端点、新的后台任务），而无需编辑核心代码。
  • 模块可以在运行时从超级管理员面板启用或禁用，也可以通过 modules_statuses.json 进行管理。
  • 每个模块独立版本化，并可声明对其他模块的依赖关系。

安装（LeadHub 已内置）​

该软件包已在 LeadHub 中安装并配置完成。如需验证：

composer show nwidart/laravel-modules

模块配置文件位于 config/modules.php，模块存储在项目根目录的 Modules/ 文件夹下。

创建您的第一个模块​

# 创建一个新模块
php artisan module:make MyFeature

# 一次性创建多个模块
php artisan module:make ModuleA ModuleB ModuleC

# 创建不带默认样板文件的模块（最简结构）
php artisan module:make MyFeature --plain

运行 module:make 后，您的模块将在 Modules/MyFeature/ 下创建并自动注册。

模块样板结构​

Modules/
  MyFeature/
    app/
      Http/
        Controllers/      # 路由控制器
        Middleware/        # 模块级中间件
        Requests/          # 表单请求类
      Models/              # Eloquent 模型
      Providers/
        MyFeatureServiceProvider.php   # 主服务提供者（自动加载）
        RouteServiceProvider.php       # 加载 routes/web.php + routes/api.php
    config/
      config.php           # 模块级配置
    database/
      migrations/          # 模块迁移文件（与核心隔离）
      seeders/
      factories/
    resources/
      views/               # Blade 模板
      lang/                # 翻译字符串
      assets/              # JS/CSS（通过 Vite 编译）
    routes/
      web.php              # Web 路由（加载于 'web' 中间件组）
      api.php              # API 路由（加载于 'api' 中间件组）
    tests/                 # 功能测试与单元测试
    module.json            # 模块元数据及依赖声明
    composer.json          # 此模块命名空间的 PSR-4 自动加载

关键文件说明​

module.json​

定义模块的标识和加载顺序：

{
    "name": "MyFeature",
    "alias": "myfeature",
    "description": "Adds custom feature X to LeadHub",
    "keywords": [],
    "priority": 0,
    "providers": [
        "Modules\\MyFeature\\Providers\\MyFeatureServiceProvider"
    ],
    "requires": []
}
  • priority — 控制加载顺序；数字越小越先加载。当您的模块依赖其他模块时使用此字段。
  • requires — 本模块所依赖的模块别名列表。LeadHub 在加载前会强制检查依赖关系。

MyFeatureServiceProvider.php​

您模块的入口点。在此处注册路由、中间件、视图、翻译和绑定。自动生成的服务提供者已调用 RouteServiceProvider，并自动注册模块的视图和翻译。

config/config.php​

模块级配置。通过以下方式访问：

config('myfeature.some_key');

使用 Laravel 标准的配置发布方式，按环境发布并覆盖配置。

常用 Artisan 生成器​

# Controllers、Models、Migrations
php artisan module:make-controller MyController MyFeature
php artisan module:make-model MyModel MyFeature
php artisan module:make-migration create_my_table MyFeature

# Requests、Middleware、Policies
php artisan module:make-request StoreMyRequest MyFeature
php artisan module:make-middleware CheckSomething MyFeature
php artisan module:make-policy MyPolicy MyFeature

# Jobs、Events、Listeners、Mail
php artisan module:make-job ProcessSomething MyFeature
php artisan module:make-event SomethingHappened MyFeature
php artisan module:make-listener HandleSomething MyFeature
php artisan module:make-mail WelcomeMail MyFeature

# Artisan 命令
php artisan module:make-command MyCommand MyFeature

运行迁移与数据填充​

模块迁移与核心迁移分开存储，可独立运行：

# 迁移所有模块
php artisan module:migrate

# 迁移指定模块
php artisan module:migrate MyFeature

# 回滚
php artisan module:migrate-rollback MyFeature

# 数据填充
php artisan module:seed MyFeature

启用与禁用模块​

通过命令行：

php artisan module:enable MyFeature
php artisan module:disable MyFeature
php artisan module:list          # 显示所有模块及其状态

通过超级管理员 → 模块：使用每个已注册模块旁边的切换开关。

模块状态持久化保存在项目根目录的 modules_statuses.json 文件中 — 请将此文件提交到版本控制。

多租户注意事项​

LeadHub 是多租户系统。构建模块时，请注意以下几点：

  • 租户范围迁移：如果您的迁移需要创建租户级别的数据表，请在租户上下文中执行 module:migrate。
  • 服务提供者隔离：在模块的服务提供者内注册中间件、策略和事件监听器，避免污染全局作用域。
  • 功能门控：将模块启用/禁用开关与 LeadHub 的套餐系统结合使用 — 可全局禁用某模块，或将其限制在特定套餐层级。

相关内容​