[iOS / Swift] Codable & CodingKeys

🍎 Codable이란?

Swift에서 서버와 데이터를 주고받을 때, 서버의 JSON 데이터를 우리 앱의 구조체나 클래스 형태로 바꿔야 할 때가 많습니다.

이때 사용하는 것이 바로 Codable입니다! 

공식 문서에 따르면 Codable은 자신을 외부 표현으로 변환하거나(Encode),

외부 표현으로부터 자신으로 변환할 수 있는(Decode) 타입이에요.

즉, Swift의 객체를 JSON으로 바꾸거나, JSON을 Swift 객체로 바꾸는 역할을 하는 프로토콜인거죠. 

 

Codable은 사실 두 개의 프로토콜이 합쳐진 형태인데요 !

프로토콜	역할
Encodable	자신을 JSON 같은 외부 데이터로 인코딩할 수 있습니다.
Decodable	외부 데이터를 자신으로 디코딩할 수 있습니다.
Codable	Encodable + Decodable 둘 다 가능

 

Codable을 채택했다는 것은 그 타입이 인코딩도 되고, 디코딩도 되는 타입이라는 뜻입니다.

또한 Codable은 프로토콜이기 때문에 struct, class, enum 등 모든 타입에서 채택하여 사용할 수 있습니다.

 

예를 들어, 앱에서 사용자 정보를 저장한다고 가정해봅시다.

struct User: Codable {
    let name: String
    let age: Int
}

 

이 구조체는 이제 JSON으로 변환할 수도 있고, JSON 데이터를 받아서 다시 User 타입으로 바꿀 수도 있는거죠.

 

Encoding (Swift → JSON)

서버로 보낼 데이터를 JSON으로 바꾸려면 아래와 같은 JSONEncoder를 사용합니다.

struct User: Codable {
    let name: String
    let age: Int
}

let me = User(name: "제로", age: 23)

let encoder = JSONEncoder()

if let data = try? encoder.encode(me),
   let jsonString = String(data: data, encoding: .utf8) {
    print(jsonString)
}

 

출력 결과는 이렇게 나오겠죠?

{"name":"제로","age":23}

 

이게 바로 Swift 구조체가 JSON 형태로 바뀐 모습입니다.

 

팁: JSONEncoder는 기본적으로 한 줄로 출력되기 때문에, outputFormatting 옵션을 설정하면 보기 좋게 줄바꿈이 들어간 JSON을 출력할 수 있어요! 

 

Decoding (JSON → Swift)

이번에는 서버에서 JSON 데이터를 받아 User로 변환하는 경우를 봅시다.

struct User: Codable {
    let name: String
    let age: Int
}

let jsonData = """
{"name": "제로", "age": 23}
""".data(using: .utf8)!

let decodedUser = try? JSONDecoder().decode(User.self, from: jsonData)
print(decodedUser?.name ?? "")

 

decode(_:from:) 메서드에 제네릭 타입(User.self)을 넘겨주면, JSON 데이터를 알아서 해당 타입으로 바꿔줍니다.

이 과정이 바로 디코딩이에요!

 

Optional 속성과 기본값

 

실제 API를 다루다 보면 값이 null이거나 아예 키가 빠진 JSON이 종종 있습니다.

이럴 때는 어떻게 해줘야 할까요?

 

해당 속성을 Optional로 선언해주면 됩니다!

struct User: Codable {
    let name: String
    let age: Int?
}

 

 

만약 값이 없을 때 기본값을 주고 싶다면 decodeIfPresent를 활용할 수도 있어요.

struct User: Codable {
    let name: String
    let age: Int

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        name = try container.decode(String.self, forKey: .name)
        age = try container.decodeIfPresent(Int.self, forKey: .age) ?? 0
    }
}

 

이렇게 하면 age가 없거나 null이어도 자동으로 0이 들어가겠죠?

 

---

CodingKeys

서버에서 오는 JSON이 snake_case로 되어 있는 경우가 많습니다.

예를 들어 이런 JSON이 왔다고 해볼까요?

{
  "user_name": "제로",
  "profile_image_url": "<https://example.com/me.png>"
}

 

Swift에서는 보통 camelCase를 쓰기 때문에 이 이름들을 직접 연결해줘야 합니다. 

하나하나 이름을 바꿔주려면 오류도 많이 생기고 번거롭겠죠?

 

이때 사용하는 게 바로 CodingKeys입니다.

struct User: Codable {
    let userName: String
    let profileImageURL: String

    enum CodingKeys: String, CodingKey {
        case userName = "user_name"
        case profileImageURL = "profile_image_url"
    }
}

 

이렇게 해두면 서버에서 받은 user_name이 userName으로, profile_image_url이 profileImageURL로 자동 매핑됩니다.

 

자동 변환 옵션

CodingKeys를 하나하나 적기 귀찮을 때가 있죠? 그런 분들을 위한 자동 변환 옵션입니다.

바로 keyDecodingStrategy인데요! 

 

해당 속성을 이용해서 자동으로 snake_case → camelCase 변환을 적용할 수 있습니다.

let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase

 

이 옵션을 설정해두면 JSON의 user_name이 자동으로 Swift의 userName으로 바뀝니다.

덕분에 CodingKeys를 따로 작성하지 않아도 돼서 코드가 훨씬 깔끔해져요.

 

다만, 한 가지 주의할 점이 있습니다!

keyDecodingStrategy는 단순히 이름 규칙만 변환해주는 기능이기 때문에, desc → description처럼 이름 자체가 전혀 다른 경우에는 여전히 CodingKeys를 사용해서 직접 매핑해줘야 합니다.