README

使用常规UUID作为主键肯定会很慢。

此包通过存储略微调整的二进制版本的UUID来解决性能问题。您可以在以下链接中了解更多关于存储机制的信息：http://mysqlserverteam.com/storing-uuid-values-in-mysql-tables/。

该包可以生成优化的UUID版本。它还提供了方便的模型作用域，可以轻松检索使用二进制UUID的模型。

想测试您系统上的性能改进吗？没问题，我们已包括基准测试。

该包目前仅支持MySQL和SQLite。

安装

您可以通过Composer安装此包

composer require bluink/laravel-binary-uuid

用法

为了让模型使用优化的UUID，您必须在表中将uuid字段添加为主字段。

Schema::create('table_name', function (Blueprint $table) {
    $table->uuid('uuid');
    $table->primary('uuid');
});

为了使模型能够与编码的UUID（即使用uuid作为主键）一起工作，您必须让模型使用Spatie\BinaryUuid\HasBinaryUuid特质。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;
}

如果您不喜欢名为uuid的主键名称，可以手动指定getKeyName方法。别忘了将$incrementing设置为false。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;

    public $incrementing = false;

    public function getKeyName()
    {
        return 'custom_uuid';
    }
}

如果您尝试将具有二进制属性的模型转换为JSON，您将看到错误。通过在您的模型中声明$uuidAttributes上的二进制属性，您将告诉包在将UUID转换为数组时将它们转换为文本。此外，这为每个uuid属性添加了一个动态访问器。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;

    /**
     * The suffix for the uuid text attribute
     * by default this is '_text'
     *
     * @var
     */
    protected $uuidSuffix = '_str';

    /**
     * The binary UUID attributes that should be converted to text.
     *
     * @var array
     */
    protected $uuids = [
        'country_uuid' // foreign or related key
    ];
}

在您的JSON中，您将看到以文本形式表示的uuid和country_uuid。如果您还使用复合主键，上述方法也足够好。只需在$uuids数组中包含您的键或覆盖您模型上的getKeyName()方法，并返回作为键数组的复合主键。您还可以自定义UUID文本属性后缀名称。在上述代码中，它不是'_text'，而是'_str'。

您模型中的$uuids数组定义了在检索时将转换为UUID字符串的字段，在写入数据库时将转换为二进制。您不需要在模型的$casts数组中定义这些字段。

关于uuid蓝图方法的说明

Laravel目前不允许添加新的蓝图方法，这些方法可以直接使用。因此，我们决定覆盖uuid的行为，这将创建一个BINARY列而不是一个CHAR(36)列。

在某些情况下，Laravel生成的代码也会使用uuid，但不支持我们的二进制实现。例如，数据库通知。为了使这些通知工作，您必须将这些通知的迁移更改使用CHAR(36)。

// $table->uuid('id')->primary();

$table->char('id', 36)->primary();

创建模型

模型的UUID将在保存时自动生成。

$model = MyModel::create();

dump($model->uuid); // b"\x11þ╩ÓB#(ªë\x1FîàÉ\x1EÝ."

获取可读UUID

UUID仅在数据库中以二进制形式存储。但是，您可以使用文本版本进行URL生成等。

$model = MyModel::create();

dump($model->uuid_text); // "6dae40fa-cae0-11e7-80b6-8c85901eed2e"

如果您想在创建模型之前设置特定的UUID，这也是可能的。

但您可能永远不会想这样做。

$model = new MyModel();

$model->uuid_text = $uuid;

$model->save();

查询模型

查询数据库的最优方式

$uuid = 'ff8683dc-cadd-11e7-9547-8c85901eed2e'; // UUID from eg. the URL.

$model = MyModel::withUuid($uuid)->first();

withUuid作用域将自动将UUID字符串编码为查询数据库。手动方法可能如下所示。

$model = MyModel::where('uuid', MyModel::encodeUuid($uuid))->first();

您还可以使用withUuid作用域查询多个UUID。

$models = MyModel::withUuid([
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
])->get();

注意：版本1.3.0增加了使用uuid字符串查找数据的简化语法。

$uuid = 'ff8683dc-cadd-11e7-9547-8c85901eed2e'; // UUID from eg. the URL.

$model = MyModel::find($uuid);

$model = MyModel::findOrFail($uuid);

版本1.3.0查询多个UUID。

$uuids = [
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
];

$model = MyModel::findMany($uuids);

查询关系

您还可以使用withUuid作用域，通过指定要查询的字段来查询关系字段。

$models = MyModel::withUuid('ff8683dc-cadd-11e7-9547-8c85901eed2e', 'relation_field')->get();

$models = MyModel::withUuid([
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
], 'relation_field')->get();

运行基准测试

该包包含基准测试，证明了以调整后的二进制形式存储uuid确实更加高效。

在运行测试之前，您应该设置一个MySQL数据库，并在phpunit.xml.dist中指定连接配置。

要运行测试，请输入以下命令。

phpunit -d memory_limit=-1 --testsuite=benchmarks

运行基准测试可能需要几分钟。您有足够的时间喝几杯咖啡！

在测试运行过程中，平均结果将在终端中输出。测试完成后，您将在测试文件夹中找到单个查询统计数据的CSV文件。

您可以使用这些数据进一步调查本地机器上UUID的性能。

以下是我们机器上运行的基准测试结果。

正常ID、二进制UUID和优化UUID方法的比较。在大型数据集中，优化UUID的表现优于其他所有方法。

测试

composer test

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

鸣谢

• Brent Roose
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。