Docs 菜单
Docs 主页
/ / /
Node.js
/ /

UTF-8 验证

在此页面上

  • Overview
  • 指定 UTF-8 验证设置
  • 设置验证范围

在本指南中,您可以了解如何启用或禁用 Node.js 驱动程序的 UTF-8 验证功能。UTF-8 是一种字符编码规范,可确保大多数操作系统、应用程序和语言字符集的兼容性和一致的显示方式。

如果启用验证,驱动程序在尝试转换包含无效 UTF-8 字符的数据时会引发错误。验证会增加处理开销,因为它需要检查数据。

如果您禁用验证,则应用程序可以避免验证处理开销,但不能保证一致呈现无效的 UTF-8 数据。

驱动程序默认启用 UTF-8 验证。在应用程序和 MongoDB 之间传输数据时,驱动程序会检查文档中是否有任何未以有效 UTF-8 格式编码的字符。

注意

当您将数据发送到 MongoDB 时,当前版本的 Node.js 驱动程序会在验证之前将无效的 UTF-8 字符自动替换为有效的 UTF-8 字符。因此,只有在启用该设置且驱动程序从 MongoDB 接收到无效的 UTF-8 文档数据时,验证才会抛出错误。

阅读以下部分,了解如何使用 Node.js 驱动程序设置 UTF-8 验证。

您可以在创建客户端、引用数据库或集合或调用增删改查操作时通过在选项参数中定义 enableUtf8Validation 设置来指定驱动程序是否应执行 UTF-8 验证。如果省略该设置,则驱动程序将启用 UTF-8 验证。

请参阅以下代码示例,了解如何在客户端、数据库、集合或 CRUD 操作上禁用 UTF-8 验证:

// disable UTF-8 validation on the client
new MongoClient('<connection uri>', { enableUtf8Validation: false });
// disable UTF-8 validation on the database
client.db('<database name>', { enableUtf8Validation: false });
// disable UTF-8 validation on the collection
db.collection('<collection name>', { enableUtf8Validation: false });
// disable UTF-8 validation on a specific operation call
await myColl.findOne({ title: 'Cam Jansen'}, { enableUtf8Validation: false });

如果您的应用程序在启用 enableUtf8Validation 选项时从 MongoDB 读取无效的 UTF-8,则会引发包含以下消息的 BSONError

Invalid UTF-8 string in BSON document

enableUtf8Validation 设置会自动应用于包含该设置的对象实例的作用域,以及调用该实例创建的任何其他对象。

例如,如果调用中包含用于实例化数据库对象的选项,则从该对象构造的任何集合实例都会继承该设置。对该集合实例调用的任何操作也会继承该设置。

const database = client.db('books', { enableUtf8Validation: false });
// The collection inherits the UTF-8 validation disabled setting from the database
const myColl = database.collection('mystery');
// CRUD operation runs with UTF-8 validation disabled
await myColl.findOne({ title: 'Encyclopedia Brown' });

您可以在构造对象实例或调用操作时,在任何作用域级别覆盖该设置。

例如,如果您对集合对象禁用验证,则可覆盖针对该集合的各个增删改查操作调用中的设置。

const collection = database.collection('mystery', { enableUtf8Validation: false });
// CRUD operation runs with UTF-8 validation enabled
await myColl.findOne({ title: 'Trixie Belden' }, { enableUtf8Validation: true });
// CRUD operation runs with UTF-8 validation disabled
await myColl.findOne({ title: 'Enola Holmes' });

后退

未定义的值