31 · 직렬화와 스키마

직렬화는 앱의 경계를 넘는 모든 데이터가 반드시 지나는 관문이다. 서버 응답, 로컬 저장, 앱 익스텐션 간 전달, 딥링크 페이로드가 전부 여기를 통과한다.

이 챕터의 버그들은 앞선 장들과 같은 성질을 갖는다 — 조용하다. 프로퍼티가 인코딩에서 빠져도 컴파일은 통과하고, 상속 계층의 필드가 사라져도 에러가 없으며, 키 변환 전략이 원본 키를 이기고 keyNotFound를 낸다.

P0 09장 Q4에서 데이터베이스 스키마 진화를 다뤘다 — "코드는 배포로 한 번에 교체되지만 데이터는 각 기기에 과거 버전 그대로 남아 있다"는 문제였다. 이 챕터는 같은 문제를 클라이언트-서버 JSON 계약 축에서 본다. 여기서는 양쪽 모두가 서로 다른 속도로 바뀐다.

Q1. Codable은 무엇을 자동 생성하며 어디서 무너지는가?

CS 원리

직렬화 구현 방식은 크게 셋이고, 각각 다른 시점에 실패한다.

Swift는 세 번째를 골랐다. 이 선택의 값어치는 "직렬화할 수 없는 타입을 담으면 빌드가 안 된다"는 보장이다. 런타임에 "이 필드는 인코딩 못 합니다"라는 예외를 만나는 대신, 코드를 쓰는 순간 알게 된다.

그런데 합성은 타입 단위로 일어난다. 클래스 상속에서는 서브클래스가 자기 프로퍼티만 보고 합성하는데, 상위 타입이 이미 Codable을 채택했다면 서브클래스는 그 구현을 상속받는다. 상속받은 init(from:)은 상위 타입의 프로퍼티만 안다.

여기서 정적 분석이 뚫린다. 컴파일러 입장에서는 프로토콜 요구사항이 이미 만족돼 있으므로 합성할 이유가 없고, 새 프로퍼티가 빠진다는 사실은 타입 시스템이 표현하지 않는 문제다.

iOS에서는

합성이 거부되는 경우는 컴파일러가 알려준다.

struct Fine: Codable {          // ✅ 전부 Codable
    let id: Int
    let name: String
    let tags: [String]
}

struct Broken: Codable {        // ❌ 컴파일 에러
    let id: Int
    let handler: () -> Void     // 함수 타입은 Codable 이 아니다
    let any: any Shape          // 실존 타입도 합성 불가
}
//   "type 'Broken' does not conform to protocol 'Decodable'"
//   → 정적으로 막힌다. 이게 이 설계의 값어치다.

클래스 상속은 다르다. 에러 없이 넘어간다.

class Animal: Codable {
    var name: String = ""
}

class Dog: Animal {
    var breed: String = ""      // ⚠️ 에러도 경고도 없다
}

let dog = Dog(); dog.name = "바둑"; dog.breed = "진돗개"
let data = try JSONEncoder().encode(dog)
String(data: data, encoding: .utf8)      // {"name":"바둑"}  ← breed 가 없다

해결은 직접 구현하고 super를 명시적으로 다루는 것이다.

class Dog2: Animal {
    var breed: String = ""

    private enum CodingKeys: String, CodingKey { case breed }

    override func encode(to encoder: Encoder) throws {
        var c = encoder.container(keyedBy: CodingKeys.self)
        try c.encode(breed, forKey: .breed)
        try super.encode(to: c.superEncoder())      // 상위를 별도 컨테이너로 (Q3)
    }

    required init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: CodingKeys.self)
        breed = try c.decode(String.self, forKey: .breed)
        try super.init(from: c.superDecoder())
    }
}

연관값 enum도 SE-0295(Swift 5.5+)부터 합성된다. 다만 모양을 알아야 한다.

enum Event: Codable {
    case login(userId: String)
    case logout
}
// {"login":{"userId":"u1"}}
// {"logout":{}}                ← 연관값이 없어도 빈 객체다. 문자열이 아니다.
//
// 서버가 흔히 쓰는 {"type":"login","userId":"u1"} 형태와는 스키마가 다르다 (Q5)

실험 · 도구

상속 누락을 직접 재현해 보자.

import Foundation

class Base: Codable { var id = 1 }
class Child: Base { var extra = "숨은 값" }

let enc = JSONEncoder(); enc.outputFormatting = .sortedKeys
print(String(data: try enc.encode(Child()), encoding: .utf8)!)
//   {"id":1}      ← extra 가 없다. 경고 하나 없이.

// 디코딩도 마찬가지다
let json = #"{"id":9,"extra":"서버가 보낸 값"}"#.data(using: .utf8)!
let c = try JSONDecoder().decode(Child.self, from: json)
print(c.id, c.extra)      // 9  "숨은 값"   ← 서버 값이 무시됐다

코드베이스에서 위험한 조합을 찾는다.

# Codable 을 채택한 클래스의 서브클래스 — 누락 후보
grep -rn "class .*: .*Codable" --include=*.swift . > /tmp/codable-classes.txt
while read -r line; do
  cls=$(echo "$line" | sed -E 's/.*class ([A-Za-z0-9_]+).*/\1/')
  grep -rn "class .*: *$cls\b" --include=*.swift . | grep -v "$cls *:"
done < /tmp/codable-classes.txt

# 인코딩 결과에 기대 필드가 다 있는지 테스트로 고정하는 편이 확실하다
grep -rn "encode(.*)" --include=*Tests*.swift . | head

프로젝트 적용

1. 직렬화 모델은 struct로 만든다. 상속 구멍이 아예 생기지 않고, 값 의미론이라 동시성에도 유리하다(35장).
2. 상속이 불가피하면 encode(to:)·init(from:)을 직접 쓴다. superEncoder()로 상위를 격리한다(Q3).
3. 왕복 테스트를 만든다. 인코딩 → 디코딩 후 모든 필드가 살아 있는지 검사하면 누락이 잡힌다.
4. 도메인 모델과 전송 모델을 분리한다. 서버 스키마가 바뀔 때 도메인이 흔들리지 않고, 상속이 필요한 도메인 계층과 Codable이 분리된다.
5. 연관값 enum의 인코딩 모양을 확인하고 서버와 합의한다. 합성 결과가 서버 기대와 다를 수 있다(Q5).

꼬리 질문

// 전송 모델 — 서버 스키마를 그대로 반영, 전부 옵셔널
struct UserDTO: Decodable {
    let id: Int?
    let usr_nm: String?
    let created_at: String?
}

// 도메인 모델 — 앱이 원하는 형태, 불변식이 지켜진 상태
struct User {
    let id: Int
    let displayName: String
    let createdAt: Date
}

extension UserDTO {
    func toDomain() throws -> User {
        guard let id, let name = usr_nm, !name.isEmpty,
              let raw = created_at, let date = try? Date(raw, strategy: .iso8601)
        else { throw MappingError.invalid(self) }
        return User(id: id, displayName: name, createdAt: date)
    }
}

import Testing
import Foundation

@Test func 왕복이_보존된다() throws {
    let original = Dog2(name: "바둑", breed: "진돗개")

    let data = try JSONEncoder().encode(original)
    let back = try JSONDecoder().decode(Dog2.self, from: data)

    #expect(back.name == original.name)
    #expect(back.breed == original.breed)     // 상속 누락이 여기서 잡힌다
}

@Test func 인코딩_키가_기대와_일치한다() throws {
    let data = try JSONEncoder().encode(Dog2(name: "바둑", breed: "진돗개"))
    let obj = try JSONSerialization.jsonObject(with: data) as! [String: Any]

    // 키 집합을 명시적으로 고정한다 — 필드가 빠지거나 늘면 실패한다
    #expect(Set(obj.keys) == ["breed", "super"])
}

@Test func 서버_스키마와_일치한다() throws {
    // 실제 서버 응답을 픽스처로 고정한다
    let fixture = try Data(contentsOf: Bundle.module.url(forResource: "user_v3", withExtension: "json")!)
    let user = try JSONDecoder().decode(UserDTO.self, from: fixture)
    #expect(user.id != nil)
}

// 변환 래퍼 — Codable 이 아닌 타입을 Data 로 우회한다
struct AttributedTextBox: Codable {
    let value: NSAttributedString

    init(_ v: NSAttributedString) { value = v }

    init(from decoder: Decoder) throws {
        let data = try decoder.singleValueContainer().decode(Data.self)
        guard let s = try NSKeyedUnarchiver.unarchivedObject(
                ofClass: NSAttributedString.self, from: data) else {
            throw DecodingError.dataCorruptedError(
                in: try decoder.singleValueContainer(),
                debugDescription: "NSAttributedString 복원 실패")
        }
        value = s
    }

    func encode(to encoder: Encoder) throws {
        let data = try NSKeyedArchiver.archivedData(
            withRootObject: value, requiringSecureCoding: true)
        var c = encoder.singleValueContainer()
        try c.encode(data)
    }
}

Q2. CodingKeys에서 빼면 어떻게 되는가?

CS 원리

CodingKeys는 필드 이름과 외부 표현의 사상을 선언하는 장치다. 합성 규칙은 단순하다 — 이 열거형에 있는 케이스만 직렬화 대상이 된다.

여기서 진단의 비대칭이 생긴다. 컴파일러가 잡을 수 있는 것과 없는 것이 갈린다.

세 번째가 위험하다. 합법적인 선택이기 때문이다 — 캐시된 파생값이나 로컬 전용 상태를 제외하는 것은 정당한 의도다. 컴파일러는 의도한 제외와 실수로 빠뜨린 것을 구별할 수 없다.

일반화하면 "기본값이 있으면 누락이 성공처럼 보인다"는 문제다. 기본값은 편의를 주지만, 값이 오지 않았다는 사실을 감춘다. 이는 P1 21장 Q6의 페일 사일런트 구조와 같다.

iOS에서는

세 경우를 실제 코드로 보면 차이가 분명하다.

struct Car: Codable {
    var name: String
    let speed: Int = 100          // ⚠️ 경고: 초기값이 있어 덮어쓸 수 없으므로 디코딩되지 않음
    var mileage: Int = 0          // CodingKeys 에서 빼면 경고조차 없다
    var owner: String             // 기본값 없음 — 빼면 컴파일 에러

    enum CodingKeys: String, CodingKey {
        case name, speed, owner   // mileage 제외 — 진단 없이 조용히 빠진다
    }
}

let json = #"{"name":"A","speed":300,"mileage":5000,"owner":"김"}"#.data(using: .utf8)!
let car = try JSONDecoder().decode(Car.self, from: json)
car.speed        // 100    ← 서버가 300 을 보냈지만 초기값이 이긴다
car.mileage      // 0      ← 제외했으므로 무시됐다

키 이름 매핑이 CodingKeys의 주 용도다.

struct User: Codable {
    let displayName: String
    let profileImageURL: URL?

    enum CodingKeys: String, CodingKey {
        case displayName = "display_name"
        case profileImageURL = "profile_image_url"
    }
}
//   자동 변환 전략(convertFromSnakeCase)과 섞어 쓰면 안 된다 — Q6 에서 다룬다

의도적 제외는 명시하는 것이 좋다. 주석이나 별도 타입으로 의도를 남긴다.

struct Article: Codable {
    let id: String
    let title: String

    /// 로컬 전용 — 서버로 보내지 않고 받지도 않는다 (의도적으로 CodingKeys 에서 제외)
    var isRead: Bool = false

    enum CodingKeys: String, CodingKey { case id, title }
}

실험 · 도구

누락을 자동으로 잡으려면 키 집합을 검사하는 것이 가장 확실하다.

import Foundation

/// 인코딩 결과의 최상위 키 집합을 뽑는다
func encodedKeys<T: Encodable>(_ v: T) throws -> Set<String> {
    let data = try JSONEncoder().encode(v)
    let obj = try JSONSerialization.jsonObject(with: data)
    guard let dict = obj as? [String: Any] else { return [] }
    return Set(dict.keys)
}

// Mirror 로 저장 프로퍼티 이름을 얻어 대조한다
func storedProperties<T>(_ v: T) -> Set<String> {
    Set(Mirror(reflecting: v).children.compactMap(\.label))
}

let car = Car(name: "A", owner: "김")
let missing = storedProperties(car).subtracting(
    try encodedKeys(car).union(["speed"]))   // 매핑된 키는 별도 처리
print("인코딩에서 빠진 프로퍼티: \(missing)")   // ["mileage"]

테스트로 고정하면 필드가 추가될 때 자동으로 잡힌다.

@Test func 모든_필드가_인코딩된다() throws {
    let sample = Car(name: "A", owner: "김")
    let intentionallyExcluded: Set<String> = ["mileage", "isRead"]

    let props = storedProperties(sample).subtracting(intentionallyExcluded)
    let keys = try encodedKeys(sample)

    // 매핑된 이름을 고려해야 하므로 개수로 1차 확인
    #expect(props.count == keys.count,
            "인코딩 누락 의심 — 프로퍼티 \(props) vs 키 \(keys)")
}

코드베이스 훑기도 유용하다.

# CodingKeys 가 있는 타입의 프로퍼티 수와 케이스 수를 비교한다
grep -rn -A20 "enum CodingKeys" --include=*.swift . | head -40

# let + 초기값 경고를 놓치지 않도록 경고를 에러로 승격한다
# Build Settings › Other Swift Flags 에
#   -warnings-as-errors
# 를 넣으면 이 경고가 빌드를 막는다 (P1 21장 Q6 의 "조용한 실패를 빌드 실패로")

프로젝트 적용

1. 제외는 의도를 주석으로 남긴다. 컴파일러가 구별하지 못하므로 사람이 남겨야 다음 사람이 실수를 알아본다.
2. 경고를 에러로 승격한다. let + 초기값 경고는 실제 버그인 경우가 대부분이다.
3. 서버가 보내는 값을 let + 초기값으로 선언하지 않는다. 초기값이 이겨서 서버 값이 무시된다.
4. 키 집합 테스트를 둔다. 필드를 추가하고 CodingKeys를 안 고치는 실수가 가장 흔하다.
5. 로컬 전용 상태는 아예 다른 타입에 둔다. 직렬화 모델에 섞으면 매번 제외를 관리해야 한다.

꼬리 질문

// ✅ CodingKeys 가 없으면 필드 추가가 자동 반영된다
struct Item: Codable {
    let id: String
    let title: String
    let newField: String        // 추가만 하면 끝
}

// ⚠️ 키 이름 매핑이 필요하다면 — 전부 나열해야 하고 갱신 의무가 생긴다
struct Item2: Codable {
    let id: String
    let createdAt: Date
    enum CodingKeys: String, CodingKey { case id, createdAt = "created_at" }
}

// 서버가 20개 필드를 보내도 3개만 선언하면 나머지는 무시된다
struct Minimal: Decodable {
    let id: String
    let title: String
    let price: Decimal
}
//   서버가 필드를 추가해도 앱은 깨지지 않는다 — 하위 호환의 기본이다

struct StrictItem: Decodable {
    let id: String
    let title: String

    init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: CodingKeys.self)
        id = try c.decode(String.self, forKey: .id)
        title = try c.decode(String.self, forKey: .title)

        // 원본 키 집합과 대조해 예상 밖 키를 로깅한다 (실패시키지는 않는다)
        let known = Set(CodingKeys.allCases.map(\.stringValue))
        let actual = Set(c.allKeys.map(\.stringValue))
        let unknown = actual.subtracting(known)
        if !unknown.isEmpty { logger.notice("알 수 없는 필드: \(unknown)") }
    }

    enum CodingKeys: String, CodingKey, CaseIterable { case id, title }
}

struct A: Decodable { var count: Int = 0 }

try JSONDecoder().decode(A.self, from: #"{}"#.data(using: .utf8)!)          // ✅ count = 0
try JSONDecoder().decode(A.self, from: #"{"count":null}"#.data(using: .utf8)!)
//   ❌ valueNotFound — 기본값이 구제해 주지 않는다

struct B: Decodable {
    private let rawCount: Int?
    var count: Int { rawCount ?? 0 }
    enum CodingKeys: String, CodingKey { case rawCount = "count" }
}

Q3. 세 컨테이너는 무엇이 다르며 언제 직접 쓰는가?

CS 원리

Codable의 설계는 인코딩 형식과 데이터 모델의 분리다. 모델은 "무엇을 저장할지"만 선언하고, 형식(JSON·plist·바이너리)은 인코더가 정한다. 이 사이를 잇는 것이 컨테이너 추상화다.

세 컨테이너는 대부분의 계층적 데이터 형식이 공유하는 세 가지 모양에 대응한다.

• 이름-값 쌍의 집합 — 객체·딕셔너리·레코드
• 순서 있는 나열 — 배열·리스트
• 단일 값 — 스칼라

이 셋으로 JSON뿐 아니라 plist·YAML·CBOR도 표현되므로, 같은 모델을 여러 형식으로 직렬화할 수 있다.

뷰 성질이 중요한 설계 결정이다. 컨테이너가 값을 소비한다면 한 번 읽은 자리를 다시 읽을 수 없지만, 뷰라면 가능하다. 후자를 택했기 때문에 "판별자만 먼저 읽고 나머지를 다시 읽기"가 성립한다. 비용도 작다 — 재파싱이 아니라 이미 만들어진 트리에서 한 번 더 조회하는 정도다.

다만 배열 컨테이너는 예외다. 순서 접근이므로 currentIndex 커서가 전진만 하고, 한 번 지나간 원소로 되돌아갈 수 없다. 이 비대칭을 모르면 배열에서 판별자 패턴을 쓰려다 막힌다.

iOS에서는

중첩 JSON을 평평하게 펴는 것이 가장 흔한 용도다.

// 서버: {"id":1,"meta":{"author":{"name":"김"},"tags":["a","b"]}}
// 앱:   Article(id:1, authorName:"김", tags:["a","b"])

struct Article: Decodable {
    let id: Int
    let authorName: String
    let tags: [String]

    enum CodingKeys: String, CodingKey { case id, meta }
    enum MetaKeys: String, CodingKey { case author, tags }
    enum AuthorKeys: String, CodingKey { case name }

    init(from decoder: Decoder) throws {
        let root = try decoder.container(keyedBy: CodingKeys.self)
        id = try root.decode(Int.self, forKey: .id)

        let meta = try root.nestedContainer(keyedBy: MetaKeys.self, forKey: .meta)
        tags = try meta.decode([String].self, forKey: .tags)

        let author = try meta.nestedContainer(keyedBy: AuthorKeys.self, forKey: .author)
        authorName = try author.decode(String.self, forKey: .name)
    }
}

상속에서는 superEncoder()가 키 충돌을 구조적으로 차단한다.

// ❌ 같은 컨테이너에 상위·하위가 같은 키를 쓰면 조용히 덮어써진다
//    에러가 나지 않으므로 발견이 늦다

// ✅ superEncoder() 는 예약된 "super" 키 아래 별도 컨테이너를 만든다
override func encode(to encoder: Encoder) throws {
    var c = encoder.container(keyedBy: CodingKeys.self)
    try c.encode(breed, forKey: .breed)
    try super.encode(to: c.superEncoder())     // {"breed":"...","super":{"name":"..."}}
}
//   이름을 조심해서 짓는 것과 다르다 — "겹칠 수 없는 구조"를 만드는 것이다

배열 커서의 전진 전용 성질도 실제로 부딪힌다.

init(from decoder: Decoder) throws {
    var arr = try decoder.unkeyedContainer()
    let first = try arr.decode(String.self)     // currentIndex: 0 → 1
    // arr.currentIndex 를 0 으로 되돌릴 방법이 없다

    // 배열 원소별로 판별이 필요하면 원소 단위로 nested 컨테이너를 연다
    while !arr.isAtEnd {
        let element = try arr.nestedContainer(keyedBy: ItemKeys.self)
        let type = try element.decode(String.self, forKey: .type)
        // element 안에서는 재읽기가 가능하다
    }
}

실험 · 도구

재읽기가 실제로 되는지 확인해 보자.

import Foundation

struct Probe: Decodable {
    let a: Int
    let aAgain: Int

    enum K: String, CodingKey { case a }

    init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: K.self)
        a = try c.decode(Int.self, forKey: .a)
        aAgain = try c.decode(Int.self, forKey: .a)     // 같은 키를 두 번 — 문제없다
    }
}

let p = try JSONDecoder().decode(Probe.self, from: #"{"a":7}"#.data(using: .utf8)!)
print(p.a, p.aAgain)      // 7 7

배열 커서는 되돌릴 수 없다는 것도 확인된다.

struct ArrProbe: Decodable {
    init(from decoder: Decoder) throws {
        var arr = try decoder.unkeyedContainer()
        print("시작 index:", arr.currentIndex)      // 0
        _ = try arr.decode(Int.self)
        print("한 번 읽은 뒤:", arr.currentIndex)     // 1
        // 되돌리는 API 가 없다 — 필요하면 원소를 통째로 먼저 디코딩해 보관한다
    }
}
_ = try JSONDecoder().decode(ArrProbe.self, from: "[1,2,3]".data(using: .utf8)!)

인코딩 결과 구조를 확인하는 것도 유용하다.

# 인코딩 결과를 보기 좋게 출력해 구조를 확인한다
swift run MyTool | python3 -m json.tool

# super 키가 실제로 생기는지 확인
echo '{"breed":"진돗개","super":{"name":"바둑"}}' | python3 -m json.tool

프로젝트 적용

1. 합성으로 되는 것은 직접 쓰지 않는다. 컨테이너 코드는 필드 추가 시 갱신 의무가 생기는 수동 코드다.
2. 중첩 평탄화는 DTO 계층에 가둔다. 도메인 모델까지 init(from:)을 직접 쓰면 유지 비용이 커진다.
3. 상속 인코딩에는 반드시 superEncoder()를 쓴다. 키 충돌은 에러 없이 값이 덮어써지는 형태로 나타난다.
4. 배열에서 판별이 필요하면 원소 단위로 컨테이너를 연다. 배열 커서를 되돌리려 하지 않는다.
5. 직접 쓴 init(from:)에는 왕복 테스트를 반드시 붙인다. 합성이 주던 안전망이 사라진 상태다.

꼬리 질문

struct FlexibleID: Decodable {
    let value: String

    init(from decoder: Decoder) throws {
        let c = try decoder.singleValueContainer()

        // 문자열로 먼저 시도
        if let s = try? c.decode(String.self) { value = s; return }
        // 숫자로 시도
        if let i = try? c.decode(Int.self)    { value = String(i); return }
        if let d = try? c.decode(Double.self) { value = String(d); return }

        throw DecodingError.typeMismatch(String.self, .init(
            codingPath: decoder.codingPath,
            debugDescription: "String·Int·Double 중 어느 것도 아님"))
    }
}

let model = Article(...)

// 같은 모델을 세 형식으로
let json = try JSONEncoder().encode(model)
let plist = try PropertyListEncoder().encode(model)
// 서드파티 인코더(CBOR·MessagePack 등)도 같은 프로토콜을 채택한다

// JSON 에서 nan 을 다루려면 전략을 지정한다
let enc = JSONEncoder()
enc.nonConformingFloatEncodingStrategy = .convertToString(
    positiveInfinity: "+inf", negativeInfinity: "-inf", nan: "nan")

// ❌ 전체를 직접 구현 — 필드 추가 시마다 갱신해야 한다
struct Full: Decodable {
    let a: String, b: Int, c: Date, d: [String]
    init(from decoder: Decoder) throws { /* 네 줄 모두 수동 */ }
}

// ✅ 중첩 부분만 별도 타입으로 뽑아 합성을 살린다
struct Meta: Decodable { let author: Author; let tags: [String] }
struct Article2: Decodable {
    let id: Int
    let meta: Meta            // 중첩은 타입으로 표현하고 합성에 맡긴다
    var authorName: String { meta.author.name }
}

Q4. 디코딩 실패는 어떤 정보를 주는가?

CS 원리

파싱 실패를 다루는 설계의 핵심은 "어디서, 무엇이, 왜"를 잃지 않는 것이다.

일반적인 Error는 실패했다는 사실만 전달한다. 그런데 계층적 데이터의 디코딩에서 정작 필요한 정보는 위치다 — 응답에 필드가 200개인데 "타입이 안 맞음"만 알면 탐색 공간이 전혀 줄지 않는다(P1 20장 Q7의 좁히기 원리).

그래서 DecodingError는 경로를 누적한다. 디코더가 중첩 컨테이너로 내려갈 때마다 codingPath에 키를 쌓고, 실패 시점의 경로가 그대로 에러에 담긴다. 이는 스택 트레이스와 같은 아이디어다 — 실패 지점만이 아니라 거기까지 온 경로를 남긴다.

네 케이스의 구분도 원인별로 대응이 다르기 때문에 존재한다.

keyNotFound와 valueNotFound의 구분이 특히 유용하다 — 전자는 서버가 필드를 안 보냈다는 뜻이고 후자는 보냈는데 null이라는 뜻이다. 원인이 완전히 다르다.

iOS에서는

네 케이스를 사람이 읽는 한 줄로 바꾸는 헬퍼가 네트워크 계층의 표준 관용구다.

import Foundation

extension DecodingError {
    /// 내부 로깅용 한 줄 요약 — 사용자에게 보여주지 않는다
    var diagnostic: String {
        func path(_ ctx: Context) -> String {
            ctx.codingPath.map { key in
                key.intValue.map { "[\($0)]" } ?? ".\(key.stringValue)"
            }.joined().trimmingCharacters(in: CharacterSet(charactersIn: "."))
        }
        switch self {
        case .typeMismatch(let type, let ctx):
            return "타입 불일치 at \(path(ctx)) — \(type) 기대, \(ctx.debugDescription)"
        case .valueNotFound(let type, let ctx):
            return "null 수신 at \(path(ctx)) — \(type) 은 옵셔널이 아님"
        case .keyNotFound(let key, let ctx):
            return "키 없음 at \(path(ctx)).\(key.stringValue)"
        case .dataCorrupted(let ctx):
            return "형식 손상 at \(path(ctx)) — \(ctx.debugDescription)"
        @unknown default:
            return "알 수 없는 디코딩 실패"
        }
    }
}

호출부에서는 이렇게 쓴다.

do {
    let users = try JSONDecoder().decode([User].self, from: data)
} catch let error as DecodingError {
    logger.error("디코딩 실패: \(error.diagnostic, privacy: .public)")
    // 예: 디코딩 실패: 타입 불일치 at users[2].address.zip — Int 기대, Expected to decode Int but found a string
    metrics.increment("decode.failure", tags: ["kind": error.kindLabel])
} catch {
    logger.error("알 수 없는 오류: \(error.localizedDescription, privacy: .public)")
}

지표로 종류별 빈도를 추적하면 서버 스키마 변경을 조기에 감지할 수 있다 — keyNotFound가 특정 릴리스부터 급증하면 계약이 깨진 것이다(P1 18장).

프라이버시 주의가 필요하다. 이 문자열은 프로퍼티명과 서버 필드명을 그대로 노출하고, debugDescription에 값의 일부가 섞일 수 있다. P1 23장 Q1에서 본 대로 사용자에게 보여주는 메시지가 아니라 내부 로깅 채널로만 보낸다.

실험 · 도구

네 케이스를 각각 재현해 보면 어떤 정보가 오는지 분명해진다.

import Foundation

struct Address: Decodable { let zip: Int }
struct User: Decodable { let name: String; let address: Address }

let cases: [(String, String)] = [
    ("typeMismatch",  #"[{"name":"A","address":{"zip":"12345"}}]"#),
    ("valueNotFound", #"[{"name":"A","address":{"zip":null}}]"#),
    ("keyNotFound",   #"[{"name":"A","address":{}}]"#),
    ("dataCorrupted", #"[{"name":"A","address":{"zip":1}},"#),        // JSON 이 깨짐
]

for (label, json) in cases {
    do {
        _ = try JSONDecoder().decode([User].self, from: json.data(using: .utf8)!)
        print("\(label): 성공")
    } catch let e as DecodingError {
        print("\(label): \(e.diagnostic)")
    } catch {
        print("\(label): \(error)")
    }
}
// typeMismatch:  타입 불일치 at [0].address.zip — Int 기대, …
// valueNotFound: null 수신 at [0].address.zip — Int 은 옵셔널이 아님
// keyNotFound:   키 없음 at [0].address.zip
// dataCorrupted: 형식 손상 at  — …

실패한 원본을 남겨 두면 재현이 쉬워진다.

# 디코딩 실패 시 원본 응답을 임시 파일로 남기고 검사한다 (개발 빌드에서만)
python3 -m json.tool < failed-response.json          # 형식 자체가 유효한지
jq '.users[2].address' failed-response.json           # 문제 지점만 뽑아 본다
jq -r '.. | objects | keys[]' failed-response.json | sort -u | head -40   # 전체 키 목록

프로젝트 적용

1. localizedDescription만 로깅하지 않는다. DecodingError로 캐스팅해 codingPath를 반드시 펼친다. 이것 하나가 조사 시간을 몇 시간 단축한다.
2. 진단 문자열은 내부 채널로만 보낸다. 필드명·값이 섞이므로 사용자 메시지로 쓰면 정보 유출이다.
3. 케이스별 빈도를 지표로 추적한다. keyNotFound 급증은 서버 계약 변경의 신호다.
4. 실패한 원본 응답을 개발 빌드에서 저장한다. 프로덕션에서는 PII 때문에 저장하지 않고 경로와 종류만 남긴다.
5. 사용자에게는 복구 가능한 메시지를 보여준다. "데이터를 불러오지 못했습니다 · 다시 시도" 정도로 충분하다.

꼬리 질문

/// 실패한 원소를 건너뛰는 배열 래퍼
struct Lossy<T: Decodable>: Decodable {
    let elements: [T]
    let failures: [String]          // 진단을 버리지 않는다

    init(from decoder: Decoder) throws {
        var container = try decoder.unkeyedContainer()
        var ok: [T] = [], bad: [String] = []
        while !container.isAtEnd {
            do {
                ok.append(try container.decode(T.self))
            } catch let e as DecodingError {
                bad.append(e.diagnostic)
                _ = try? container.decode(AnyCodable.self)   // 커서를 전진시킨다
            }
        }
        elements = ok; failures = bad
    }
}

struct Event: Decodable { let at: Date }

let dec = JSONDecoder()
dec.dateDecodingStrategy = .iso8601

// 소수 초가 섞여 오면 실패한다 (29장 Q5 꼬리질문)
let json = #"{"at":"2026-08-15T14:30:00.123Z"}"#.data(using: .utf8)!
do { _ = try dec.decode(Event.self, from: json) }
catch let e as DecodingError { print(e.diagnostic) }
//   형식 손상 at .at — Expected date string to be ISO8601-formatted.

dec.dateDecodingStrategy = .custom { decoder in
    let s = try decoder.singleValueContainer().decode(String.self)
    let withFrac = ISO8601DateFormatter()
    withFrac.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
    if let d = withFrac.date(from: s) { return d }

    let plain = ISO8601DateFormatter()
    plain.formatOptions = [.withInternetDateTime]
    if let d = plain.date(from: s) { return d }

    throw DecodingError.dataCorruptedError(
        in: try decoder.singleValueContainer(),
        debugDescription: "지원하지 않는 날짜 형식: \(s)")
}

struct APIResponse<T: Decodable>: Decodable {
    let minimumClientVersion: String?     // 서버가 명시적으로 알려준다
    let data: T?
}
//   디코딩 실패를 원인 추측으로 다루지 않고, 계약 안에 버전 협상을 둔다

Q5. 다형 JSON은 왜 어려운가?

CS 원리

이것은 태그된 합집합(tagged union)의 직렬화 문제다. 정적 타입 언어에서 "여러 타입 중 하나"를 표현하려면 어느 것인지 알려주는 태그가 필요한데, 그 태그를 어디에 두느냐가 스키마를 가른다.

세 배치는 표현력이 같지만 호환되지 않는다. 그래서 "Codable이 enum을 지원한다"는 사실만으로는 서버와 통하지 않는다 — 어느 배치인지가 실제 계약이다.

내부 태그 방식이 어려운 이유는 타입 결정과 데이터 읽기가 같은 레벨에서 섞여 있기 때문이다. radius를 읽으려면 먼저 circle임을 알아야 하는데, 그 정보가 같은 객체 안에 있다. 그래서 같은 자리를 두 번 봐야 한다 — 한 번은 태그를 위해, 한 번은 페이로드를 위해.

여기서 설계 선택이 하나 남는다. 모르는 태그를 만났을 때 그 원소만 건너뛸지, 전체를 실패시킬지다. 이는 복원력 대 정확성의 트레이드오프이고, 도메인이 정한다 — 결제·계약 도메인은 엄격 모드가 맞다.

iOS에서는

내부 태그 방식의 표준 구현이다.

import Foundation

struct Circle: Decodable { let radius: Double }
struct Rect: Decodable { let width: Double; let height: Double }

enum Shape: Decodable {
    case circle(Circle)
    case rect(Rect)
    case unknown(String)

    private enum Tag: String, CodingKey { case type }

    init(from decoder: Decoder) throws {
        // ① 태그만 먼저 읽는다
        let tagContainer = try decoder.container(keyedBy: Tag.self)
        let type = try tagContainer.decode(String.self, forKey: .type)

        // ② ③ 같은 decoder 로 구체 타입을 다시 디코딩한다
        switch type {
        case "circle": self = .circle(try Circle(from: decoder))
        case "rect":   self = .rect(try Rect(from: decoder))
        default:       self = .unknown(type)      // 복원력 모드
        }
    }
}

let json = #"[{"type":"circle","radius":5},{"type":"rect","width":2,"height":3}]"#
let shapes = try JSONDecoder().decode([Shape].self, from: json.data(using: .utf8)!)

엄격 모드가 필요하면 default에서 던진다.

default:
    throw DecodingError.dataCorruptedError(
        forKey: .type, in: tagContainer,
        debugDescription: "지원하지 않는 shape 타입: \(type)")
//   codingPath 가 남으므로 어느 원소인지 특정된다 (Q4)

SE-0295 합성이 왜 답이 아닌지도 코드로 보면 분명하다.

enum AutoShape: Codable {
    case circle(radius: Double)
    case rect(width: Double, height: Double)
}

let s = AutoShape.circle(radius: 5)
String(data: try JSONEncoder().encode(s), encoding: .utf8)!
//   {"circle":{"radius":5}}
//   서버가 기대하는 {"type":"circle","radius":5} 와 다르다.
//   합성은 편리하지만 스키마를 우리가 고를 수 없다.

인코딩도 대칭으로 직접 써야 한다.

extension Shape: Encodable {
    func encode(to encoder: Encoder) throws {
        var c = encoder.container(keyedBy: Tag.self)
        switch self {
        case .circle(let v):
            try c.encode("circle", forKey: .type)
            try v.encode(to: encoder)          // 같은 레벨에 페이로드를 편다
        case .rect(let v):
            try c.encode("rect", forKey: .type)
            try v.encode(to: encoder)
        case .unknown(let t):
            try c.encode(t, forKey: .type)
        }
    }
}

실험 · 도구

두 스키마가 서로 못 읽는다는 것을 직접 확인해 보자.

import Foundation

// 합성이 만드는 외부 태그 JSON
let auto = try JSONEncoder().encode(AutoShape.circle(radius: 5))
print(String(data: auto, encoding: .utf8)!)      // {"circle":{"radius":5}}

// 내부 태그를 기대하는 디코더에 넣으면 실패한다
do { _ = try JSONDecoder().decode(Shape.self, from: auto) }
catch let e as DecodingError { print(e.diagnostic) }
//   키 없음 at .type      ← 태그 배치가 다르다

// 반대도 마찬가지다
let manual = #"{"type":"circle","radius":5}"#.data(using: .utf8)!
do { _ = try JSONDecoder().decode(AutoShape.self, from: manual) }
catch let e as DecodingError { print(e.diagnostic) }

서버가 어떤 배치를 쓰는지 빠르게 확인하는 방법이다.

# 응답에서 판별자 후보 필드를 찾는다
jq -r '.. | objects | keys[]' response.json | sort | uniq -c | sort -rn | head -20
#   type · kind · __typename 같은 이름이 상위에 보이면 내부 태그 방식이다

# 태그 값의 종류를 모아 본다 — unknown 처리 대상 파악
jq -r '.. | objects | select(has("type")) | .type' response.json | sort -u

프로젝트 적용

1. 서버의 태그 배치를 먼저 확인하고 계약에 명시한다. "enum을 쓰면 된다"가 아니라 어느 배치인지가 계약이다.
2. 모르는 태그 처리 방침을 도메인별로 정한다. 피드는 unknown 케이스로 살리고, 결제는 실패시킨다.
3. unknown을 만나면 지표로 올린다. 서버가 새 타입을 추가했다는 신호이고, 얼마나 많은 사용자가 못 보고 있는지 알 수 있다.
4. 인코딩도 대칭으로 구현하고 왕복 테스트를 붙인다. 디코딩만 구현하면 보내는 쪽에서 어긋난다.
5. 합성을 쓸 거면 서버가 그 형태에 맞춰야 한다. 앱이 데이터 형식을 정하는 관계(로컬 저장 등)에서는 합성이 편하다.

꼬리 질문

enum Shape: Decodable {
    case circle(Circle)
    case rect(Rect)
    case unknown(type: String)      // ✅ 처음부터 있어야 나중에 안 깨진다
}

struct Page<T: Decodable>: Decodable {
    let items: [T]
    let nextCursor: String?
}

// Shape 이 Decodable 이므로 그대로 쓸 수 있다
let page = try JSONDecoder().decode(Page<Shape>.self, from: data)

struct Bad<T>: Decodable { let value: T }        // ❌ T 에 제약이 없어 합성 불가
struct Good<T: Decodable>: Decodable { let value: T }   // ✅

enum APIResult<T: Decodable>: Decodable {
    case success(T)
    case failure(APIError)

    private enum K: String, CodingKey { case status, data, error }

    init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: K.self)
        switch try c.decode(String.self, forKey: .status) {
        case "ok":  self = .success(try c.decode(T.self, forKey: .data))
        default:    self = .failure(try c.decode(APIError.self, forKey: .error))
        }
    }
}

Q6. 키 변환 전략과 디코더 재사용에 대한 통념은 맞는가?

CS 원리

키 변환 전략의 문제는 비가역 사상(non-invertible mapping)이다.

camelCase → snake_case 변환은 정보를 잃는다. imageURL과 imageUrl이 둘 다 image_url로 가므로, 역방향에서 어느 것이 원본인지 알 수 없다. 역변환 규칙은 하나만 고를 수 있고, 그것이 imageUrl이다.

여기서 연쇄 실패가 생긴다.

• 인코딩: imageURL → image_url
• 디코딩: image_url → imageUrl
• 모델의 프로퍼티는 imageURL → 키가 안 맞아 keyNotFound

그리고 적용 순서가 중요하다. 전략은 컨테이너를 만들 때 키 전체를 변환하므로, CodingKeys에 무엇을 적든 이미 변환된 키와 비교된다. 그래서 전략과 명시적 키를 섞으면 안 된다 — 전부 전략에 맡기거나, 전부 명시하거나 둘 중 하나다.

두 번째 통념 — 인스턴스 생성 비용은 타입마다 다르다. 29장 Q5에서 DateFormatter는 로케일·달력 데이터를 로드하고 심볼 테이블을 구성하느라 18배 차이가 났다. JSONDecoder는 그런 무거운 초기화가 없어 생성 자체가 가볍고, 진짜 비용은 파싱에 있다. "객체 재사용은 항상 이득"이라는 일반화가 여기서 깨진다.

iOS에서는

전략과 명시적 키를 섞었을 때 무슨 일이 생기는지 보자.

struct Photo: Decodable {
    let imageURL: URL
    enum CodingKeys: String, CodingKey {
        case imageURL = "image_url"       // 원본 키를 그대로 적었다
    }
}

let dec = JSONDecoder()
dec.keyDecodingStrategy = .convertFromSnakeCase     // 전략도 켰다

let json = #"{"image_url":"https://x.com/a.jpg"}"#.data(using: .utf8)!
try dec.decode(Photo.self, from: json)
//   ❌ keyNotFound — 전략이 "image_url" 을 "imageUrl" 로 먼저 바꿨고,
//      CodingKeys 의 "image_url" 과 비교되지 않는다.

해결은 한쪽만 쓰는 것이다.

// ✅ 방법 A — 전략만 쓴다. CodingKeys 를 정의하지 않는다.
struct PhotoA: Decodable { let imageUrl: URL }      // 프로퍼티명을 변환 결과에 맞춘다
// dec.keyDecodingStrategy = .convertFromSnakeCase

// ✅ 방법 B — 전략을 끄고 전부 명시한다. 이름을 우리가 통제한다.
struct PhotoB: Decodable {
    let imageURL: URL
    enum CodingKeys: String, CodingKey { case imageURL = "image_url" }
}
// dec.keyDecodingStrategy = .useDefaultKeys       (기본값)

방법 B를 권한다 — 약어(URL·ID·HTML)가 섞이면 전략의 왕복이 깨지고, 서버가 snake_case가 아닌 키를 하나라도 쓰면 전략만으로는 감당이 안 된다.

디코더 재사용은 성능이 아니라 설정 일관성 때문에 한다.

// 재사용의 진짜 이유 — 날짜 전략·키 전략을 한 곳에서 관리한다
enum API {
    static let decoder: JSONDecoder = {
        let d = JSONDecoder()
        d.dateDecodingStrategy = .iso8601
        d.keyDecodingStrategy = .useDefaultKeys
        return d
    }()
}
//   성능 때문이 아니라 "설정이 어긋나지 않게" 하려는 것이다.
//   JSONDecoder 는 값 타입이 아니지만 설정 후 변경하지 않으면 동시 사용에 문제가 없다.

참고로 swift-foundation 재작성으로 디코딩 성능이 크게 개선됐다. swift.org의 검증 가능한 개선치는 구형(corelibs-foundation) 대비 200~500%이며, 원인은 리플렉션이 아니라 JSONSerialization이 만드는 Objective-C 객체 그래프와의 브리징(swift_dynamicCast) 제거다.

실험 · 도구

왕복이 깨지는 것을 직접 확인해 보자.

import Foundation

struct Round: Codable { let imageURL: String }

let enc = JSONEncoder(); enc.keyEncodingStrategy = .convertToSnakeCase
let dec = JSONDecoder(); dec.keyDecodingStrategy = .convertFromSnakeCase

let data = try enc.encode(Round(imageURL: "a.jpg"))
print(String(data: data, encoding: .utf8)!)      // {"image_url":"a.jpg"}

do { _ = try dec.decode(Round.self, from: data) }
catch let e as DecodingError { print(e.diagnostic) }
//   키 없음 at .imageUrl    ← 역변환이 imageUrl 을 기대하는데 프로퍼티는 imageURL 이다

디코더 생성 비용도 직접 재 볼 수 있다.

let big = try Data(contentsOf: url)      // 약 4.6MB, 5만 건
let clock = ContinuousClock()

let shared = JSONDecoder()
let reused = clock.measure { _ = try? shared.decode([Record].self, from: big) }
let fresh  = clock.measure { _ = try? JSONDecoder().decode([Record].self, from: big) }

print("재사용: \(reused)")     // 약 86ms
print("매번 생성: \(fresh)")   // 약 86ms — 차이가 거의 없다
//   DateFormatter 와 달리 생성 비용이 파싱 비용에 묻힌다

기존 코드에서 위험한 조합을 찾는다.

# 전략과 CodingKeys 를 함께 쓰는 파일 — 충돌 후보
grep -rl "convertFromSnakeCase" --include=*.swift . | while read f; do
  grep -l "enum CodingKeys" "$f"
done

# 약어가 섞인 프로퍼티명 — 전략 왕복이 깨지는 후보
grep -rnE "let [a-z]+[A-Z]{2,}" --include=*.swift . | head -20

프로젝트 적용

1. 키 변환 전략과 CodingKeys를 섞지 않는다. 프로젝트 차원에서 한쪽으로 통일한다.
2. 약어가 있는 이름이 하나라도 있으면 전략을 쓰지 않는다. URL·ID·HTML이 흔하다.
3. 디코더는 성능이 아니라 설정 일관성 때문에 공유한다. "재사용하면 빨라진다"는 근거로 쓰지 않는다.
4. 재사용 조언을 타입별로 검증한다. DateFormatter는 맞고 JSONDecoder는 무의미하다 — 측정이 답한다.
5. 왕복 테스트에 약어 필드를 포함한다. 전략의 비가역성은 왕복 테스트로만 드러난다.

꼬리 질문

// 서버가 섞어 보내는 경우 — 전략으로는 감당이 안 된다
// {"user_id":1,"displayName":"김","image_url":"..."}

struct Mixed: Decodable {
    let userId: Int
    let displayName: String
    let imageURL: URL

    enum CodingKeys: String, CodingKey {
        case userId = "user_id"
        case displayName                     // 그대로 일치
        case imageURL = "image_url"
    }
}
// decoder.keyDecodingStrategy = .useDefaultKeys   ← 기본값 유지

let items = try await Task.detached(priority: .userInitiated) {
    try JSONDecoder().decode([Record].self, from: data)
}.value

let clock = ContinuousClock()

// 생성만
let createOnly = clock.measure { for _ in 0..<10_000 { _ = JSONDecoder() } }
// 생성 + 사용
let createAndUse = clock.measure {
    for _ in 0..<10_000 { _ = try? JSONDecoder().decode(Small.self, from: tiny) }
}
print("생성만: \(createOnly)")          // 생성 비용이 여기 드러난다
print("생성+사용: \(createAndUse)")     // 사용 비용에 묻히는지 본다

Q7. JSON 스키마를 어떻게 진화시키는가?

CS 원리

스키마 진화는 호환성의 두 방향으로 정리된다.

모바일에서 상위 호환이 특히 중요하다. 서버는 계속 배포되지만 앱은 사용자가 업데이트해야 하고, 일부는 영원히 하지 않는다. 그래서 서버의 변경이 구버전 앱을 깨뜨리지 않아야 한다.

여기서 안전한 변경과 위험한 변경이 갈린다.

• 안전 — 옵셔널 필드 추가, 열거형에 새 케이스 추가(unknown 대비가 있다면), 응답에 필드 추가.
• 위험 — 필드 제거, 타입 변경(Int → String), 의미 변경(같은 이름인데 뜻이 달라짐), 옵셔널을 필수로 승격.

가장 위험한 것이 의미 변경이다 — 타입도 이름도 그대로라 어떤 도구도 잡지 못하고, 구버전 앱은 조용히 잘못된 동작을 한다. 예컨대 amount가 원 단위에서 전 단위로 바뀌면 구버전은 100배 틀린 금액을 보여준다.

대응 원리는 "바꾸지 말고 더한다"이다. 새 의미가 필요하면 새 이름을 쓰고, 두 필드를 당분간 함께 채운다. 이는 데이터베이스의 확장-축소(expand-contract) 마이그레이션과 같은 패턴이다.

iOS에서는

클라이언트 쪽 대비는 모르는 것에 관대하고, 아는 것에 엄격한 구조를 만드는 것이다.

struct Product: Decodable {
    let id: String
    let name: String

    // 신규 필드 — 구버전 서버는 안 보낼 수 있으므로 옵셔널
    let amountWon: Int?
    // 구 필드 — 언젠가 사라질 수 있으므로 옵셔널
    private let amount: Int?

    /// 신규를 우선하고 없으면 구 필드로 폴백한다
    var priceWon: Int { amountWon ?? amount ?? 0 }

    enum CodingKeys: String, CodingKey { case id, name, amountWon, amount }
}

열거형은 unknown 케이스를 처음부터 둔다(Q5).

enum Status: String, Decodable {
    case pending, shipped, delivered
    case unknown

    init(from decoder: Decoder) throws {
        let raw = try decoder.singleValueContainer().decode(String.self)
        self = Status(rawValue: raw) ?? .unknown
        if self == .unknown { logger.notice("알 수 없는 status: \(raw, privacy: .public)") }
    }
}

버전 협상을 계약 안에 두면 추측이 필요 없어진다.

struct Envelope<T: Decodable>: Decodable {
    let schemaVersion: Int
    let minimumClientVersion: String?    // 서버가 명시적으로 알려준다
    let payload: T
}
//   디코딩 실패를 "앱이 낡아서"라고 추측하는 대신 서버가 말해 준다 (Q4 꼬리질문)

실험 · 도구

구버전 모델로 신버전 응답을 디코딩해 보는 것이 상위 호환 테스트다.

import Testing

@Test func 구버전_모델이_신버전_응답을_읽는다() throws {
    // 실제 서버가 앞으로 보낼 응답 (새 필드 포함)
    let future = #"""
    {"id":"1","name":"A","amount":1000,"amountWon":1000,"newField":"x"}
    """#.data(using: .utf8)!

    // 구버전 모델로 디코딩 — 깨지면 안 된다
    let old = try JSONDecoder().decode(ProductV1.self, from: future)
    #expect(old.amount == 1000)
}

@Test func 신버전_모델이_구버전_응답을_읽는다() throws {
    let past = #"{"id":"1","name":"A","amount":1000}"#.data(using: .utf8)!
    let new = try JSONDecoder().decode(Product.self, from: past)
    #expect(new.priceWon == 1000)      // 폴백이 동작한다
}

CI에 계약 픽스처를 두면 서버 변경이 앱을 깨뜨리는지 미리 알 수 있다.

# 서버 팀이 관리하는 응답 예시를 앱 저장소에 동기화한다
Fixtures/
  product_v1.json      # 구버전 — 여전히 읽혀야 한다
  product_v2.json      # 현재
  product_v3_draft.json # 예정된 변경 — 미리 검증한다

# 모든 픽스처를 현재 모델로 디코딩해 본다
swift test --filter ContractTests

프로젝트 적용

1. "추가는 자유, 제거·변경은 금지"를 계약 규칙으로 문서화한다. 서버 팀과 공유해야 의미가 있다.
2. 의미를 바꿔야 하면 새 이름을 쓴다. 같은 필드의 뜻을 바꾸는 것은 어떤 도구도 잡지 못한다.
3. 확장-축소 3단계를 지킨다. 축소 시점은 구버전 사용률 지표로 판단한다(P1 21장 Q5의 릴리스 태깅이 여기서 쓰인다).
4. 열거형에 unknown을 처음부터 둔다. 나중에 추가하면 이미 배포된 버전은 못 고친다.
5. 구버전 모델로 신버전 응답을 읽는 테스트를 CI에 둔다. 상위 호환은 테스트하지 않으면 반드시 깨진다.

꼬리 질문

# 서버 CI 에서 클라이언트 픽스처를 검증한다
curl -s localhost:8080/api/products/1 > /tmp/actual.json
python3 - <<'PY'
import json
expected_keys = set(json.load(open("client-fixtures/product_v2.json")).keys())
actual_keys   = set(json.load(open("/tmp/actual.json")).keys())
missing = expected_keys - actual_keys
if missing:
    raise SystemExit(f"❌ 클라이언트가 기대하는 키가 사라졌다: {missing}")
print("✅ 계약 유지")
PY

struct StoredEnvelope<T: Codable>: Codable {
    let schemaVersion: Int
    let payload: T
}

func load(_ data: Data) throws -> Settings {
    let head = try JSONDecoder().decode(VersionHead.self, from: data)
    switch head.schemaVersion {
    case 1:  return try migrateV1toV2(JSONDecoder().decode(SettingsV1.self, from: data))
    case 2:  return try JSONDecoder().decode(Settings.self, from: data)
    default: throw StoreError.unsupportedVersion(head.schemaVersion)
    }
}

출처 · 참고자료