README

基于 Hyperf 框架的模块化开发组件，提供完整的模块管理解决方案，支持注解路由和配置文件路由两种方式，严格遵循 Hyperf 组件开发规范。

特性

✅ 完整的模块生命周期管理
✅ 独立的 composer.json 管理
✅ 支持注解路由和配置文件路由
✅ ConfigProvider 机制集成
✅ 命令行工具支持
✅ 模块启用/禁用控制
✅ 自动配置加载
✅ 遵循 Hyperf 组件开发规范

安装

composer require molong/modules
composer require wikimedia/composer-merge-plugin

安装完成后，需要在主项目的 composer.json 中配置合并插件。

5. 配置 Composer Merge Plugin

在主项目的 composer.json 中添加插件配置：

{
    "require": {
        "molong/modules": "^1.0",
        "wikimedia/composer-merge-plugin": "^2.0"
    },
    "extra": {
        "merge-plugin": {
            "include": [
                "modules/*/composer.json"
            ],
            "replace": false,
            "ignore-duplicates": false,
            "merge-extra": false,
            "merge-extra-deep": false,
            "merge-scripts": false
        }
    }
}

配置说明：

include：指定要合并的 composer.json 文件路径，支持 glob 模式
replace：是否替换主项目中已有的配置项（false 表示模块配置会被主项目覆盖）
ignore-duplicates：是否忽略重复的配置项
merge-extra：是否合并 extra 字段
merge-extra-deep：是否深度合并 extra 字段
merge-scripts：是否合并 scripts 字段

6. 运行 Composer 命令

配置完成后，运行以下命令来应用合并：

composer update

或者只更新自动加载：

composer dump-autoload

插件会自动将所有模块的 composer.json 合并到主项目中。

配置

1. 发布配置文件

使用 Hyperf 的配置发布机制发布配置文件：

php bin/hyperf.php vendor:publish molong/modules

这会将配置文件发布到 config/autoload/modules.php。

2. 配置文件说明

配置文件位于 config/autoload/modules.php：

<?php

return [
    'path' => BASE_PATH . '/modules',  // 模块存放路径
    'namespace' => 'Modules',           // 模块基础命名空间
    'autoload' => true,                 // 是否自动加载模块的 composer.json
    'enabled' => [],                    // 启用的模块（留空启用所有）
    'disabled' => [],                   // 禁用的模块
];

3. 创建模块目录

mkdir -p modules

4. 模块启用/禁用配置

enabled：指定要启用的模块列表，如果为空则启用所有模块
disabled：指定要禁用的模块列表，优先级高于 enabled

示例：

return [
    // 只启用 User 和 Order 模块
    'enabled' => ['User', 'Order'],
    'disabled' => [],
];

// 或启用所有模块，但禁用 Example 模块
return [
    'enabled' => [],
    'disabled' => ['Example'],
];

使用

创建模块

使用命令行工具创建新模块：

# 使用注解路由（默认）
php bin/hyperf.php module:make User

# 使用配置文件路由
php bin/hyperf.php module:make User --routing=config

# 同时支持两种路由方式
php bin/hyperf.php module:make User --routing=both

查看模块列表

php bin/hyperf.php module:list

启用模块

php bin/hyperf.php module:enable User

禁用模块

php bin/hyperf.php module:disable User

创建数据迁移文件

# 为指定模块创建迁移文件
php bin/hyperf.php module:migrate-make User create_users_table

这会在 modules/User/src/database/migrations/ 目录下创建一个新的迁移文件。

执行数据迁移

# 运行指定模块的所有迁移
php bin/hyperf.php module:migrate User

创建数据填充文件

# 为指定模块创建数据填充文件
php bin/hyperf.php module:seed-make User UserSeeder

这会在 modules/User/src/database/seeders/ 目录下创建一个新的 seeder 文件。

执行数据填充

# 运行指定模块的所有 seeders
php bin/hyperf.php module:seed User

# 运行指定模块的特定 seeder
php bin/hyperf.php module:seed User UserSeeder

更新自动加载

添加新模块后，需要更新自动加载：

composer dump-autoload

wikimedia/composer-merge-plugin 会自动合并所有模块的 composer.json 到主项目中。

发布配置文件

# 发布指定模块的配置文件到 config/autoload/
php bin/hyperf.php module:publish User

# 发布特定类型的配置（目前只支持 config）
php bin/hyperf.php module:publish User --tag=config

配置文件发布后，可以在项目的 config/autoload/ 目录下找到并修改这些配置文件。

模块结构

创建的模块遵循以下目录结构：

User/
├── src/
│   ├── app/                     # 功能代码目录
│   │   ├── Http/               # Http相关
│   │   │   ├── Controllers/    # 控制器
│   │   │   ├── Middleware/     # 中间件
│   │   │   └── Requests/       # 请求验证
│   │   ├── Model/              # 模型
│   │   └── Service/            # 服务层
│   ├── config/                 # 配置文件
│   │   ├── routes.php          # 路由配置（仅配置文件路由时使用）
│   │   └── {模块名}.php       # 模块配置文件
│   ├── tests/                  # 测试文件
│   ├── database/               # 数据库迁移
│   │   ├── migrations/          # 迁移文件
│   │   └── seeders/            # 数据填充文件
│   └── ConfigProvider.php      # 配置提供者
├── composer.json                # Composer 配置
└── README.md                    # 模块文档

路由方式

1. 注解路由

在控制器中使用 Hyperf 的路由注解：

<?php
declare(strict_types=1);

namespace Modules\User\Http\Controllers;

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Psr\Http\Message\ResponseInterface;

#[Controller]
class UserController
{
    #[GetMapping(path: '/modules/user/list')]
    public function list(): ResponseInterface
    {
        return response()->json(['data' => []]);
    }
}

2. 配置文件路由

在 config/routes.php 中配置路由：

<?php
declare(strict_types=1);

use Hyperf\HttpServer\Router\Router;

Router::addGroup('/modules/user', function () {
    Router::get('/list', [Modules\User\Http\Controllers\UserController::class, 'list']);
    Router::post('/create', [Modules\User\Http\Controllers\UserController::class, 'create']);
});

3. 混合使用

模块可以同时使用两种路由方式，在创建时使用 --routing=both 选项。

ConfigProvider 机制

每个模块都包含一个 ConfigProvider 类，用于注册模块的配置：

<?php
declare(strict_types=1);

namespace User;

class ConfigProvider
{
    public function __invoke(): array
    {
        return [
            // 依赖注入
            'dependencies' => [
                // ...
            ],
            // 命令行工具
            'commands' => [
                // ...
            ],
            // 注解扫描路径
            'annotations' => [
                'scan' => [
                    'paths' => [
                        __DIR__,
                    ],
                ],
            ],
            // 监听器
            'listeners' => [
                // ...
            ],
            // 中间件
            'middlewares' => [
                // ...
            ],
            // 进程
            'processes' => [
                // ...
            ],
        ];
    }
}

模块开发规范

1. 命名规范

模块名称：大驼峰命名（如：User, Order, Payment）
命名空间：Modules\{模块名}
控制器：Modules\{模块名}\Http\Controllers\{控制器名}Controller
中间件：Modules\{模块名}\Http\Middleware\{中间件名}Middleware
请求验证：Modules\{模块名}\Http\Requests\{请求名}Request
服务：Modules\{模块名}\Service\{服务名}Service
模型：Modules\{模块名}\Model\{模型名}

2. 目录规范

{模块名}/
├── src/
│   ├── app/                     # 功能代码目录
│   │   ├── Http/               # Http相关
│   │   │   ├── Controllers/    # 控制器层
│   │   │   ├── Middleware/     # 中间件
│   │   │   └── Requests/       # 请求验证
│   │   ├── Model/              # 数据模型层
│   │   ├── Service/            # 服务层
│   │   ├── Exception/          # 异常类
│   │   └── Listener/           # 监听器
│   ├── config/                 # 配置文件
│   ├── tests/                  # 单元测试
│   ├── database/               # 数据库迁移文件
│   │   └── migrations/
│   └── resources/              # 资源文件（可选）
├── composer.json                # Composer 配置
└── README.md                    # 模块文档

3. Composer.json 规范

每个模块的 composer.json 必须包含：

{
    "name": "user/module",
    "type": "hyperf-component",
    "description": "Hyperf User module",
    "license": "MIT",
    "autoload": {
        "psr-4": {
            "Modules\\User\\": "src/app/"
        }
    },
    "extra": {
        "hyperf": {
            "config": "Modules\\User\\ConfigProvider"
        }
    }
}

最佳实践

1. 模块独立性

每个模块应该尽可能独立，避免模块间的直接依赖。如果需要依赖其他模块，建议通过接口定义依赖关系。

2. 配置管理

模块配置应该通过 ConfigProvider 统一管理，避免在模块外部直接修改配置。

3. 路由规划

使用注解路由：适合简单、直观的路由定义
使用配置文件路由：适合复杂、需要统一管理的路由
混合使用：根据实际需求灵活选择

4. 依赖注入

使用 Hyperf 的依赖注入容器管理模块依赖，避免直接实例化对象。

5. 测试覆盖

为模块编写完整的单元测试，确保模块功能的稳定性和可靠性。

高级用法

1. 模块间通信

通过服务接口实现模块间通信：

// 在一个模块中定义接口
namespace User\Contracts;

interface UserServiceInterface
{
    public function getUser(int $id): array;
}

// 在另一个模块中使用
use User\Contracts\UserServiceInterface;

class OrderService
{
    public function __construct(
        private UserServiceInterface $userService
    ) {}
    
    public function getOrderUser(int $orderId): array
    {
        // 通过接口调用用户模块的服务
        return $this->userService->getUser($userId);
    }
}

2. 模块事件

使用 Hyperf 的事件机制实现模块间解耦：

// 定义事件
namespace User\Event;

class UserCreated
{
    public function __construct(
        public readonly int $userId
    ) {}
}

// 在模块中发布事件
use Hyperf\Event\EventDispatcher;
use User\Event\UserCreated;

$eventDispatcher->make(UserCreated::class, ['userId' => $userId]);

3. 模块配置

创建模块特定的配置文件：

// config/modules/user.php
return [
    'cache_ttl' => 3600,
    'max_retry' => 3,
];

在模块中读取配置：

use Hyperf\Config\Annotation\Value;

class UserService
{
    #[Value('modules.user.cache_ttl')]
    private int $cacheTtl;
}

故障排查

1. 模块未加载

检查以下几点：

模块目录是否在正确的路径下
composer.json 配置是否正确
ConfigProvider 是否存在且格式正确

2. 路由不生效

检查路由配置文件是否存在
确认路由注解语法是否正确
查看路由是否被正确注册

3. 类找不到

运行 composer dump-autoload
检查命名空间是否正确
确认文件路径与命名空间对应

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT License

联系方式

作者：Molong
邮箱：your-email@example.com
GitHub：https://github.com/yourusername/hyperf-modules

molong / modules

Maintainers

Package info

Statistics

Security