Swift Academy · Aula

CodingKeys para Renomeação

Associe nomes diferentes de propriedades e do JSON.

CodingKeys para Renomeação é uma aula grátis de Swift Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Swift Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Swift Academy inclui 4 aulas no total.

Por que renomear chaves?

As APIs JSON costumam usar nomes diferentes dos nomes das propriedades Swift — first_name em vez de firstName. Um enum CodingKeys faz a ligação entre os dois sem alterar a API do seu modelo.

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

print("CodingKeys maps firstName to first_name")

Anatomia de CodingKeys

CodingKeys é um enum aninhado que está em conformidade com String, CodingKey. Cada caso corresponde ao nome de uma propriedade; seu valor bruto é a chave JSON a ser usada.

import Foundation

struct Product: Codable {
    var productName: String
    var unitPrice: Double
    enum CodingKeys: String, CodingKey {
        case productName = "product_name"
        case unitPrice = "unit_price"
    }
}

print(Product.CodingKeys.productName.rawValue)

Decodificando com chaves renomeadas

Durante a decodificação, o decodificador procura cada propriedade usando o valor bruto em CodingKeys, portanto um JSON em snake_case preenche propriedades em camelCase.

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

let json = "{\"first_name\":\"Ada\"}"
let u = try JSONDecoder().decode(User.self, from: json.data(using: .utf8)!)
print(u.firstName)

Codificando com chaves renomeadas

A codificação usa o mesmo mapeamento no sentido inverso: o JSON de saída contém as chaves correspondentes aos valores brutos, não os nomes das propriedades Swift.

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

let data = try JSONEncoder().encode(User(firstName: "Ada"))
print(String(data: data, encoding: .utf8)!)

Listando todas as propriedades

Depois que você adiciona um enum CodingKeys, ele deve incluir um caso para cada propriedade que deseja codificar ou decodificar. Os casos mantidos sem valor bruto usam o nome da propriedade exatamente como está.

import Foundation

struct Item: Codable {
    var id: Int
    var displayName: String
    enum CodingKeys: String, CodingKey {
        case id
        case displayName = "display_name"
    }
}

let data = try JSONEncoder().encode(Item(id: 1, displayName: "Pen"))
print(String(data: data, encoding: .utf8)!)

Omitindo uma propriedade

Deixar uma propriedade fora de CodingKeys a exclui da codificação e da decodificação. Essa propriedade deve ter um valor padrão para que o inicializador sintetizado ainda possa construir o tipo.

import Foundation

struct User: Codable {
    var name: String
    var cachedToken: String = "none"
    enum CodingKeys: String, CodingKey {
        case name
    }
}

let u = try JSONDecoder().decode(User.self, from: "{\"name\":\"Ada\"}".data(using: .utf8)!)
print(u.name, u.cachedToken)

Renomeando várias chaves

Mapeie quantas chaves forem necessárias. Cada caso associa uma propriedade Swift à chave JSON exata esperada pelo servidor.

import Foundation

struct Account: Codable {
    var userId: Int
    var isVerified: Bool
    enum CodingKeys: String, CodingKey {
        case userId = "user_id"
        case isVerified = "is_verified"
    }
}

let json = "{\"user_id\":7,\"is_verified\":true}"
let a = try JSONDecoder().decode(Account.self, from: json.data(using: .utf8)!)
print(a.userId, a.isVerified)

Mapeando para nomes mais claros

CodingKeys não serve apenas para snake_case. Use-o para renomear chaves enigmáticas da API com nomes claros de propriedades Swift.

import Foundation

struct Reading: Codable {
    var temperature: Double
    enum CodingKeys: String, CodingKey {
        case temperature = "t"
    }
}

let json = "{\"t\":19.5}"
let r = try JSONDecoder().decode(Reading.self, from: json.data(using: .utf8)!)
print(r.temperature)

CodingKeys com tipos aninhados

Cada tipo Codable tem seu próprio CodingKeys. Uma estrutura aninhada pode renomear suas próprias chaves independentemente do tipo pai.

import Foundation

struct Meta: Codable {
    var createdAt: String
    enum CodingKeys: String, CodingKey { case createdAt = "created_at" }
}
struct Doc: Codable { var title: String; var meta: Meta }

let json = "{\"title\":\"A\",\"meta\":{\"created_at\":\"today\"}}"
let d = try JSONDecoder().decode(Doc.self, from: json.data(using: .utf8)!)
print(d.meta.createdAt)

Conversão de ida e volta com chaves renomeadas

O mesmo CodingKeys orienta as duas direções, portanto um valor é codificado em snake_case e decodificado de volta para o mesmo valor Swift.

import Foundation

struct User: Codable {
    var firstName: String
    var lastName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
        case lastName = "last_name"
    }
}

let u = User(firstName: "Ada", lastName: "Lovelace")
let data = try JSONEncoder().encode(u)
let back = try JSONDecoder().decode(User.self, from: data)
print(back.firstName, back.lastName)

Quando recorrer a CodingKeys

Use um enum CodingKeys explícito quando chaves individuais precisarem de controle preciso, quando apenas algumas chaves forem diferentes ou quando você precisar omitir uma propriedade. Para uma API uniformemente em snake_case, uma estratégia de decodificação pode ser mais simples.

import Foundation

struct Event: Codable {
    var eventName: String
    var startTime: String
    enum CodingKeys: String, CodingKey {
        case eventName = "name"
        case startTime = "start_time"
    }
}

let json = "{\"name\":\"Launch\",\"start_time\":\"10:00\"}"
let e = try JSONDecoder().decode(Event.self, from: json.data(using: .utf8)!)
print(e.eventName, e.startTime)

Verificação rápida: CodingKeys

Teste sua compreensão sobre renomeação de chaves.

Recapitulação: CodingKeys para renomeação

Você aprendeu a controlar as chaves com precisão:

Declare enum CodingKeys: String, CodingKey aninhado no tipo.
O valor bruto de cada caso é a chave JSON; os casos orientam tanto a codificação quanto a decodificação.
Liste todas as propriedades que deseja codificar; omitir uma delas a exclui — ela precisa ter um valor padrão.
Tipos aninhados têm seus próprios CodingKeys independentes.

Perguntas Frequentes

A aula “CodingKeys para Renomeação” é grátis?

Sim — o texto completo de “CodingKeys para Renomeação” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Swift Academy, atualize para CoddyKit PRO. O curso de Swift Academy inclui 4 aulas no total.

O que vou aprender em “CodingKeys para Renomeação”?

Associe nomes diferentes de propriedades e do JSON. Você pratica Swift Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Swift Academy?

Nenhuma experiência prévia é necessária. Swift Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “CodingKeys para Renomeação”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Swift Academy?

Sim. Cada aula de Swift Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

CodingKeys para Renomeação
Estratégias de Decodificação de Chaves e Datas
encode(to:) e init(from:) Manuais
Decodificação de JSON Heterogêneo

← Voltar para Swift Academy