MongoDB 文档数据格式：BSON

文档数据格式：BSON

概览

在本指南中，您可以了解 BSON 数据格式、MongoDB 如何使用它以及如何独立于 MongoDB Java 驱动程序安装 BSON 库。

BSON 数据格式

BSON或二进制 JSON 是 MongoDB 用于组织和存储数据的数据格式。此数据格式包括所有 JSON 数据结构类型，并增加了对日期、不同大小整数、ObjectId 和二进制数据等类型的支持。有关受支持类型的完整列表，请参阅 BSON 类型服务器手册页。

二进制格式不是人类可读的，但您可以使用 Java BSON 库将其转换为 JSON 表示。您可以在我们关于JSON 和 BSON 的文章中阅读有关这些格式之间关系的更多信息。

MongoDB 和 BSON

使用 BSON 库的 MongoDB Java 驱动程序允许您使用实现BSON 接口的对象类型之一来处理 BSON 数据，包括：

文档（BSON 库包）
BsonDocument（BSON 库包）
RawBsonDocument（BSON 库包）
JsonObject（BSON 库包）
BasicDBObject（Java 驱动程序包）

有关使用这些对象类型的更多信息，请参阅我们的文档指南。

安装 BSON 库

这些说明向您展示了如何将 BSON 库作为依赖项添加到您的项目中。如果您将 MongoDB Java 驱动程序作为依赖项添加到您的项目中，则可以跳过此步骤，因为 BSON 库已作为驱动程序的必需依赖项包含在内。有关如何将 MongoDB Java 驱动程序作为依赖项添加到您的项目的说明，请参阅我们的快速入门指南的驱动程序安装部分。

我们建议您使用Maven或 Gradle构建自动化工具来管理项目的依赖项。从以下选项卡中选择以查看该工具的依赖项声明：

以下代码段显示了文件dependencies部分中的依赖项声明 pom.xml。

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>bson</artifactId>
        <version>4.3.2</version>
    </dependency>
</dependencies>

以下代码段显示了文件中dependencies对象中的依赖项声明 build.gradle。

dependencies {
   compile 'org.mongodb:bson:4.3.2'
}

如果您没有使用上述工具之一，您可以通过直接从sonatype 存储库下载 JAR 文件将其包含在您的项目中。

文档数据格式：扩展 JSON

概览

在本指南中，您可以了解如何在 MongoDB Java 驱动程序中使用扩展 JSON 格式。

JSON 是一种数据格式，表示对象、数组、数字、字符串、布尔值和空值的值。的扩展JSON格式定义一个保留的密钥集合与前缀“ $”来表示字段类型信息直接对应于每种类型在BSON，所述格式MongoDB使用来存储数据。

本指南解释了以下主题：

不同的 MongoDB 扩展 JSON 格式
如何使用 BSON 库在扩展 JSON 和 Java 对象之间进行转换
如何创建 BSON 类型的自定义转换

有关这些格式之间差异的更多信息，请参阅我们关于 JSON 和 BSON 的文章。

扩展 JSON 格式

MongoDB 扩展 JSON 具有不同的字符串格式来表示 BSON 数据。每种不同的格式都符合 JSON RFC 并满足特定用例。在扩展格式中，也被称为规范格式，特征在于用于而不丢失信息每BSON类型的双向转换特定表示。的宽松模式格式是更简洁，更接近普通JSON，但并不代表所有类型的信息，例如数量字段的特定的字节大小。

请参阅下表以查看每种格式的说明：

Name	描述
Extended	也称为规范格式，这种 JSON 表示避免了 BSON 类型信息的丢失。这种格式在失去人类可读性和与旧格式的互操作性的情况下优先保留类型。
Relaxed Mode	描述具有某些类型信息丢失的 BSON 文档的 JSON 表示。这种格式在丢失某些类型信息的情况下优先考虑人类可读性和互操作性。
Shell	与 MongoDB shell 中使用的语法匹配的 JSON 表示。这种格式优先考虑与 MongoDB shell 的兼容性，它经常使用 JavaScript 函数来表示类型。

笔记

驱动程序将$uuid扩展 JSON 类型从字符串解析BsonBinary为二进制子类型 4的对象。有关$uuid字段解析的更多信息，请参阅扩展 JSON 规范中解析 $uuid 字段的特殊规则部分。

有关这些格式的更多详细信息，请参阅以下资源：

JSON RFC官方文档
MongoDB 扩展 JSON服务器手册入口
mongo shell服务器手册入口中的数据类型
BsonBinary API 文档
扩展 JSON 规范GitHub 文档

扩展 JSON 示例

以下示例显示了一个包含以每个扩展 JSON 格式表示的 ObjectId、日期和长数字字段的文档。单击与您要查看的示例的格式对应的选项卡：

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}

{
  "_id:": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

读取扩展 JSON

使用文档类

您可以通过parse()从Document或BsonDocument 类调用静态方法将扩展 JSON 字符串读入 Java 文档对象，具体取决于您需要的对象类型。此方法解析任何格式的扩展 JSON 字符串，并返回包含数据的该类的实例。

以下示例显示了如何使用Document该类将示例扩展 JSON 字符串读取到Document使用该parse()方法的对象中：

String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," +
                  "\"myNumber\": {\"$numberLong\": \"4794261\" }}}";
Document doc = Document.parse(ejsonStr);
System.out.println(doc);

上述代码的输出应如下所示：

Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

有关更多信息，请参阅我们的文档基础页面。

使用 BSON 库

您还可以通过使用JsonReader类将扩展 JSON 字符串读入 Java 对象，而无需使用 MongoDB Java 驱动程序的文档类。该类包含顺序解析扩展 JSON 字符串的任何格式的字段和值的方法，并将它们作为 Java 对象返回。驱动程序的文档类也使用这个类来解析扩展的 JSON。

以下代码示例展示了如何使用JsonReader该类将扩展 JSON 字符串转换为 Java 对象：

String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," +
                  "\"myNumber\": {\"$numberLong\": \"4794261\" }}}";
JsonReader jsonReader = new JsonReader(ejsonStr);
jsonReader.readStartDocument();
jsonReader.readName("_id");
ObjectId id = jsonReader.readObjectId();
jsonReader.readName("myNumber");
Long myNumber = jsonReader.readInt64();
jsonReader.readEndDocument();
System.out.println(id + " is type: " + id.getClass().getName());
System.out.println(myNumber + " is type: " + myNumber.getClass().getName());
jsonReader.close();

此代码示例的输出应如下所示：

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: java.lang.Long

有关更多信息，请参阅JsonReader API 文档。

写入扩展 JSON

使用文档类

您可以从的实例Document或 BsonDocument通过调用toJson()方法编写扩展 JSON 字符串，可选择将的实例传递给它JsonWriterSettings以指定扩展 JSON 格式。

在此示例中，我们以轻松模式格式输出扩展 JSON。

Document myDoc = new Document();
myDoc.append("_id", new ObjectId("507f1f77bcf86cd799439012")).append("myNumber", 11223344);
JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED).build();
System.out.println(doc.toJson(settings));

此代码示例的输出应如下所示：

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": 11223344}

使用 BSON 库

您还可以使用 BSON 库和JsonWriter类从 Java 对象中的数据输出扩展 JSON 字符串。要构造的实例JsonWriter，请传递 Java 的子类Writer以指定您希望如何输出扩展 JSON。您可以选择传递一个JsonWriterSettings 实例来指定扩展 JSON 格式等选项。默认情况下， JsonWriter使用轻松模式格式。MongoDB Java 驱动程序的文档类也使用这个类将 BSON 转换为扩展 JSON。

以下代码示例展示了如何使用JsonWriter创建扩展 JSON 字符串并将其输出到System.out. 我们通过向outputMode()builder 方法传递JsonMode.EXTENDED常量来指定格式：

JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build();
try (JsonWriter jsonWriter = new JsonWriter(new BufferedWriter(new OutputStreamWriter(System.out)), settings)) {
    jsonWriter.writeStartDocument();
    jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012"));
    jsonWriter.writeInt64("myNumber", 11223344);
    jsonWriter.writeEndDocument();
    jsonWriter.flush();
}

此代码示例的输出应如下所示：

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

有关本节中提到的方法和类的更多信息，请参阅以下 API 文档：

自定义 BSON 类型转换

除了指定outputMode()要格式化 JSON 输出之外，您还可以通过将转换器添加到 JsonWriterSettings.Builder. 这些转换器方法检测 Java 类型并执行Converter传递给它们的定义的逻辑。

以下示例代码显示了如何附加定义为 lambda 表达式的转换器以简化轻松模式 JSON 输出。

JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED)
        .objectIdConverter((value, writer) -> writer.writeString(value.toHexString()))
        .dateTimeConverter(
                (value, writer) -> {
                    ZonedDateTime zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC);
                    writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime));
                })
        .build();
Document doc = new Document()
     .append("_id", new ObjectId("507f1f77bcf86cd799439012"))
     .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
     .append("myNumber", 4794261);
System.out.println(doc.toJson(settings)));

此代码的输出应如下所示：

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}

在不指定转换器的情况下，轻松模式 JSON 输出应如下所示：

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}

有关本节中提到的方法和类的更多信息，请参阅以下 API 文档：

发表于 2021-10-02 10:02 汪成龙的博客阅读(3860) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

MongoDB 文档数据格式：BSON

文档数据格式：BSON

概览

BSON 数据格式

MongoDB 和 BSON

安装 BSON 库

文档数据格式：扩展 JSON

概览

扩展 JSON 格式

扩展 JSON 示例

读取扩展 JSON

使用文档类

使用 BSON 库

写入扩展 JSON

使用文档类

使用 BSON 库

自定义 BSON 类型转换

公告