[SwiftData] 02. Model your schema with SwiftData(SwiftData로 스키마 모델링하기)

SwiftData로 스키마 모델링하기 WWDC 영상 번역/정리본입니다.

•  목차
  • 00:00 Intro
  • 01:41 Utilizing schema macros | 스키마 매크로를 최대한 활용하는 법(@Attribute, @Relationship, @Transient)
  • 05:30 Evolving schemas | 앱이 변경될 때 스키마 마이그레이션으로 스키마를 개선하는 법
  • 08:56 Wrap-up
• doc
  • SwiftData 공식 문서
  • Adopting SwiftData for a core Data app 샘플 프로젝트
• 선 시청
  • SwiftData 알아보기
  • SwiftData로 앱 빌드하기

 

0. Intro

SwiftData는 데이터 모델링 및 관리를 위한 프레임워크입니다.

SwiftUI처럼 외부 파일 형식 없이 오로지 코드에만 집중할 수 있으며, Swift의 새로운 매크로 시스템으로 원활한 API 경험을 제공합니다.

 

SampleTrips 앱을 예시로 살펴볼까요? SampleTrips 앱에서는 사용자가 여행을 계획할 수 있습니다.
각 여행은 이름과 목적지 시작 및 종료 날짜와 함께 생성됩니다. 또한 버킷 리스트 항목과 숙소에 대한 관계도 포함할 수 있습니다.

import SwiftUI

final class Trip {
    var name: String
    var destination: String
    var start_date: Date
    var end_date: Date
    
    var bucketList: [BucketListItem]? = []
    var livingAccommodation: LivingAccommodation?
}

 

 

이 Trip 클래스에 SwiftData를 추가하는 것은 간단합니다.
👉🏻 SwiftData를 import하고, @Model 매크로를 class에 추가하면 됩니다.

import SwiftUI
import SwiftData

@Model
final class Trip {
    var name: String
    var destination: String
    var start_date: Date
    var end_date: Date
    
    var bucketList: [BucketListItem]? = []
    var livingAccommodation: LivingAccommodation?
}

 

@Model 매크로는 Trip 클래스를 PersistentModel과 일치시키고, descriptive 스키마를 생성합니다. 이제 모델을 정의하는 코드가 앱 스키마의 진실 공급원이 되었습니다.

 

1. Utilizing schema macros

SwiftData 스키마 매크로를 통해 지속적인 경험의 행동이 앱에서 완벽히 작동하도록 맞춤화할 수 있습니다.

기존 스키마에서는 각 여행에 고유한 이름을 보장하지 않았습니다. 따라서 이름이 같은 여행끼리 충돌할 수 있습니다. 이는 @Attribute 스키마 매크로로 unique 옵션을 사용해 해결할 수 있습니다.

@Model
final class Trip {
    @Attribute(.unique) var name: String // << 여기
    var destination: String
    var start_date: Date
    var end_date: Date
    
    var bucketList: [BucketListItem]? = []
    var livingAccommodation: LivingAccommodation?
}

 

이제, SwiftData가 생성하는 여행 모델의 스키마가 영구 백엔드에 저장되는 모든 여행에 고유한 이름을 보장합니다.

만약 해당 이름의 여행이 이미 존재하는 경우 영구 백엔드에서 최근 값으로 업데이트합니다. 이를 upsert(업서트)라고 합니다. 업서트는 인서트로 시작합니다. 기존 데이터와 충돌한 인서트가 업데이트로 변해 기존 데이터의 프로퍼티를 업데이트하게 됩니다.

 

Unique constraints

다른 프로퍼티에도 고유한 제약을 적용할 수 있습니다. 숫자나 문자열, UUID와 같은 기본값 유형이라면 가능합니다. 

스키마를 좀 더 수정해 볼까요? 이전에 지정한 start_date와 end_date에서 성가신 밑줄을 없애고 싶습니다. 근데 변수 이름을 바꾸면 생성된 스키마의 새 프로퍼티로 간주될 겁니다. SwiftData가 새 프로퍼티를 생성하는 건 원하지 않고 기존 데이터를 그대로 유지하고 싶습니다.

 

👉🏻 이를 위해서는 기존 이름을 프로퍼티 이름으로 매핑하면 됩니다!
@Attribute를 사용하고, originalName: 매개변수를 지정해서요.
기존 이름을 매핑하면 데이터 손실을 예방할 수 있고, 스키마 업데이트가 SampleTrips 앱의 다음 출시에 간단한 마이그레이션을 보장하게 됩니다.

@Attribute(originalName: "start_date") var startDate: Date
@Attribute(originalName: "end_date") var endDate: Date

 

 

 

이외에도 @Attribute 매크로는 다양한 작업을 수행할 수 있습니다.

대용량 데이터를 외부에 저장하고 변형 가능성을 지원합니다.

• External data
• Transformable
• Spotlight integration
• Hash modifier

 

Relationships

이제 Relationships를 살펴볼까요?

새 버킷 리스트 항목이나 숙소를 여행에 추가하면 SwiftData가 암시적으로 모델 간의 역관계를 발견하고 대신 설정해줍니다. 암시적 역관계에는 annotation이 전혀 필요 없습니다.

암시적 역관계는 기본 삭제 규칙을 사용하여 여행이 삭제될 때 버킷 리스트 항목과 숙소 프로퍼티를 null로 만듭니다. 하지만 버킷 리스트 항목과 숙소가 여행과 함께 삭제되길 원합니다.

👉🏻  @Relationship 매크로와 cascade 삭제 규칙으로 이를 쉽게 수행할 수 있습니다.

@Model 
final class Trip {
    @Attribute(.unique) var name: String
    var destination: String
    @Attribute(originalName: "start_date") var startDate: Date
    @Attribute(originalName: "end_date") var endDate: Date
    
    @Relationship(.cascade)
    var bucketList: [BucketListItem]? = []
  
    @Relationship(.cascade)
    var livingAccommodation: LivingAccommodation?
}

 

이제 여행을 지우면 해당 관계들도 함께 삭제됩니다.

 

 

@Relationship 매크로의 기능

originalName 모디파이어 뿐만 아니라 to-many 관계에서 최소 및 최대 개수를 지정할 수도 있습니다.

• Tailor your @Relationship metadata
  • originalName
  • Specify toMany count constraints
  • Hash modifier

 

이제, 여행을 몇 번 조회하는지 추적하는 방법을 추가하고 싶습니다. 하지만 SwiftData가 조회 수를 계속 세기를 바라지는 않습니다.

👉🏻 @Transient 매크로를 사용하면 됩니다. @Transient로 프로퍼티를 decorate하면 해당 프로퍼티는 지속되지 않습니다.

@Transient
var tripViews: Int = 0

 

@Transient 매크로를 사용해서 불필요한 데이터를 지속하지 않게 할 수 있습니다. 그리고 transient 프로퍼티에 기본값을 반드시 지정해야 SwiftData에서 가져올 때 논리적인 값이 할당됩니다. 스키마 매크로 활용에 대한 자세한 정보는 SwiftData 문서를 참조하세요 !

• Hide properties from SwifData with @Transient
• Specify which properties do not persist
• Provide a default value

 

2. Evolving schemas

SampleTrips 앱을 출시할 때마다 앱이 업데이트를 처리할 수 있게 해야 합니다. 프로퍼티 추가 및 제거 등의 스키마 변경이 있을 때는 데이터 마이그레이션이 발생합니다. 마이그레이션은 복잡할 수 있지만 SwiftData를 쓰면 간단히 해결할 수 있습니다.

• Encapsulate your models at a specific version with VersionedSchema
• Order your versions with SchemaMigrationPlan
• Define each migration stage
  • Lightweight
  • Custom

VersionedSchema와 SchemaMigrationPlan이 도와줍니다. SwiftData 모델이 변경된 앱의 새 버전을 출시할 때마다 VersionedSchema를 정의하세요. 이는 이전에 출시된 스키마를 캡슐화합니다. 각각의 스키마 버전이 VersionedSchema로 정의되어야 버전 사이에 어떤 변화가 있었는지 SwiftData가 알 수 있습니다. 그런 다음 VersionedSchema의 total ordering을 사용해 SchemaMigrationPlan을 생성하면 SwiftData가 필요한 마이그레이션을 순서대로 수행합니다. 마이그레이션 계획에 스키마를 정렬했으면 마이그레이션 스테이지를 정의할 수 있는습니다.

 

두 가지 유형의 마이그레이션 스테이지가 제공됩니다.

하나는 경량 마이그레이션입니다. 경량 마이그레이션은 다음에 앱을 출시하면서 기존 데이터를 마이그레이션할 때 추가 코드가 필요하지 않습니다. 날짜 프로퍼티에 originalName을 추가하거나 관계에서 삭제 규칙을 지정하는 등의 변경은 경량 마이그레이션에 적합합니다.

하지만 여행 이름을 고유하게 짓는 건 경량 마이그레이션에 적합하지 않습니다. 이때는 사용자 지정 마이그레이션 스테이지가 필요합니다. 그래야 고유한 이름을 짓기 전에 중복된 여행을 제거할 수 있습니다.

 

우선 첫 번째 출시된 기존 스키마를 가져와서 VersionedSchema에 캡슐화합니다. 이를 SampleTripsSchemaV1로 지정했습니다. 각 VersionedSchema는 정의된 모델 클래스를 나열합니다.

enum SampleTripsSchemaV1: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        [Trip.self, BucketListItem.self, LivingAccommodation.self]
    }

    @Model
    final class Trip {
        var name: String
        var destination: String
        var start_date: Date
        var end_date: Date
    
        var bucketList: [BucketListItem]? = []
        var livingAccommodation: LivingAccommodation?
    }

    // Define the other models in this version...
}

 

 

두 번째 버전 스키마에는 여행 이름에 고유성 제약을 추가했습니다. VersionedSchema를 하나 더 생성해서 Trip 모델 클래스에 적용한 변경 사항을 캡슐화합니다.

enum SampleTripsSchemaV2: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        [Trip.self, BucketListItem.self, LivingAccommodation.self]
    }

    @Model
    final class Trip {
        @Attribute(.unique) var name: String // << 변경
        var destination: String
        var start_date: Date
        var end_date: Date
    
        var bucketList: [BucketListItem]? = []
        var livingAccommodation: LivingAccommodation?
    }

    // Define the other models in this version...
}

 

 

세 번째 버전 스키마에도 똑같이 해서 시작 및 종료 날짜에 적용된 이름 변경을 캡처합니다.

enum SampleTripsSchemaV3: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        [Trip.self, BucketListItem.self, LivingAccommodation.self]
    }

    @Model
    final class Trip {
        @Attribute(.unique) var name: String
        var destination: String
        @Attribute(originalName: "start_date") var startDate: Date // << 변경
        @Attribute(originalName: "end_date") var endDate: Date     // << 변경
    
        var bucketList: [BucketListItem]? = []
        var livingAccommodation: LivingAccommodation?
    }

    // Define the other models in this version...
}

 

 

이제 VersionedSchema가 모두 준비됐으니 SchemaMigrationPlan을 구성해서 출시된 버전간 마이그레이션을 처리하는 법을 알아봅시다.

1. 앱 스키마의 total ordering을 제공합니다.
2. 각 마이그레이션이 경량인지 사용자 정의인지 annotation을 달아야 합니다.
   1) V1에서 V2로의 마이그레이션은 사용자 지정 스테이지가 필요해서 데이터가 마이그레이션되기 전에 작업을 수행해야 합니다.
   2) willMigrate 클로저에서 마이그레이션이 진행되기 전에 중복되는 여행을 삭제할 수 있습니다. V1에서 V2로의 마이그레이션이 발생하는 시점을 SwiftData가 감지해 이 클로저를 실행합니다.
   3) V2에서 V3로의 마이그레이션인, originalName의 마이그레이션은 경량이므로 해당 스테이지도 추가해야 합니다. 
   

   enum SampleTripsMigrationPlan: SchemaMigrationPlan {
       static var schemas: [any VersionedSchema.Type] {
           [SampleTripsSchemaV1.self, SampleTripsSchemaV2.self, SampleTripsSchemaV3.self]
       }
       
       static var stages: [MigrationStage] {
           [migrateV1toV2, migrateV2toV3]
       }
   
       static let migrateV1toV2 = MigrationStage.custom(
           fromVersion: SampleTripsSchemaV1.self,
           toVersion: SampleTripsSchemaV2.self,
           willMigrate: { context in
               let trips = try? context.fetch(FetchDescriptor<SampleTripsSchemaV1.Trip>())
                         
               // De-duplicate Trip instances here...
                         
               try? context.save() 
           }, didMigrate: nil
       )
       
       static let migrateV2toV3 = MigrationStage.lightweight(
           fromVersion: SampleTripsSchemaV2.self,
           toVersion: SampleTripsSchemaV3.self
       )
   }
   

3. 마이그레이션 계획의 세부 사항까지 모두 정의했으니 마이그레이션을 실행할 수 있습니다. 현재 스키마와 마이그레이션 계획이 포함된 ModelContainer를 설정하면 끝입니다. 어떤 버전에서든 최신 릴리즈로 업그레이드할 수 있고 데이터도 확실히 보존될 것입니다.

struct TripsApp: App {
    let container = ModelContainer(
        for: Trip.self, 
        migrationPlan: SampleTripsMigrationPlan.self
    )
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(container)
    }
}

 

3. Wrap-up

스키마 매크로를 활용해 스키마의 추가 메타데이터를 전달하세요.

앱이 개선될 때마다 VersionedSchema로 개선점을 캡처해 이전 버전에서도 앱을 마이그레이션할 수 있습니다.

• Convey metadata with schema macros
• Version schemas as your app evolves