# hyperf-modules

**Repository Path**: ycgpp/hyperf-modules

## Basic Information

- **Project Name**: hyperf-modules
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hyperf 模块化开发组件

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

## 特性

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

## 安装

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

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

### 5. 配置 Composer Merge Plugin

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

```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 命令

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

```bash
composer update
```

或者只更新自动加载：

```bash
composer dump-autoload
```

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

## 配置

### 1. 发布配置文件

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

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

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

### 2. 配置文件说明

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

```php
<?php

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

### 3. 创建模块目录

```bash
mkdir -p modules
```

### 4. 模块启用/禁用配置

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

示例：

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

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

## 使用

### 创建模块

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

```bash
# 使用注解路由（默认）
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
```

### 查看模块列表

```bash
php bin/hyperf.php module:list
```

### 启用模块

```bash
php bin/hyperf.php module:enable User
```

### 禁用模块

```bash
php bin/hyperf.php module:disable User
```

### 创建数据迁移文件

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

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

### 执行数据迁移

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

### 创建数据填充文件

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

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

### 执行数据填充

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

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

### 更新自动加载

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

```bash
composer dump-autoload
```

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

### 发布配置文件

```bash
# 发布指定模块的配置文件到 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
<?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
<?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
<?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` 必须包含：

```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. 模块间通信

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

```php
// 在一个模块中定义接口
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 的事件机制实现模块间解耦：

```php
// 定义事件
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. 模块配置

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

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

在模块中读取配置：

```php
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

## 参考文档

- [Hyperf 官方文档](https://hyperf.wiki)
- [Hyperf 组件开发指南](https://hyperf.wiki/zh-cn/component/)