지난 글에서 서버 응답을 User.fromJson으로 모델 클래스로 바꿨다. 필드가 두세 개일 때는 괜찮은데, 서버가 주는 항목이 열 개, 스무 개가 되면 json['...'] as String을 손으로 쓰는 일이 점점 고통스럽다. 게다가 오타를 내도 컴파일러가 모른다. 서버가 created_at이라는 이름으로 날짜를 주는 경우를 직접 써보자.

class User {
  final int id;
  final String name;
  final DateTime createdAt;

  User({required this.id, required this.name, required this.createdAt});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'] as int,
      name: json['name'] as String,
      createdAt: DateTime.parse(json['createdAt'] as String), // 서버는 created_at으로 줌
    );
  }
}

컴파일은 통과한다. 그런데 실행하면 이 줄에서 죽는다.

type 'Null' is not a subtype of type 'String' in type cast

JSON에는 createdAt이라는 키가 없고 created_at만 있어서 json['createdAt']이 null이고, 그걸 String으로 단언(as String)하다가 터진다. 모델을 쓰면 오타를 컴파일러가 잡아준다고 했는데, JSON 키를 문자열로 적는 이 자리만큼은 여전히 오타가 실행 중에야 드러난다.

원인: 변환 코드를 사람이 직접 쓰고 있다

json['키']의 키는 그냥 문자열이라 컴파일러가 검사할 수 없다. 필드가 늘수록 이런 줄이 늘어나고, 서버 필드 이름이 바뀌면 일일이 찾아 고쳐야 한다. 이 반복 작업을 코드 생성기가 대신 써주게 하는 게 json_serializable이다.

해결 1: json_serializable로 변환 코드를 생성한다

설치부터 한다. 앱에 들어가는 건 json_annotation이고, 코드를 만드는 도구 두 개는 개발 때만 쓰는 dev 의존성이다.

flutter pub add json_annotation
flutter pub add dev:json_serializable
flutter pub add dev:build_runner

클래스에 어노테이션을 붙인다.

import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart'; // 생성될 파일을 이 파일의 일부로 선언

@JsonSerializable(fieldRename: FieldRename.snake)
class User {
  final int id;
  final String name;
  final DateTime createdAt; // JSON의 created_at과 연결됨

  User({required this.id, required this.name, required this.createdAt});

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

• @JsonSerializable(): "이 클래스의 변환 코드를 만들어달라"는 표시다
• fieldRename: FieldRename.snake: 필드 이름 createdAt을 JSON에서는 created_at으로 대응시킨다. 필드 하나만 바꾸려면 그 필드에 @JsonKey(name: 'created_at')을 붙인다
• part 'user.g.dart': 생성될 파일을 이 파일에 이어 붙인다는 선언이다
• _$UserFromJson, _$UserToJson: 생성기가 만들어줄 함수다. 지금은 아직 없다

이제 생성기를 돌린다.

dart run build_runner build --delete-conflicting-outputs

user.g.dart 파일이 생기고 _$UserFromJson이 채워진다. 이후로는 User.fromJson(response.data)가 JSON 키를 알아서 맞춰 변환한다. 필드가 늘어도 어노테이션이 붙은 클래스에 필드만 추가하고 다시 생성하면 된다.

삽질 포인트: 생성기를 안 돌렸더니 빨간 줄

The function '_$UserFromJson' isn't defined.

생성하기 전이거나, part 'user.g.dart'; 줄을 빼먹었거나, 필드를 고쳐놓고 생성기를 다시 안 돌렸을 때 나오는 에러다. 생성된 파일은 원본과 별개라서 어노테이션 클래스를 고치면 다시 생성해야 한다. 고칠 때마다 명령을 치기 번거로우면 감시 모드를 켜둔다.

dart run build_runner watch -d

파일이 바뀔 때마다 자동으로 다시 생성한다.

다음 문제: 모델이 같은지 비교하면 false가 나온다

json_serializable이 fromJson, toJson은 만들어주지만, 모델에는 아직 불편한 점이 남아 있다.

final now = DateTime.now();
final a = User(id: 1, name: '홍길동', createdAt: now);
final b = User(id: 1, name: '홍길동', createdAt: now);

print(a == b); // false

내용이 똑같은데 false다. 평범한 클래스의 ==는 같은 객체인지(주소가 같은지)만 비교하기 때문이다. 이게 문제가 되는 곳이 많다. Cubit에서 새 상태가 이전 상태와 같으면 무시된다고 했는데, 이 비교가 ==다. 내용이 같은 상태를 매번 새 상태로 취급해서 화면이 불필요하게 다시 그려지거나, 반대로 Riverpod에서 같은 값으로 갱신해도 알림이 간다.

==를 제대로 쓰려면 operator ==와 hashCode를 직접 만들어야 하고, 값을 일부만 바꾼 복사본을 만드는 copyWith, 디버깅용 toString도 필요하다. 필드가 늘 때마다 이걸 전부 고쳐야 한다. 이 보일러플레이트까지 생성해주는 게 freezed다.

해결 2: freezed로 ==, copyWith, toString까지 한 번에

flutter pub add freezed_annotation
flutter pub add dev:freezed

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
abstract class User with _$User {
  const factory User({
    required int id,
    required String name,
    @JsonKey(name: 'created_at') required DateTime createdAt,
  }) = _User;

  factory User.fromJson(Map<String, Object?> json) => _$UserFromJson(json);
}

필드를 factory 생성자의 파라미터로 한 번만 적는다. 필드 선언, 생성자, fromJson용 코드가 모두 한 곳에 모인다. 생성자 글에서 본 factory가 여기서 핵심으로 쓰인다.

• abstract class User with _$User: 상속 글에서 본 with(mixin)다. 생성된 _$User를 섞어서 ==, copyWith, toString을 얻는다
• = _User: 생성기가 만들어줄 실제 구현 클래스에 연결한다
• part 파일이 두 개다. user.freezed.dart는 freezed가, user.g.dart는 fromJson용 json_serializable이 만든다

같은 명령으로 생성하면 이제 이런 일이 된다.

final a = User(id: 1, name: '홍길동', createdAt: now);
final b = User(id: 1, name: '홍길동', createdAt: now);

print(a == b);               // true, 내용이 같으면 같은 값
print(a.copyWith(name: '김철수')); // 일부만 바꾼 새 객체를 만들어줌
print(a);                    // User(id: 1, name: 홍길동, createdAt: ...)

copyWith는 원본을 고치지 않고 바꾼 부분만 다른 새 객체를 돌려준다. Cubit에서 상태를 직접 고치지 않고 새로 만들어 emit하는 규칙과 잘 맞는다.

emit(state.copyWith(name: '김철수'));

삽질 포인트: 예전 튜토리얼 코드가 안 된다

freezed는 3.0부터 규칙이 바뀌어서, 클래스를 abstract나 sealed로 선언해야 한다. 인터넷의 예전 글에 많이 보이는 class User with _$User를 그대로 따라 쓰면 막힌다. 새로 쓸 때는 위처럼 abstract class로 시작한다.

json_serializable과 같이 쓰면 @JsonKey가 있는 자리에서 invalid_annotation_target 경고가 뜰 수 있다. 이 경고는 analysis_options.yaml에서 끄라고 안내되어 있다.

analyzer:
  errors:
    invalid_annotation_target: ignore

freezed로 상태 묶기: sealed

Bloc 글에서 sealed class로 직접 만든 상태 네 개도, freezed로 ==까지 한 번에 얻을 수 있다.

@freezed
sealed class UserState with _$UserState {
  const factory UserState.loading() = UserLoading;
  const factory UserState.loaded(User user) = UserLoaded;
  const factory UserState.error(String message) = UserError;
}

상태마다 클래스를 따로 쓰던 코드가 한 덩어리로 줄고, 각 상태가 내용이 같으면 같은 값으로 비교된다.

Kotlin, Swift와 비교하면

// Kotlin - data class + kotlinx.serialization
@Serializable
data class User(
    val id: Int,
    val name: String,
    @SerialName("created_at") val createdAt: String,
)

// Swift - Codable
struct User: Codable {
    let id: Int
    let name: String
    let createdAt: Date

    enum CodingKeys: String, CodingKey {
        case id, name
        case createdAt = "created_at"
    }
}

• 값 중심 클래스: Flutter freezed / Kotlin data class / Swift struct
• JSON 변환: Flutter는 json_serializable이 코드를 생성 / Kotlin은 @Serializable / Swift는 Codable이 자동
• 키 이름 대응: Flutter @JsonKey(name:) / Kotlin @SerialName / Swift CodingKeys
• 값 비교와 복사: Flutter는 freezed가 ==, copyWith 생성 / Kotlin data class가 기본 제공 / Swift struct는 Equatable을 붙이면 됨
• 생성 단계: Flutter만 build_runner를 따로 돌려야 함

Kotlin의 data class가 ==, copy, toString을 언어가 기본으로 주는 것을, Dart는 freezed가 코드 생성으로 흉내 낸다. 그래서 Dart에서는 build_runner라는 별도 단계가 생긴다.

정리

• json['키']를 손으로 쓰면 키 오타가 실행 중에야 터지므로, 클래스에 @JsonSerializable()을 붙여 변환 코드를 생성하게 한다
• 생성하려면 part '파일.g.dart'를 선언하고 dart run build_runner build를 돌리며, 필드를 고치면 다시 생성해야 한다
• 서버의 snake_case 키는 fieldRename: FieldRename.snake나 @JsonKey(name:)로 대응시킨다
• 평범한 클래스는 내용이 같아도 ==가 false라서 상태 비교가 어긋나므로, freezed로 ==, copyWith, toString을 생성한다
• freezed 3.0부터는 abstract class나 sealed class로 선언하고 factory 생성자에 필드를 적는다
• Kotlin data class, Swift Codable이 기본으로 주는 걸 Dart는 코드 생성으로 얻는다

다음 글에서는 앱을 껐다 켜도 남는 데이터를 저장하는 로컬 저장소(shared_preferences, drift)를 다뤄보겠다.