通用唯一标识符 (UUIDs)

mongodb UUIDs简史

考虑以下规范文本表示的UUID

00112233-4455-6677-8899-aabbccddeeff

最初，MongoDB将UUID表示为BSON Binary 子类型3的值。因为子类型3在编码期间没有标准化UUID的字节序，所以不同的MongoDB驱动程序以不同的字节序编码UUID。使用以下选项卡比较不同MongoDB语言驱动程序将前面的UUID编码为Binary 子类型3的方式

00112233-4455-6677-8899-aabbccddeeff

33221100-5544-7766-8899-aabbccddeeff

77665544-3322-1100-ffee-ddccbbaa9988

为了标准化UUID字节序，我们创建了Binary 子类型4。尽管此子类型在MongoDB驱动程序中得到一致处理，但某些MongoDB部署仍包含子类型3的UUID值。

UNSPECIFIED

当使用UNSPECIFIED表示形式时，PyMongo将BSON Binary值解码为相同子类型的Binary对象。要将Binary对象转换为本地UUID对象，请调用Binary.as_uuid()方法并指定UUID表示形式格式。

如果您尝试在此表示形式下编码UUID对象，PyMongo将引发ValueError。为了避免这种情况，可以在UUID上调用如以下示例所示的Binary.from_uuid()方法。

explicit_binary = Binary.from_uuid(uuid4(), UuidRepresentation.STANDARD)

以下代码示例显示了如何检索包含UNSPECIFIED表示形式的UUID的文档，然后将该值转换为UUID对象。为此，代码执行以下步骤

• 使用 CSHARP_LEGACY UUID 表示法插入包含 uuid 字段的文档。

• 使用 UNSPECIFIED 表示法检索相同的文档。PyMongo 将 uuid 字段的值解码为 Binary 对象。

• 调用 as_uuid() 方法将 uuid 字段的值转换为类型为 CSHARP_LEGACY 的 UUID 对象。转换后，此值与 PyMongo 插入的原始 UUID 相同。

from bson.codec_options import CodecOptions, DEFAULT_CODEC_OPTIONS
from bson.binary import Binary, UuidRepresentation
from uuid import uuid4
# Using UuidRepresentation.CSHARP_LEGACY
csharp_opts = CodecOptions(uuid_representation=UuidRepresentation.CSHARP_LEGACY)
# Store a legacy C#-formatted UUID
input_uuid = uuid4()
collection = client.testdb.get_collection('test', codec_options=csharp_opts)
collection.insert_one({'_id': 'foo', 'uuid': input_uuid})
# Using UuidRepresentation.UNSPECIFIED
unspec_opts = CodecOptions(uuid_representation=UuidRepresentation.UNSPECIFIED)
unspec_collection = client.testdb.get_collection('test', codec_options=unspec_opts)
# UUID fields are decoded as Binary when UuidRepresentation.UNSPECIFIED is configured
document = unspec_collection.find_one({'_id': 'foo'})
decoded_field = document['uuid']
assert isinstance(decoded_field, Binary)
# Binary.as_uuid() can be used to convert the decoded value to a native UUID
decoded_uuid = decoded_field.as_uuid(UuidRepresentation.CSHARP_LEGACY)
assert decoded_uuid == input_uuid

STANDARD

当使用 STANDARD UUID 表示法时，PyMongo 将本机 UUID 对象编码为子类型 4 的 Binary 对象。所有使用 STANDARD 表示法的 MongoDB 驱动程序以相同的方式处理这些对象，不更改字节顺序。

在所有新的应用程序中以及所有首次使用 MongoDB UUIDs 的应用程序中使用 STANDARD UUID 表示法。

PYTHON_LEGACY

PYTHON_LEGACY UUID 表示法对应于 PyMongo 旧版本（小于 v4.0）中使用的 UUID 的旧表示法。当使用 PYTHON_LEGACY UUID 表示法时，PyMongo 将本机 UUID 对象编码为子类型 3 的 Binary 对象，保留与 UUID.bytes 属性相同的字节顺序。

如果您从 MongoDB 读取的 UUID 是使用 PYTHON_LEGACY 表示法插入的，请使用 PYTHON_LEGACY UUID 表示法。以下两个条件都满足时，这将是正确的

• UUID 是使用版本小于 v4.0 的 PyMongo 应用程序插入的。

• 插入 UUID 的应用程序未指定 STANDARD UUID 表示法。

JAVA_LEGACY

JAVA_LEGACY UUID 的表示形式对应于 MongoDB Java 驱动程序使用的 UUID 的旧表示形式。当使用 JAVA_LEGACY UUID 表示形式时，PyMongo 将原生 UUID 对象编码为具有 Java 旧字节序的 Binary 子类型 3 对象。

如果您从 MongoDB 读取的 UUID 是使用 JAVA_LEGACY 表示形式插入的，请使用 JAVA_LEGACY UUID 表示形式。以下两个条件都满足时，则为真

• UUID 是使用 MongoDB Java 驱动程序的应用程序插入的。

• 应用程序未指定 STANDARD UUID 表示形式。

CSHARP_LEGACY

CSHARP_LEGACY UUID 的表示形式对应于 MongoDB .NET/C# 驱动程序使用的 UUID 的旧表示形式。当使用 CSHARP_LEGACY UUID 表示形式时，PyMongo 将原生 UUID 对象编码为具有 C# 旧字节序的 Binary 子类型 3 对象。

如果您从 MongoDB 读取的 UUID 是使用 CSHARP_LEGACY 表示形式插入的，请使用 CSHARP_LEGACY UUID 表示形式。以下两个条件都满足时，则为真

• UUID 是使用 MongoDB .NET/C# 驱动程序的应用程序插入的。

• 应用程序未指定 STANDARD UUID 表示形式。

ValueError: 无法对本地uuid.UUID对象进行编码，因为UUID表示为uuidrepresentation.unspecified

此错误是由于尝试将本地UUID对象编码为二进制对象，而UUID表示为UNSPECIFIED，如下代码示例所示

unspecified_collection.insert_one({'_id': 'bar', 'uuid': uuid4()})
Traceback (most recent call last):
...
ValueError: cannot encode native uuid.UUID with UuidRepresentation.UNSPECIFIED.
UUIDs can be manually converted to bson.Binary instances using bson.Binary.from_uuid()
or a different UuidRepresentation can be configured. See the documentation for
UuidRepresentation for more information.

相反，您必须显式使用Binary.from_uuid()方法将本地UUID转换为二进制对象，如下例所示

explicit_binary = Binary.from_uuid(uuid4(), UuidRepresentation.STANDARD)
unspec_collection.insert_one({'_id': 'bar', 'uuid': explicit_binary})