README

基于 Twitter 宣布的雪花算法的 PHP ID 生成器

说明

雪花算法的 PHP 实现

Snowflake 是 Twitter 内部的一个 ID 生成算法，通过一些简单的规则可以保证在大规模分布式环境下生成唯一的 ID 号码。其结构如下：

• 第一个 bit 位为未使用的符号位。
• 第二部分由 41 位的时间戳（毫秒）组成，其值是当前时间相对于某一时间的偏移量。
• 第三部分和第四部分的 5 位 bit 位表示数据中心和机器 ID，其最大值为 2^5 -1 = 31。
• 最后一部分由 12 位 bit 组成，表示每个工作节点每毫秒生成的序列号 ID，同一毫秒内最多可生成 2^12 -1 即 4095 个 ID。

需要注意的是：

• 在分布式环境中，5 位 bit 位的 datacenter 和 worker 表示最多能部署 31 个数据中心，每个数据中心最多可部署 31 台节点。
• 41 位的二进制长度最多能表示 2^41 -1 毫秒即 69 年，因此雪花算法最多能正常使用 69 年。为了能最大限度的使用该算法，你应该为其指定一个开始时间。

由此可见，雪花算法生成的 ID 并不能保证唯一。例如，当两个不同请求在同一时刻进入相同的数据中心的相同节点时，而此时该节点生成的 sequence 又是相同时，就会导致生成的 ID 重复。

因此，要想使用雪花算法生成唯一的 ID，就需要保证同一节点同一毫秒内生成的序列号是唯一的。基于此，我们在 SDK 中集成了多种序列号提供者：

• RandomSequenceResolver（随机生成）
• RedisSequenceResolver （基于 redis psetex 和 incrby 生成）
• LaravelSequenceResolver（基于 redis psetex 和 incrby 生成）
• SwooleSequenceResolver（基于 swoole_lock 锁）
• FileLockResolver（基于 PHP 文件锁）

警告 RandomSequenceResolver 序列号提供者在高并发情况下可能会导致生成的 ID 重复。如果你的应用场景中可能会出现高并发的情况，建议使用 RedisSequenceResolver 或者 LaravelSequenceResolver。

要求

1. PHP >= 8.1
2. Composer

安装

$ composer require ledc/snowflake -vvv

使用

1. 简单使用.

$snowflake = new \Ledc\Snowflake\Snowflake;

$snowflake->id();
// 1537200202186752

1. 指定数据中心 ID 及机器 ID.

$snowflake = new \Ledc\Snowflake\Snowflake($datacenterId, $workerId);

$snowflake->id();

1. 指定开始时间.

$snowflake = new \Ledc\Snowflake\Snowflake;
$snowflake->setStartTimeStamp(strtotime('2019-08-08')*1000);

$snowflake->id();

1. 使用索尼雪花算法

$sonyflake = new \Ledc\Snowflake\Sonyflake;

$sonyflake->id();

高级

1. 在 Laravel 中使用

因为 SDK 相对简单，我们并没有提供 Laravel 的扩展包，你可通过下面的方式快速集成到 Laravel 中。

// App\Providers\AppServiceProvider

use Ledc\Snowflake\Snowflake;
use Ledc\Snowflake\LaravelSequenceResolver;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->singleton('snowflake', function ($app) {
            return (new Snowflake())
                ->setStartTimeStamp(strtotime('2019-10-10')*1000)
                ->setSequenceResolver(new LaravelSequenceResolver($app->get('cache.store')));
        });
    }
}
}

1. 自定义序列号解决器

你可以通过实现 Ledc\Snowflake\SequenceResolver 接口来自定义序列号解决器。

class YourSequence implements SequenceResolver
{
    /**
     *  {@inheritdoc}
     */
    public function sequence(int $currentTime)
    {
          // Just test.
        return mt_rand(0, 1);
    }
}

// usage

$snowflake->setSequenceResolver(new YourSequence);
$snowflake->id();

你也可以直接使用闭包：

$snowflake = new \Ledc\Snowflake\Snowflake;
$snowflake->setSequenceResolver(function ($currentTime) {
    static $lastTime;
    static $sequence;

    if ($lastTime == $currentTime) {
        ++$sequence;
    } else {
        $sequence = 0;
    }

    $lastTime = $currentTime;

    return $sequence;
})->id();

许可协议

MIT