# Kylin Modules 详细开发文档

## 1. 模块介绍

Kylin Modules 是一个为 Laravel 应用提供模块化开发能力的扩展包，它允许开发者将应用拆分为多个独立的模块，每个模块可以包含自己的控制器、模型、视图、路由等，从而实现代码的解耦和复用。

### 核心功能

- **模块化管理**：支持创建、启用、禁用、删除模块
- **自动加载**：自动加载模块的服务提供者、路由、视图、翻译和配置
- **命令行工具**：提供丰富的命令行工具，用于模块的创建和管理
- **依赖管理**：支持模块间的依赖关系管理
- **版本控制**：支持模块的版本管理和更新
- **热插拔**：支持模块的热插拔，无需重启应用即可启用或禁用模块

## 2. 安装与配置

### 2.1 安装

使用 Composer 安装 Kylin Modules：

```bash
composer require kylin/modules
```

### 2.2 配置

安装完成后，需要发布配置文件：

```bash
php artisan vendor:publish --provider="Kylin\Modules\Providers\ModulesServiceProvider"
```

发布后，会在 `config` 目录下生成 `modules.php` 配置文件，您可以根据需要修改配置：

```php
return [
    'path' => base_path('packages'), // 模块存放路径
    'scan' => [
        'paths' => [
            base_path('packages'), // 扫描模块的路径
        ],
    ],
    'enabled' => [], // 启用的模块列表
    'disabled' => [], // 禁用的模块列表
    'defaults' => [
        'namespace' => 'Kylin', // 默认模块命名空间
    ],
];
```

## 3. 目录结构

Kylin Modules 的目录结构如下：

```
kylin/modules/
├── config/            # 配置文件
│   └── modules.php    # 模块配置
├── docs/              # 文档
│   ├── commands.md    # 命令行工具文档
│   ├── configuration.md # 配置文档
│   ├── creating-modules.md # 创建模块文档
│   └── installation.md # 安装文档
├── src/               # 源代码
│   ├── Autoload/      # 自动加载
│   │   └── Autoloader.php # 自动加载器
│   ├── Console/       # 命令行工具
│   │   └── Commands/  # 命令类
│   ├── Exceptions/    # 异常类
│   ├── Facades/       # 门面
│   │   └── Module.php # 模块门面
│   ├── Generators/    # 生成器
│   │   └── ModuleGenerator.php # 模块生成器
│   ├── Helpers/       # 助手函数
│   │   └── helpers.php # 助手函数
│   ├── Providers/     # 服务提供者
│   │   └── ModulesServiceProvider.php # 模块服务提供者
│   ├── Module.php     # 模块类
│   ├── ModuleCollection.php # 模块集合类
│   └── ModuleManager.php # 模块管理器
├── stubs/             # 模板文件
├── tests/             # 测试文件
├── README.md          # 说明文件
├── REFACTORING.md     # 重构说明
└── composer.json      # 包配置
```

## 4. 核心类

### 4.1 ModuleManager

`ModuleManager` 是模块管理的核心类，负责模块的加载、注册和启动：

```php
<?php

namespace Kylin\Modules;

use Illuminate\Container\Container;
use Kylin\Modules\Exceptions\ModuleNotFoundException;
use Kylin\Modules\Exceptions\ModuleAlreadyExistsException;

/**
 * 模块管理器
 *
 * 负责模块的加载、注册、启动和管理
 */
class ModuleManager
{
    // 核心方法...
}
```

**主要方法**：
- `bootstrap()`：引导模块管理器
- `loadModules()`：加载所有模块
- `scanPath(string $path)`：扫描路径中的模块
- `registerModule(string $path)`：注册模块
- `boot()`：启动所有模块
- `all()`：获取所有模块
- `get(string $name, mixed $default = null)`：通过名称获取模块
- `has(string $name)`：检查模块是否存在
- `make(string $name, array $attributes = [])`：创建新模块

### 4.2 Module

`Module` 类代表一个模块实例，负责模块的初始化、验证、启动和管理：

```php
<?php

namespace Kylin\Modules;

use Illuminate\Container\Container;
use Illuminate\Support\Str;
use Kylin\Modules\Exceptions\InvalidModuleException;
use Illuminate\Support\helpers;

/**
 * 模块类
 *
 * 负责模块的初始化、验证、启动和管理
 */
class Module
{
    // 核心方法...
}
```

**主要方法**：
- `boot()`：启动模块
- `registerProviders()`：注册模块提供者
- `registerRoutes()`：注册模块路由
- `registerViews()`：注册模块视图
- `registerTranslations()`：注册模块翻译
- `registerConfig()`：注册模块配置
- `getName()`：获取模块名称
- `getStudlyName()`：获取模块驼峰名称
- `getSnakeName()`：获取模块蛇形名称
- `getPath(string $path = '')`：获取模块路径
- `isEnabled()`：获取模块状态
- `enable()`：启用模块
- `disable()`：禁用模块

### 4.3 ModuleCollection

`ModuleCollection` 类继承自 Laravel 的 `Collection`，用于管理模块集合：

```php
<?php

namespace Kylin\Modules;

use Illuminate\Support\Collection;

/**
 * 模块集合类
 */
class ModuleCollection extends Collection
{
    // 扩展方法...
}
```

## 5. 命令行工具

Kylin Modules 提供了丰富的命令行工具，用于模块的创建和管理：

### 5.1 模块管理命令

- `module:list`：列出所有模块
- `module:make`：创建新模块
- `module:enable`：启用模块
- `module:disable`：禁用模块
- `module:delete`：删除模块
- `module:show`：显示模块信息
- `module:status`：显示模块状态

### 5.2 模块生成命令

- `module:make:controller`：创建控制器
- `module:make:model`：创建模型
- `module:make:migration`：创建迁移文件
- `module:make:seed`：创建种子文件
- `module:make:factory`：创建工厂
- `module:make:request`：创建请求
- `module:make:resource`：创建资源
- `module:make:command`：创建命令
- `module:make:middleware`：创建中间件
- `module:make:policy`：创建策略
- `module:make:rule`：创建规则
- `module:make:event`：创建事件
- `module:make:listener`：创建监听器
- `module:make:job`：创建任务
- `module:make:mail`：创建邮件
- `module:make:notification`：创建通知
- `module:make:provider`：创建服务提供者
- `module:make:component`：创建组件
- `module:make:view`：创建视图
- `module:make:config`：创建配置
- `module:make:lang`：创建语言文件
- `module:make:helper`：创建助手函数
- `module:make:interface`：创建接口
- `module:make:contract`：创建契约
- `module:make:trait`：创建特质
- `module:make:enum`：创建枚举
- `module:make:cast`：创建类型转换
- `module:make:scope`：创建作用域
- `module:make:observer`：创建观察者
- `module:make:broadcast`：创建广播
- `module:make:test`：创建测试
- `module:make:repository`：创建仓库
- `module:make:api-route`：创建 API 路由
- `module:make:route`：创建路由
- `module:make:inertia`：创建 Inertia 页面

### 5.3 模块迁移命令

- `module:migrate`：运行模块迁移
- `module:migrate:refresh`：刷新模块迁移
- `module:migrate:reset`：重置模块迁移
- `module:migrate:rollback`：回滚模块迁移

### 5.4 模块种子命令

- `module:seed`：运行模块种子

### 5.5 模块缓存命令

- `module:cache`：缓存模块
- `module:clear-cache`：清除模块缓存

### 5.6 模块其他命令

- `module:config`：显示模块配置
- `module:copy`：复制模块
- `module:dependency`：显示模块依赖
- `module:doc`：生成模块文档
- `module:export`：导出模块
- `module:health`：检查模块健康状态
- `module:i18n`：管理模块国际化
- `module:import`：导入模块
- `module:init`：初始化模块
- `module:install`：安装模块
- `module:make:all`：创建所有模块文件
- `module:monitor`：监控模块
- `module:publish`：发布模块资源
- `module:quality`：检查模块质量
- `module:queue`：管理模块队列
- `module:route`：显示模块路由
- `module:search`：搜索模块
- `module:security`：检查模块安全
- `module:stats`：显示模块统计信息
- `module:test`：运行模块测试
- `module:uninstall`：卸载模块
- `module:update`：更新模块
- `module:version`：显示模块版本

## 6. 开发指南

### 6.1 创建模块

使用 `module:make` 命令创建新模块：

```bash
php artisan module:make Blog
```

这将在 `packages` 目录下创建一个名为 `blog` 的模块，包含基本的目录结构和文件。

### 6.2 模块目录结构

创建模块后，会生成以下目录结构：

```
packages/blog/
├── composer.json     # 模块配置
├── config/           # 配置文件
├── database/         # 数据库文件
│   ├── migrations/   # 迁移文件
│   └── seeds/        # 种子文件
├── resources/        # 资源文件
│   ├── lang/         # 语言文件
│   └── views/        # 视图文件
├── routes/           # 路由文件
└── src/              # 源代码
    ├── Controllers/  # 控制器
    ├── Models/       # 模型
    └── Providers/    # 服务提供者
```

### 6.3 注册模块

模块创建后，需要在 `composer.json` 文件中注册模块的自动加载：

```json
{
    "name": "kylin/blog",
    "description": "Blog module",
    "type": "library",
    "version": "1.0.0",
    "autoload": {
        "psr-4": {
            "Kylin\Blog\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Kylin\Blog\Providers\BlogServiceProvider"
            ]
        }
    }
}
```

然后运行 `composer dump-autoload` 命令更新自动加载。

### 6.4 启用模块

使用 `module:enable` 命令启用模块：

```bash
php artisan module:enable blog
```

或者在 `config/modules.php` 文件中添加模块到 `enabled` 列表：

```php
'enabled' => [
    'blog',
],
```

### 6.5 开发模块

在模块中，您可以按照 Laravel 的开发规范创建控制器、模型、视图等文件。例如，创建一个控制器：

```bash
php artisan module:make:controller Blog PostController
```

这将在 `packages/blog/src/Controllers` 目录下创建 `PostController.php` 文件。

### 6.6 路由配置

在模块的 `routes` 目录下创建路由文件，例如 `web.php`：

```php
<?php

use Illuminate\Support\Facades\Route;
use Kylin\Blog\Controllers\PostController;

Route::prefix('blog')->group(function () {
    Route::get('/', [PostController::class, 'index'])->name('blog.index');
    Route::get('/{id}', [PostController::class, 'show'])->name('blog.show');
});
```

### 6.7 视图配置

在模块的 `resources/views` 目录下创建视图文件，例如 `index.blade.php`：

```blade
@extends('layouts.app')

@section('content')
    <h1>Blog Posts</h1>
    @foreach($posts as $post)
        <div class="post">
            <h2>{{ $post->title }}</h2>
            <p>{{ $post->content }}</p>
        </div>
    @endforeach
@endsection
```

### 6.8 配置文件

在模块的 `config` 目录下创建配置文件，例如 `blog.php`：

```php
<?php

return [
    'per_page' => 10,
    'comment_enabled' => true,
];
```

### 6.9 服务提供者

在模块的 `src/Providers` 目录下创建服务提供者，例如 `BlogServiceProvider.php`：

```php
<?php

namespace Kylin\Blog\Providers;

use Illuminate\Support\ServiceProvider;

class BlogServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        // 注册服务
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        // 引导服务
    }
}
```

## 7. 最佳实践

### 7.1 模块命名规范

- 模块名称应使用小写字母和下划线
- 模块目录应与模块名称一致
- 模块命名空间应使用驼峰命名法

### 7.2 模块结构规范

- 遵循 Laravel 的目录结构规范
- 将业务逻辑封装在服务类中
- 使用依赖注入减少耦合
- 遵循单一职责原则

### 7.3 模块依赖管理

- 明确模块间的依赖关系
- 使用 composer.json 管理外部依赖
- 避免循环依赖

### 7.4 模块版本管理

- 使用语义化版本号
- 记录模块的变更历史
- 提供升级指南

### 7.5 模块测试

- 为模块编写单元测试和功能测试
- 使用 PHPUnit 进行测试
- 确保模块的稳定性和可靠性

## 8. 常见问题

### 8.1 模块不加载

**问题**：创建模块后，模块不加载。
**解决方案**：
1. 检查模块的 `composer.json` 文件是否正确配置
2. 运行 `composer dump-autoload` 命令更新自动加载
3. 检查模块是否在 `config/modules.php` 文件的 `enabled` 列表中

### 8.2 路由不生效

**问题**：模块的路由不生效。
**解决方案**：
1. 检查模块的路由文件是否正确配置
2. 确保模块已启用
3. 清除路由缓存：`php artisan route:clear`

### 8.3 视图不显示

**问题**：模块的视图不显示。
**解决方案**：
1. 检查视图文件的路径是否正确
2. 确保模块已启用
3. 清除视图缓存：`php artisan view:clear`

### 8.4 配置不生效

**问题**：模块的配置不生效。
**解决方案**：
1. 检查配置文件的路径是否正确
2. 确保模块已启用
3. 清除配置缓存：`php artisan config:clear`

## 9. 总结

Kylin Modules 是一个强大的 Laravel 模块化开发扩展包，它提供了丰富的功能和工具，使得模块化开发变得简单和高效。通过使用 Kylin Modules，您可以：

- 将应用拆分为多个独立的模块，提高代码的可维护性
- 复用模块代码，减少重复开发
- 快速创建和管理模块，提高开发效率
- 实现模块的热插拔，无需重启应用即可启用或禁用模块

Kylin Modules 是构建大型 Laravel 应用的理想选择，它可以帮助您更好地组织代码结构，提高开发效率，降低维护成本。

## 10. 参考资源

- [Laravel 官方文档](https://laravel.com/docs)
- [Kylin Modules GitHub 仓库](https://github.com/kylin-framework/modules)
- [Composer 官方文档](https://getcomposer.org/doc)