Visão geral
Neste guia, você pode aprender como habilitar ou desabilitar o recurso de validação UTF-8 do driver do Node.js. UTF-8 é uma especificação de codificação de caracteres que garante compatibilidade e apresentação consistente na maioria dos sistemas operacionais, aplicativos e conjuntos de caracteres de idioma.
Se você habilitar a validação, o driver lançará um erro ao tentar converter dados que contenham caracteres UTF-8 inválidos. A validação adiciona sobrecarga de processamento, pois precisa verificar os dados.
Se você desabilitar a validação, seu aplicativo evitará a sobrecarga de processamento de validação, mas não poderá garantir a apresentação consistente de dados UTF-8 inválidos.
Por padrão, o driver habilita a validação UTF-8 em dados do MongoDB. Ele verifica os documentos recebidos em busca de caracteres que não estejam codificados em um formato UTF-8 válido ao analisar os dados enviados do MongoDB para seu aplicação.
Observação
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.
Leia as seções abaixo para saber como definir a validação UTF-8 usando o driver Node.js.
Especifique a configuração de validação UTF-8
É possível especificar se o driver executa a validação UTF-8 definindo a configuração enableUtf8Validation no parâmetro de opções quando você cria um cliente, faz referência a um banco de dados ou collection, ou chama uma operação CRUD. Se você omitir a configuração, o driver habilitará a validação UTF-8 .
Consulte a seguir exemplos de código que demonstram como desabilitar a validação UTF-8 no cliente, banco de dados, coleção ou operação CRUD:
// 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 });
Se seu aplicativo ler UTF-8 inválido do MongoDB enquanto a opção enableUtf8Validation estiver habilitada, ele lançará um BSONError que contém a seguinte mensagem:
Invalid UTF-8 string in BSON document
Definir o escopo de validação
A configuração enableUtf8Validation se aplica automaticamente ao escopo da instância de objeto na qual você a incluiu e a quaisquer outros objetos criados por chamadas nessa instância.
Por exemplo, se você incluir a opção na chamada para instanciar um objeto de banco de dados, qualquer instância de coleção construída a partir desse objeto herdará a configuração. Todas as operações que você chama nessa instância de coleção também herdam a configuração.
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' });
Você pode substituir a configuração em qualquer nível de escopo incluindo-a ao construir a instância do objeto ou ao chamar uma operação.
Por exemplo, se você desabilitar a validação no objeto de collection, poderá substituir a configuração em chamadas de operação CRUD individuais nessa collection.
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' });