Menu Docs
Página inicial do Docs
/ / /
Node.js
/ /

Validação UTF-8

Nesta página

  • Visão geral
  • Especifique a configuração de validação UTF-8
  • Definir o escopo de validação

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.

É 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

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' });

Voltar

Valores indefinidos