Swift encode URL: 5 erros fatais e como evitá-los

Swift encode URL: por que seu código falha com caracteres cirílicos e espaços

Todo desenvolvedor que já enviou uma requisição de rede em Swift já enfrentou essa dor: você monta a URL, insere os parâmetros, e o servidor retorna um erro 400 ou, pior ainda, — ignora silenciosamente a requisição. Familiar? Na maioria das vezes, o problema está na codificação incorreta da URL. Parece simples — pegue a string, substitua espaços por %20, e pronto. Mas Swift (como qualquer linguagem rigorosa) não perdoa gambiarras.

Neste artigo, analisaremos os 5 erros mais comuns ao fazer Swift encode URL, que acumulam milhares de visualizações no Stack Overflow. Você aprenderá como evitá-los e escrever código confiável que funciona com qualquer dado — de letras inglesas a caracteres cirílicos complexos e símbolos especiais.

Erro nº1: Usar addingPercentEncoding com o conjunto de caracteres errado

Esta é, sem dúvida, a armadilha mais popular. Muitos iniciantes veem o método addingPercentEncoding(withAllowedCharacters:) e pensam: "Ah, perfeito!". Mas passam .urlHostAllowed ou .urlPathAllowed para a URL inteira. O resultado — um crash ou uma requisição incorreta.

Por que isso não funciona?

Cada parte da URL (esquema, host, caminho, parâmetros de consulta) tem seu próprio conjunto de caracteres permitidos. Se você codificar a URL inteira como host, perderá as barras e os dois-pontos. Se codificar como caminho, quebrará a query-string.

// ❌ Erro: codificando a URL inteira como hostlet urlString = "https://example.com/caminho?nome=João & sobrenome=Silva"let encoded = urlString.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)// Resultado: "https%3A%2F%2Fexample.com%2Fcaminho%3Fnome%3DJo%C3%A3o%20%26%20sobrenome%3DSilva"// O servidor não entenderá essa URL

Lembre-se da regra de ouro: codifique cada parte da URL separadamente ou use URLComponents.

Abordagem correta: URLComponents

// ✅ Correto: usando URLComponentsvar components = URLComponents()components.scheme = "https"components.host = "example.com"components.path = "/caminho"components.queryItems = [    URLQueryItem(name: "nome", value: "João & Silva"),    URLQueryItem(name: "sobrenome", value: "Santos")]

if let url = components.url {    print(url.absoluteString)    // "https://example.com/caminho?nome=Jo%C3%A3o%20%26%20Silva&sobrenome=Santos"}

URLComponents aplica automaticamente a percent encoding correta para cada componente. Isso elimina dores de cabeça e torna o código mais limpo.

Erro nº2: Ignorar queryItems em favor da montagem manual da string

"Pra que esses componentes? Vou só concatenar a string com +". Pensamento familiar? E isso leva ao segundo erro popular. Montar a query-string manualmente é o caminho direto para bugs.

// ❌ Erro: montagem manual da query-stringlet nome = "João & Silva"let query = "nome=\\(nome)&idade=25"let urlString = "https://example.com?\\(query)"// Problema: o & no nome será interpretado como separador de parâmetros

Mesmo que você substitua espaços, esquecerá de &, #, ? e outros caracteres especiais. E se o parâmetro vier do usuário? Espere injeções e requisições quebradas.

Solução: sempre use queryItems

// ✅ Correto: queryItems faz todo o trabalho para vocêvar components = URLComponents(string: "https://example.com")!components.queryItems = [    URLQueryItem(name: "nome", value: "João & Silva"),    URLQueryItem(name: "idade", value: "25"),    URLQueryItem(name: "q", value: "Swift encode URL tutorial")]

if let url = components.url {    print(url.absoluteStr