Validação UTF-8
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.
O driver habilita a validação UTF-8 por padrão. Ele verifica os documentos em busca de caracteres que não estejam codificados em um formato UTF-8 válido ao transferir dados entre seu aplicativo e o MongoDB.
Observação
A versão atual do driver do Node.js substitui automaticamente caracteres UTF-8 inválidos por caracteres UTF-8 válidos alternativos antes da validação quando você envia dados para MongoDB. Portanto, a validação só lança um erro quando a configuração está habilitada e o driver recebe dados de documento UTF-8 inválidos do 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 deve executar 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' });