Pular para o conteúdo
FrAIFlow

Soluções / Codificação e URLs

Corrija UTF-8 malformado com codificação percentual

Um valor de URL chega ao aplicativo, mas decodeURIComponent() lança URIError. Antes de substituir pontuação, diferencie duas falhas: um escape percentual incompleto e um escape de byte completo que não representa UTF-8 válido.

Duas falhas diferentes de decodificação
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

Encontre a etapa em que o valor muda

Suponha que uma caixa de busca aceite 50% off, mas abrir o link resultante derrube a página. O sinal de porcentagem é texto comum na caixa de busca. Ele só ganha significado especial quando o código o trata como um componente de URL já codificado. Anote o valor esperado em cada etapa: texto do usuário, URL serializada e valor lido pela página destinatária. Você procura uma incompatibilidade de codificação, não pontuação para apagar.

Use uma amostra inofensiva em vez de copiar um link real de redefinição de senha ou consulta de cliente para um console ou issue pública. Primeiro, tente decodeURIComponent("%25"): o resultado esperado é um único sinal de porcentagem. Depois, teste a amostra problemática com a função protegida da seção “Rejeite entradas malformadas sem derrubar a página”. Se o controle válido funciona e a amostra falha, o decodificador não está universalmente quebrado; os dados fornecidos precisam de investigação.

Diferencie um escape quebrado de UTF-8 inválido

Um % isolado não tem um valor de byte com dois dígitos. Já %92 é sintaticamente um escape de byte, mas esse byte não pode aparecer sozinho em UTF-8. Relatos públicos mostram os dois erros, incluindo bytes antigos de aspas e um %AF isolado.

decodeURIComponent("%");          // URIError
 decodeURIComponent("%92");        // URIError
 decodeURIComponent("%25");        // %
 decodeURIComponent("%C2%AF");     // ¯
 decodeURIComponent("%E2%80%99"); // ’

A amostra preservada de Node v24.19.0 reproduziu esses resultados e também testou %91, %AF e a aspa esquerda em UTF-8. O texto do erro pode variar no navegador; a evidência útil é aceitar ou rejeitar a entrada exata.

Faça os bytes corresponderem ao texto pretendido
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

Construa consultas sem concatenar escapes percentuais manualmente

Para um novo link, passe o texto original à API URL e deixe que ela serialize o parâmetro. Do lado destinatário, leia o parâmetro pela mesma API. Não decodifique imediatamente de novo o valor retornado:

const link = new URL("https://example.com/search");
link.searchParams.set("q", "50% off & café");
const received = new URL(link.href).searchParams.get("q");
console.log(received); // 50% off & café

Esta é uma URL de exemplo, não um endpoint FrAIFlow. A distinção importante é entre componente codificado e valor já interpretado. Uma segunda decodificação pode transformar texto perfeitamente legítimo, como 50% off, em uma exceção. Lembre também que o sinal de mais em parâmetros de consulta no estilo formulário recebe tratamento diferente de um mais literal passado diretamente a decodeURIComponent(); use o parser correspondente ao formato.

Corrija o produtor em vez de adivinhar caracteres

Preserve privadamente a amostra exata que falha e pergunte ao produtor qual codificação utilizou. Um %92 isolado pode sugerir uma convenção antiga de bytes, mas o byte sozinho não determina sua origem. Não substitua silenciosamente por um apóstrofo em IDs de contas, assinaturas ou nomes de arquivos. Retorne um erro útil, preserve a entrada original para o usuário e corrija a codificação na fonte quando possível.

Depois da mudança, teste uma porcentagem literal, uma palavra acentuada, uma aspa curva, um sinal de mais e um e comercial. Cada valor deve sobreviver sem mudanças ao percurso criar link → abrir link → ler valor. Entradas malformadas devem produzir seu erro controlado, não parar o restante da página. Essas verificações validam o contrato de formato; não justificam decodificar repetidamente até que uma string pareça legível.

Rejeite entradas malformadas sem derrubar a página

function decodeComponent(value) {
  try { return { ok: true, value: decodeURIComponent(value) }; }
  catch (error) {
    if (!(error instanceof URIError)) throw error;
    return { ok: false, error: "Invalid encoded component" };
  }
}

Esse ponto de entrada informa a falha sem alterar silenciosamente um identificador. Ele não descobre uma codificação de origem desconhecida. Decodifique apenas o número de vezes exigido pelo contrato do formato: uma porcentagem restante depois de uma decodificação bem-sucedida não justifica outra rodada. Evite o obsoleto unescape() como correção UTF-8 e mantenha tokens ou valores privados de consulta fora de logs públicos de diagnóstico.

Um escape percentual isolado e o antigo %92 causam URIError; o UTF-8 %E2%80%99 é decodificado como aspa simples direita.
Explicação original preservada.
Saída registrada do teste sintético de correção de UTF-8 malformado com codificação percentual
Resultados registrados de decodeURIComponent do Node.js com entradas percentualmente codificadas válidas e malformadas. É uma captura da saída de teste registrada, não do aplicativo do autor do relato. Abrir a imagem de evidência em tamanho original.

Fontes e leituras relacionadas