Overview概述
In this guide, you can learn how to enable or disable the Node.js driver's UTF-8 validation feature. UTF-8 is a character encoding specification that ensures compatibility and consistent presentation across most operating systems, applications, and language character sets.在本指南中，您可以学习如何启用或禁用Node.js驱动程序的UTF-8验证功能。UTF-8是一种字符编码规范，可确保大多数操作系统、应用程序和语言字符集之间的兼容性和一致性。
If you enable validation, the driver throws an error when it attempts to convert data that contains invalid UTF-8 characters. The validation adds processing overhead since it needs to check the data.如果启用验证，驱动程序在尝试转换包含无效UTF-8字符的数据时会抛出错误。验证增加了处理开销，因为它需要检查数据。
If you disable validation, your application avoids the validation processing overhead, but cannot guarantee consistent presentation of invalid UTF-8 data.如果禁用验证，您的应用程序将避免验证处理开销，但无法保证一致地呈现无效的UTF-8数据。
By default, the driver enables UTF-8 validation on data from MongoDB. It checks incoming documents for any characters that are not encoded in a valid UTF-8 format when it parses data sent from MongoDB to your application.默认情况下，驱动程序对来自MongoDB的数据启用UTF-8验证。当它解析从MongoDB发送到您的应用程序的数据时，它会检查传入文档中是否有任何未以有效UTF-8格式编码的字符。
Note
This version of the Node.js driver automatically substitutes invalid lone surrogates with the replacement character before validation when you send data to MongoDB. Therefore, the validation only throws an error when the setting is enabled and the driver receives invalid UTF-8 document data from MongoDB.当您向MongoDB发送数据时，此版本的Node.js驱动程序会在验证之前自动用替换字符替换无效的单独代理。因此，只有当启用了该设置并且驱动程序从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 performs UTF-8 validation by defining the 您可以在创建客户端、引用数据库或集合或调用CRUD操作时，通过在enableUtf8Validation setting in the options parameter when you create a client, reference a database or collection, or call a CRUD operation. If you omit the setting, the driver enables UTF-8 validation.options参数中定义enableUtf8Validation设置来指定驱动程序是否执行UTF-8验证。如果省略该设置，驱动程序将启用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 documentSet 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' });