README

从 spaite 的存档包 boxed-code/laravel-binary-uuid 分支而来，只发布维护版本。

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

该包通过存储稍微修改过的二进制版本的 UUID 解决了性能问题。您可以在以下链接中了解更多关于存储机制的信息：[http://mysqlserverteam.com/storing-uuid-values-in-mysql-tables/](http://mysqlserverteam.com/storing-uuid-values-in-mysql-tables/)

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

想要测试您的系统上的性能改进？没问题，我们已经包含了[基准测试](#user-content-running-the-benchmarks)。

该包目前仅支持 MySQL 和 SQLite。

安装

您可以通过 Composer 安装此包。

composer require boxed-code/laravel-binary-uuid

使用

要使模型使用优化的 UUID，您必须在表中添加一个 uuid 字段作为主字段。

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

要使模型与编码的 UUID（即使用 uuid 作为主键）一起工作，您必须让模型使用 BoxedCode\BinaryUuid\HasBinaryUuid trait。

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

class TestModel extends Model
{
    use HasBinaryUuid;
}

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

use Illuminate\Database\Eloquent\Model;
use BoxedCode\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 BoxedCode\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

变更日志

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

贡献

请参阅贡献指南以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件green2go@gmail.com而不是使用问题跟踪器来报告。

鸣谢

• Brent Roose
• 所有贡献者

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。