PHPackages                             dybasedev/luna-prototype - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. dybasedev/luna-prototype

ActiveLibrary[Framework](/categories/framework)

dybasedev/luna-prototype
========================

基于 Laravel 的模块化快速业务原型开发框架

0.9.0(9mo ago)014Apache-2.0PHPPHP ^8.4

Since Jun 22Pushed 8mo agoCompare

[ Source](https://github.com/dybasedev/luna-prototype)[ Packagist](https://packagist.org/packages/dybasedev/luna-prototype)[ RSS](/packages/dybasedev-luna-prototype/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (20)Used By (0)

Luna Prototype
==============

[](#luna-prototype)

基于 Laravel 12.0 的快速业务原型开发框架

概述
--

[](#概述)

Luna Prototype 是一个基于 Laravel 12.0 和 PHP 8.4 的模块化快速业务原型开发框架。框架的核心理念是**减少不必要的重复功能开发**，通过提供**相对原子化的组件**，让开发者可以根据具体业务需求进行**扩展、调整和组合使用**。

### 设计理念

[](#设计理念)

- **原子化组件**: 每个模块都设计为功能单一、职责明确的原子化组件，可独立使用
- **避免重复开发**: 提供常见业务场景的基础实现，减少从零开始的重复工作
- **灵活组合**: 模块间松耦合，可根据项目需求自由组合和扩展
- **渐进式集成**: 可以选择性地集成需要的模块，不强制使用全套功能
- **扩展优先**: 通过处理器模式、配置系统等机制，优先支持扩展而非修改核心代码

Luna Prototype 特别适合快速原型开发、概念验证、初创项目和需要快速迭代的业务场景。

主要特性
----

[](#主要特性)

### 基础架构特性

[](#基础架构特性)

- **原子化模块架构**: 每个模块都是独立的原子化组件，可按需选择和组合
- **配置管理系统**: 支持版本控制的灵活配置存储和管理机制
- **处理器扩展模式**: 基于处理器的业务逻辑扩展点，支持插件化开发
- **业务事件系统**: 业务操作事件定义和用户友好的描述格式化机制
- **异常处理机制**: 统一的异常定义、映射和处理框架
- **安装器框架**: 模块化的安装流程管理
- **备份恢复机制**: 应用状态的备份和恢复功能

### 业务组件特性

[](#业务组件特性)

- **资产账户系统**: 提供多层级账户类型、余额管理、原子化操作等功能
- **交易系统**: 完整的交易流程管理，包括订单、支付、退款等功能
- **会员体系框架**: 可扩展的会员等级、里程碑系统和权益管理
- **权限系统**: 基于策略的权限管理，支持角色、用户组和灵活的权限分配
- **单位转换系统**: 支持多种单位类型转换，包括货币、度量衡等，支持动态汇率
- **对象持有系统**: 灵活的对象持有关系管理，支持签到、购买限制、抽奖等场景
- **调度任务系统**: 灵活的定时任务和后台作业管理框架
- **UI组件抽象层**: 前端无关的表单字段和数据展示组件抽象

原子化组件优势
-------

[](#原子化组件优势)

### 按需使用

[](#按需使用)

```
// 只需要账户系统
class AppServiceProvider extends LunaServiceProvider
{
    public function customRegister(): void
    {
        $this->registerModule(LunaAssetsAccountConfigure::create()->build());
    }
}

// 需要完整功能
class AppServiceProvider extends LunaServiceProvider
{
    public function customRegister(): void
    {
        $this->registerModule(LunaAssetsAccountConfigure::create()->build());
        $this->registerModule(LunaScheduleConfigure::create()->build());
        $this->registerModule(LunaMembershipConfigure::create()->build());
        $this->registerModule(LunaUnitConversionConfigure::create()->build());
        $this->registerModule(LunaTradeConfigure::create()->build());
        $this->registerModule(LunaHoldingObjectConfigure::create()->build());
        $this->registerModule(LunaPermissionConfigure::create()->build());
    }
}
```

### 灵活扩展

[](#灵活扩展)

```
// 扩展账户类型处理器
$this->extendModule(function() {
    return LunaHandlerConfigure::create()
        ->group('account_handlers', '账户处理器', function($register) {
            $register->handler(CryptoWalletHandler::class);
            $register->handler(PointsHandler::class);
            $register->handler(CouponHandler::class);
        })
        ->build();
});

// 自定义业务事件格式化
$this->extendModule(function() {
    return LunaBusinessEventConfigure::create()
        ->group('payment_events', '支付事件', function($register) {
            $register->handler(PaymentEventHandler::class);
        })
        ->build();
});
```

核心概念
----

[](#核心概念)

### 模块组件（Module）

[](#模块组件module)

Luna Prototype 的核心是**组件化设计**。每个组件都是一个完整、独立的功能单元模块，具有清晰的职责边界和标准化的结构。

#### 组件的标准结构

[](#组件的标准结构)

每个 Luna 组件通常包含三个核心部分：

1. **配置器（Configure）** - 组件的核心，负责服务注册、依赖管理和组件配置
2. **访问入口类（Module）** - 组件的业务逻辑封装和 API 接口
3. **服务提供者（ServiceProvider）** - 资源发布器（可选）

```
// 组件的典型结构
namespace Dybasedev\LunaPrototype\YourComponent;

// 1. 配置器 - 处理组件的注册和启动逻辑
class LunaYourComponentConfigure extends LunaModuleConfigure { }

// 2. 访问入口类 - 提供组件的业务 API
class LunaYourComponent extends LunaModule { }

// 3. 服务提供者 - 负责资源文件的发布
class LunaYourComponentServiceProvider extends ServiceProvider { }
```

#### 组件的概念

[](#组件的概念)

组件是 Luna Prototype 的基本构建单元，每个组件：

- **独立性**：可以独立安装、配置和使用
- **原子性**：专注于单一的业务领域或功能
- **可组合**：可以与其他组件自由组合使用
- **可扩展**：提供标准化的扩展点和配置选项

### 组件的配置器（Luna Module Configure）

[](#组件的配置器luna-module-configure)

配置器是组件的核心，继承自 `LunaModuleConfigure` 基类，负责：

#### 定义组件身份

[](#定义组件身份)

```
class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    public function name(): string
    {
        return 'luna.assets-account';  // 组件唯一标识
    }

    public function dependencies(): array
    {
        return ['luna.foo'];  // 声明依赖的其他组件，此处仅作演示
    }
}
```

#### 配置选项管理

[](#配置选项管理)

```
class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    // 配置属性
    protected(set) string $accountModel = AssetsAccount::class;
    protected(set) string $accountTypeModel = AssetsAccountType::class;

    // 配置方法（流式接口，且强烈建议使用该方式）
    public function useAccountModel(string $class): static
    {
        $this->accountModel = $class;
        return $this;
    }
}
```

#### 服务注册

[](#服务注册)

配置器负责组件的服务注册，这是 Luna Prototype 的一个重要设计理念：

```
public function register(Container $container): void
{
    // 注册单例服务
    $container->singleton('luna.assets-account', function ($app) {
        return new LunaAssetsAccount(
            $this,
            $app->make('cache.store'),
            $app->make(LunaHandler::class)
        );
    });

    // 注册别名
    $container->alias('luna.assets-account', LunaAssetsAccount::class);
}
```

> **重要**：与传统 Laravel 包不同，Luna 组件的 `register()` 和 `boot()` 逻辑都在配置器（Configure）类中实现，而不是在服务提供者中。

### 服务提供者的作用

[](#服务提供者的作用)

在 Luna Prototype 中，服务提供者（ServiceProvider）专注于**资源文件的发布**，这是它的主要职责：

```
class LunaAssetsAccountServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 发布数据库迁移文件
        $this->publishesMigrations([
            __DIR__ . '/migrations' => database_path('migrations'),
        ]);

        // 如果组件有配置文件、语言文件等其他资源
        // $this->publishes([
        //     __DIR__ . '/config/assets-account.php' => config_path('luna/assets-account.php'),
        // ], 'luna-assets-account-config');

        // $this->publishes([
        //     __DIR__ . '/lang' => lang_path('luna/assets-account'),
        // ], 'luna-assets-account-lang');
    }
}
```

#### 为什么要分离服务提供者？

[](#为什么要分离服务提供者)

1. **清晰的发布管理**：使用 `php artisan vendor:publish` 时，可以清楚地看到每个组件可发布的资源
2. **按需发布**：开发者可以选择性地发布特定组件的资源文件
3. **保持配置器纯粹**：配置器专注于组件逻辑，服务提供者专注于资源发布

#### 使用资源发布

[](#使用资源发布)

```
# 查看可发布的资源
php artisan vendor:publish

# 发布特定组件的迁移文件
php artisan vendor:publish --provider="Dybasedev\LunaPrototype\AssetsAccount\LunaAssetsAccountServiceProvider"

# 使用标签发布（如果定义了标签）
php artisan vendor:publish --tag=luna-trade-migrations
```

### 组件的访问入口类

[](#组件的访问入口类)

访问入口类继承自 `LunaModule` 基类，提供组件的主要 API 接口：

```
class LunaAssetsAccount extends LunaModule
{
    // 提供业务方法
    public function createAccountType(
        string $name,
        string $handler,
        ?string $displayName = null
    ): AssetsAccountType {
        // 业务逻辑实现
    }

    // 获取用户账户
    public function ownerAccount(
        Model $owner,
        string $accountType
    ): AssetsAccount {
        // 业务逻辑实现
    }
}
```

访问组件的三种方式：

```
// 1. 依赖注入
public function __construct(LunaAssetsAccount $assetsAccount) { }

// 2. 服务容器
$assetsAccount = app('luna.assets-account');

// 3. 辅助函数
$assetsAccount = luna_assets_account();
```

### 组件的注册流程

[](#组件的注册流程)

Luna Prototype 采用了独特的组件注册机制，通过继承 `LunaServiceProvider` 来管理所有组件：

```
// app/Providers/AppServiceProvider.php
class AppServiceProvider extends LunaServiceProvider
{
    public function customRegister(): void
    {
        // 注册组件
        $this->registerModule(
            LunaAssetsAccountConfigure::create()
                ->useAccountModel(CustomAccount::class)  // 自定义配置
                ->build()
        );

        // 扩展现有组件
        $this->extendModule(function() {
            return LunaHandlerConfigure::create()
                ->group('payment', '支付处理器', function($register) {
                    $register->handler(AlipayHandler::class);
                })
                ->build();
        });
    }
}
```

#### 注册流程详解

[](#注册流程详解)

1. **继承 LunaServiceProvider**：您的 `AppServiceProvider` 需要继承 `LunaServiceProvider` 而不是 Laravel 的 `ServiceProvider`
2. **配置组件**：在 `customRegister()` 方法中使用 `registerModule()` 注册需要的组件
3. **自动注册服务提供者**：框架会自动注册组件配置器中声明的 ServiceProvider，无需手动添加到 `config/app.php`
4. **处理依赖关系**：框架自动检查组件间的依赖关系，确保正确的加载顺序
5. **执行生命周期方法**：依次执行配置器的 `register()` 方法、ServiceProvider 的注册、配置器的 `boot()` 方法

#### 自动服务提供者注册机制

[](#自动服务提供者注册机制)

Luna Prototype 的一个重要特性是**自动注册服务提供者**，这大大减少了业务开发者的样板代码：

```
// 在组件的配置器中声明服务提供者
class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    public function serviceProvider(): ?string
    {
        return LunaAssetsAccountServiceProvider::class;
    }
}

// LunaServiceProvider 会自动注册这个服务提供者
// 无需在 config/app.php 中手动添加！
```

这样设计的优势：

- **减少配置**：无需手动维护 `config/app.php` 中的服务提供者列表
- **保持一致性**：组件的所有相关配置都在配置器中管理
- **避免遗漏**：不会因为忘记注册服务提供者而导致资源无法发布

### Foundation 组件概要

[](#foundation-组件概要)

Foundation 是 Luna Prototype 的基础组件，所有其他组件都依赖于它。它提供了整个框架的核心基础设施。

#### 主要功能

[](#主要功能)

- **Handler（处理器系统）**：统一的处理器注册和执行机制
- **Configuration（配置管理）**：灵活的配置存储和版本控制
- **BusinessEvent（业务事件）**：业务操作的事件定义和格式化
- **Exception（异常处理）**：统一的异常定义和处理机制
- **Installation（安装器）**：模块化的安装流程管理
- **Backupable（备份恢复）**：应用状态的备份和恢复

→ [Foundation 详细文档](src/Foundation/README.md)

#### 核心类

[](#核心类)

```
// 处理器管理
$handler = luna_handler();
$handlerInstance = $handler->createHandlerInstance('payment-handler');
$result = $handlerInstance->process($data);

// 配置管理
$config = luna_configuration();
$appGroup = $config->group('app');
$appGroup->set('settings.theme', 'dark');
$appGroup->save();

// 业务事件
$event = luna_business_event();
$message = $event->eventMessage('user.login', ['user' => 'Alice']);
```

Foundation 组件是其他所有组件的基石，提供了标准化的扩展点和基础服务。

系统要求
----

[](#系统要求)

- PHP 8.4+
- Laravel 12.0+
- 支持的数据库: MySQL, PostgreSQL, SQLite

安装
--

[](#安装)

通过 Composer 安装：

```
composer require dybasedev/luna-prototype
```

快速开始
----

[](#快速开始)

### 1. 基础配置

[](#1-基础配置)

修改 Laravel 项目中的 `AppServiceProvider` 继承 `LunaServiceProvider`：

```
// app/Providers/AppServiceProvider.php