README

Cycle ORM 在 Hyperf 中的连接池支持。

该库基于 hyperf/pool 为 Cycle ORM 提供协程安全的数据库连接复用能力，同时尽量保持与原生 Cycle ORM 一致的配置和使用方式。

特性

基于 hyperf/pool 的数据库连接池
按协程隔离 Database 与 ORM 实例
自动回收连接，减少长驻进程中的连接泄露风险
保持与 Cycle ORM 接近的配置结构
支持 MySQL、PostgreSQL、SQLite、SQL Server

安装

composer require lzpeng/hyperf-cycle

发布配置

安装后可发布默认配置：

php bin/hyperf.php vendor:publish lzpeng/hyperf-cycle

发布后会生成数据库配置文件，你可以在其中维护连接信息和连接池参数。

配置示例

<?php

declare(strict_types=1);

use Cycle\Database\Config\MySQL\TcpConnectionConfig;
use Lzpeng\HyperfCycle\Config\MySQLDriverConfig;
use function Hyperf\Support\env;

return [
    'default' => 'default',
    'databases' => [
        'default' => ['connection' => 'default'],
    ],
    'connections' => [
        'default' => new MySQLDriverConfig(
            connection: new TcpConnectionConfig(
                database: env('DB_DATABASE', 'test'),
                host: env('DB_HOST', 'localhost'),
                port: env('DB_PORT', 3306),
                user: env('DB_USER', 'test'),
                password: env('DB_PASSWORD', ''),
                charset: env('DB_CHARSET', 'utf8mb4'),
            ),
            reconnect: true,
            queryCache: true,
            options: [],
            poolOptions: [
                'min_connections' => env('DB_MIN_CONNECTIONS', 1),
                'max_connections' => env('DB_MAX_CONNECTIONS', 10),
                'connect_timeout' => env('DB_CONNECT_TIMEOUT', 10.0),
                'wait_timeout' => env('DB_WAIT_TIMEOUT', 3.0),
                'heartbeat' => env('DB_HEARTBEAT', -1),
                'max_idle_time' => env('DB_MAX_IDLE_TIME', 60.0),
            ],
        ),
    ],
];

连接池参数

参数	说明
`min_connections`	最小连接数
`max_connections`	最大连接数
`connect_timeout`	建立连接超时时间
`wait_timeout`	从连接池获取连接的等待时间
`heartbeat`	心跳检测间隔
`max_idle_time`	连接最大空闲时间

使用方式

推荐：从容器获取

该库通过 ConfigProvider 注册了 DatabaseManager 与 ORMFactory，通常直接从容器取用即可：

use Lzpeng\HyperfCycle\ORMFactory;

$ormFactory = $container->get(ORMFactory::class);

$orm = $ormFactory->orm();
$em = $ormFactory->entityManager();

手动创建

use Cycle\Database\Config\MySQL\TcpConnectionConfig;
use Cycle\ORM\Entity\Behavior\EventDrivenCommandGenerator;
use Cycle\ORM\Schema;
use Lzpeng\HyperfCycle\Config\DatabaseConfig;
use Lzpeng\HyperfCycle\Config\MySQLDriverConfig;
use Lzpeng\HyperfCycle\DatabaseManager;
use Lzpeng\HyperfCycle\ORMFactory;

$databaseManager = new DatabaseManager(
    new DatabaseConfig([
        'default' => 'default',
        'databases' => [
            'default' => ['connection' => 'mysql'],
        ],
        'connections' => [
            'mysql' => new MySQLDriverConfig(
                connection: new TcpConnectionConfig(
                    database: 'spiral',
                    host: '127.0.0.1',
                    port: 3306,
                    user: 'spiral',
                    password: '',
                ),
                queryCache: true,
                poolOptions: [
                    'min_connections' => 1,
                    'max_connections' => 20,
                    'connect_timeout' => 10.0,
                    'wait_timeout' => 3.0,
                    'heartbeat' => -1,
                    'max_idle_time' => 60.0,
                ],
            ),
        ],
    ])
);

$container = /** 获取容器 */;
$schemaConfig = /** Cycle Schema 配置 */;

$schema = new Schema($schemaConfig);
$commandGenerator = new EventDrivenCommandGenerator($schema, $container);

$ormFactory = new ORMFactory(
    databaseManager: $databaseManager,
    schema: $schema,
    commandGenerator: $commandGenerator,
);

$orm = $ormFactory->orm();
$em = $ormFactory->entityManager();

说明

本库主要解决 Hyperf 场景下的 Cycle ORM 连接池与协程隔离问题。
实体映射、Schema、Repository 等能力仍遵循标准 Cycle ORM 用法。
数据库连接会在协程生命周期结束时自动释放。

注意事项

由于hyperf是一个长驻进程框架，连接对象不要作为对象类的属性进行持久化，否则会导致连接泄露问题或事务问题。建议在需要使用数据库连接的地方通过容器获取 DatabaseManager 或 ORMFactory 来获取连接实例，确保连接能够正确回收。

错误使用示例：

use Cycle\Database\DatabaseInterface;
use Lzpeng\HyperfCycle\DatabaseManager;

/**
 * 产品数量管理器.
 */
class QuantityManager implements QuantityManagerInterface
{
    private DatabaseInterface $database;

    public function __construct(private DatabaseManager $databaseManager)
    {
        // 错误：作为属性持久化数据库连接会导致连接泄露问题或事务问题
        $this->database = $this->databaseManager->database();
    }

    public function decrease(Id $productId, Id $skuId, Quantity $quantity): void
    {
        $affected = $this->database->execute(
            'UPDATE `shop_product_sku` SET `quantity` = `quantity` - ? WHERE `id` = ? AND `product_id` = ? AND `quantity` > 0',
            [
                $quantity->toInt(),
                $skuId,
                $productId,
            ]
        );

        if ($affected === 0) {
            throw DomainException::from('库存不足，无法减少库存量', [
                'id' => $productId,
            ]);
        }
    }

    // ...
}

/**
 * 下单.
 */
class PlaceOrderCommand
{
    public function __construct(
        private SkuRepositoryInterface $skuRepository,
        private UserRepositoryInterface $userRepository,
        private OrderRepositoryInterface $orderRepository,
        private OrderFactory $orderFactory,
        private QuantityManagerInterface $quantityManager,
        private TransactionInterface $transaction,
    ) {
    }

    public function execute(
        Id $userId,
        int $productId,
        int $skuId,
        int $quantity,
        array $fulfillmentData,
    ): array {
        // ...

        $order = $this->orderFactory->create($user, $product, $sku, $quantity);

        $this->transaction->execute(function () use ($order, $user) {
            $this->orderRepository->save($order);

            // 由于QuantityManager将数据库连接作为属性, 使用的不是与orderRepository同一个连接, 导致事务失效
            $this->quantityManager->decrease($order->productId(), $order->skuId(), $order->quantity());
        });

        // ...
    }
}

正确例子：

use Lzpeng\HyperfCycle\DatabaseManager;

/**
 * 产品数量管理器.
 */
class QuantityManager implements QuantityManagerInterface
{
    public function __construct(private DatabaseManager $databaseManager)
    {
    }

    public function decrease(Id $productId, Id $skuId, Quantity $quantity): void
    {
        // 使用时才获取数据库连接，确保连接能够正确回收;
        // 同一协程内的连接实例是同一个，事务能够正常工作
        $affected = $this->databaseManager->database()->execute(
            'UPDATE `shop_product_sku` SET `quantity` = `quantity` - ? WHERE `id` = ? AND `product_id` = ? AND `quantity` > 0',
            [
                $quantity->toInt(),
                $skuId,
                $productId,
            ]
        );

        if ($affected === 0) {
            throw DomainException::from('库存不足，无法减少库存量', [
                'id' => $productId,
            ]);
        }
    }

    // ...
}

lzpeng / hyperf-cycle

Maintainers

Package info

Statistics

Security