Docs Home → Node.js

UTF-8 ValidationUTF-8验证

On this page本页内容

Overview概述

In this guide, you can learn how to enable or disable the Node.js driver's UTF-8 validation feature. 在本指南中，您可以了解如何启用或禁用Node.js驱动程序的UTF-8验证功能。UTF-8 is a character encoding specification that ensures compatibility and consistent presentation across most operating systems, applications, and language character sets.UTF-8是一种字符编码规范，可确保大多数操作系统、应用程序和语言字符集之间的兼容性和一致性。

If you enable validation, the driver throws an error when it attempts to convert data that contains invalid UTF-8 characters. 如果启用验证，则驱动程序在尝试转换包含无效UTF-8字符的数据时会抛出错误。The validation adds processing overhead since it needs to check the data.验证增加了处理开销，因为它需要检查数据。

If you disable validation, your application avoids the validation processing overhead, but cannot guarantee consistent presentation of invalid UTF-8 data.如果禁用验证，则应用程序可以避免验证处理开销，但不能保证有效UTF-8数据的一致性。

The driver enables UTF-8 validation by default. 默认情况下，驱动程序启用UTF-8验证。It checks documents for any characters that are not encoded in a valid UTF-8 format when it transfers data between your application and MongoDB.当它在应用程序和MongoDB之间传输数据时，它会检查文档中是否有未使用有效UTF-8格式编码的字符。

Note

The current version of the Node.js driver automatically substitutes invalid UTF-8 characters with alternate valid UTF-8 ones prior to validation when you send data to MongoDB. 当您向MongoDB发送数据时，当前版本的Node.js驱动程序会在验证之前自动将无效的UTF-8字符替换为有效的UTF-8字符。Therefore, the validation only throws an error when the setting is enabled and the driver receives invalid UTF-8 document data from MongoDB.因此，只有在启用该设置并且驱动程序从MongoDB接收到无效的UTF-8文档数据时，验证才会抛出错误。

Read the sections below to learn how to set UTF-8 validation using the Node.js driver.阅读以下部分，了解如何使用Node.js驱动程序设置UTF-8验证。

Specify the UTF-8 Validation Setting指定UTF-8验证设置

You can specify whether the driver should perform UTF-8 validation by defining the enableUtf8Validation setting in the options parameter when you create a client, reference a database or collection, or call a CRUD operation. 在创建客户端、引用数据库或集合或调用CRUD操作时，可以通过在options参数中定义enableUtf8Validation设置来指定驱动程序是否应执行UTF-8验证。If you omit the setting, the driver enables UTF-8 validation.如果省略该设置，则驱动程序将启用UTF-8验证。

See the following for code examples that demonstrate how to disable UTF-8 validation on the client, database, collection, or CRUD operation:有关如何在客户端、数据库、集合或CRUD操作上禁用UTF-8验证的代码示例，请参阅以下内容：

// disable UTF-8 validation on the client在客户端上禁用UTF-8验证
new MongoClient('<connection uri>', { enableUtf8Validation: false });

// disable UTF-8 validation on the database对数据库禁用UTF-8验证
client.db('<database name>', { enableUtf8Validation: false });

// disable UTF-8 validation on the collection对集合禁用UTF-8验证
db.collection('<collection name>', { enableUtf8Validation: false });

// disable UTF-8 validation on a specific operation call对特定操作调用禁用UTF-8验证
await myColl.findOne({ title: 'Cam Jansen'}, { enableUtf8Validation: false });

If your application reads invalid UTF-8 from MongoDB while the enableUtf8Validation option is enabled, it throws a BSONError that contains the following message:如果您的应用程序在启用enableUtf8Validation选项的情况下从MongoDB读取到无效的UTF-8，则会抛出一个BSONError，其中包含以下消息：

Invalid UTF-8 string in BSON document

Set the Validation Scope设置验证范围

The enableUtf8Validation setting automatically applies to the scope of the object instance on which you included it, and any other objects created by calls on that instance.enableUtf8Validation设置自动应用于包含它的对象实例的作用域，以及通过调用该实例创建的任何其他对象。

For example, if you include the option on the call to instantiate a database object, any collection instance you construct from that object inherits the setting. 例如，如果在调用中包含实例化数据库对象的选项，则从该对象构造的任何集合实例都将继承该设置。Any operations you call on that collection instance also inherit the setting.对该集合实例调用的任何操作也将继承该设置。

const database = client.db('books', { enableUtf8Validation: false });

// The collection inherits the UTF-8 validation disabled setting from the database该集合继承了数据库中禁用UTF-8验证的设置
const myColl = database.collection('mystery');

// CRUD operation runs with UTF-8 validation disabledCRUD操作在禁用UTF-8验证的情况下运行
await myColl.findOne({ title: 'Encyclopedia Brown' });

You can override the setting at any level of scope by including it when constructing the object instance or when calling an operation.通过在构造对象实例或调用操作时包含该设置，可以在任何级别的作用域覆盖该设置。

For example, if you disable validation on the collection object, you can override the setting in individual CRUD operation calls on that collection.例如，如果对集合对象禁用验证，则可以覆盖该集合上单个CRUD操作调用中的设置。

const collection = database.collection('mystery', { enableUtf8Validation: false });

// CRUD operation runs with UTF-8 validation enabledCRUD操作在启用UTF-8验证的情况下运行
await myColl.findOne({ title: 'Trixie Belden' }, { enableUtf8Validation: true });

// CRUD operation runs with UTF-8 validation disabledCRUD操作在禁用UTF-8验证的情况下运行
await myColl.findOne({ title: 'Enola Holmes' });