Friday, March 8, 2024

Dart에서 JSON을 제대로 다루는 방법
  /   No comments   

현대의 애플리케이션 개발에서 데이터는 산소와 같습니다. 특히 클라이언트 애플리케이션은 끊임없이 원격 서버와 데이터를 주고받으며 생명을 유지합니다. 이때 데이터 교환의 형식, 즉 '언어'를 통일하는 것은 매우 중요하며, 그 사실상의 표준 언어가 바로 JSON(JavaScript Object Notation)입니다. Google이 개발하고 Flutter 프레임워크의 심장 역할을 하는 Dart 언어 역시 이러한 흐름의 중심에 서 있습니다. 따라서 Dart 개발자에게 JSON을 능숙하게 다루는 능력은 선택이 아닌 필수 역량입니다.

이 글에서는 단순히 JSON 문자열을 Dart 객체로 변환하는 기술적인 방법을 넘어, 왜 그렇게 해야 하는지, 그리고 더 나아가 어떻게 하면 더 안정적이고, 유지보수하기 쉬우며, 협업에 용이한 코드를 작성할 수 있는지에 대한 '진실'에 초점을 맞추고자 합니다. 우리는 `dart:convert`라는 내장 라이브러리를 사용한 기초부터 시작하여, 타입 안정성(Type Safety)의 중요성을 깨닫고 모델 클래스를 도입하며, 마지막으로는 반복적인 작업을 자동화하여 생산성을 극대화하는 코드 생성(Code Generation) 기법까지 점진적으로 깊이를 더해갈 것입니다.

1. Dart와 JSON: 필연적인 만남의 배경

본격적인 기술 논의에 앞서, 왜 Dart와 JSON이 이토록 긴밀하게 연결될 수밖에 없는지 그 배경을 이해하는 것이 중요합니다. 이는 두 기술의 철학과 목적을 이해하는 과정이기도 합니다.

Dart: 클라이언트에 최적화된 언어의 의미

Dart는 "클라이언트 최적화(client-optimized)" 언어라고 불립니다. 이 말의 의미는 무엇일까요? 이는 단순히 UI를 그리는 기능을 넘어, 사용자와 상호작용하는 프론트엔드 환경에서 최고의 성능과 개발 경험을 제공하도록 설계되었다는 뜻입니다. Flutter가 단일 코드베이스로 모바일, 웹, 데스크톱에서 네이티브에 가까운 성능을 내는 비결이 바로 Dart의 이러한 특징에 있습니다.

  • JIT와 AOT 컴파일의 조화: 개발 중에는 JIT(Just-In-Time) 컴파일을 통해 코드 변경사항을 즉시 앱에 반영하는 '핫 리로드' 같은 빠른 개발 사이클을 지원합니다. 반면, 프로덕션용으로 앱을 빌드할 때는 AOT(Ahead-Of-Time) 컴파일을 통해 고성능의 네이티브 기계 코드로 변환되어 빠른 시작과 부드러운 애니메이션을 보장합니다.
  • 싱글 스레드와 이벤트 루프: Dart는 대부분의 UI 프레임워크와 마찬가지로 싱글 스레드 기반의 이벤트 루프 모델로 동작합니다. 이는 복잡한 동시성 문제로부터 개발자를 해방시켜 주지만, 동시에 네트워크 요청이나 파일 I/O와 같은 오래 걸리는 작업을 스레드 차단(blocking) 없이 비동기적으로 처리하는 능력이 매우 중요해짐을 의미합니다. `Future`와 `async/await` 문법이 바로 이러한 비동기 처리를 위한 핵심 도구입니다.

이러한 Dart의 특성은 자연스럽게 외부 데이터 소스, 특히 원격 서버와의 비동기 통신을 애플리케이션의 핵심 로직으로 만듭니다. 그리고 그 통신의 매개체가 바로 JSON입니다.

JSON: 단순함 속에 숨겨진 강력함

JSON은 과거 웹 데이터 교환의 주류였던 XML(eXtensible Markup Language)의 복잡성에 대한 대안으로 등장했습니다. JSON의 철학은 '최소한의 문법으로 최대한의 표현력'을 가지는 것입니다. 그 구조는 근본적으로 두 가지만 알면 됩니다.

  1. '이름-값' 쌍의 컬렉션: 대부분의 프로그래밍 언어에서 이는 객체(Object), 맵(Map), 딕셔너리(Dictionary) 등으로 표현됩니다. Dart에서는 `Map`이 이에 해당합니다.
  2. 순서가 있는 값의 목록: 이는 배열(Array) 또는 리스트(List)로 표현됩니다. Dart에서는 `List`이 해당합니다.

이 단순한 두 가지 구조의 조합만으로 현대 애플리케이션이 요구하는 거의 모든 종류의 데이터를 표현할 수 있습니다. 사람이 쉽게 읽고 쓸 수 있을 뿐만 아니라, 기계가 파싱하고 생성하는 속도도 매우 빠르다는 장점 덕분에 JSON은 명실상부한 데이터 교환의 표준으로 자리 잡았습니다.


   +-----------------------+      Serialization      +-----------------+
   |      Dart Object      |  (dart:convert.encode)   |   JSON String   |
   | (User, Product, etc.) | ---------------------> |  {"key": "value"} |
   |  (In-Memory, Typed)   | <--------------------- | (Text, Schemaless)|
   +-----------------------+     Deserialization     +-----------------+
                           (dart:convert.decode)

직렬화와 역직렬화: 두 세계를 잇는 다리

결국 Dart 애플리케이션 개발은 '메모리 상에 살아있는 Dart 객체'와 '네트워크를 통해 전달되는 텍스트 기반의 JSON 문자열'이라는 두 세계를 끊임없이 오가는 과정입니다. 이 두 세계를 연결하는 다리가 바로 직렬화(Serialization)와 역직렬화(Deserialization)입니다.

  • 직렬화 (Serialization / 인코딩): Dart 객체(예: `User` 클래스의 인스턴스)를 JSON 문자열로 변환하는 과정입니다. 서버로 데이터를 전송하거나, 디바이스의 파일 시스템에 객체 상태를 저장할 때 필요합니다.
  • 역직렬화 (Deserialization / 디코딩): 서버 API로부터 받은 JSON 문자열을 Dart 객체(예: `Map` 또는 `User` 인스턴스)로 변환하는 과정입니다. 이 데이터를 앱의 UI에 표시하거나 비즈니스 로직에 사용하기 위해 반드시 필요합니다.

이 두 과정은 완벽한 대칭을 이루어야 합니다. 즉, 어떤 Dart 객체를 직렬화했다가 다시 역직렬화했을 때, 원래의 객체와 동일한 상태와 구조를 가져야 데이터의 무결성이 보장됩니다. 이 과정을 얼마나 효율적이고 안전하게 처리하느냐가 애플리케이션 전체의 안정성을 좌우하게 됩니다.

2. 기본기 다지기: `dart:convert` 라이브러리 활용

Dart는 JSON 처리를 위한 강력한 표준 라이브러리인 `dart:convert`를 기본적으로 제공합니다. 외부 패키지를 추가로 설치할 필요 없이 바로 사용할 수 있어, 간단한 JSON 데이터를 다룰 때 매우 유용합니다. 이 라이브러리의 핵심은 `jsonEncode()`와 `jsonDecode()`라는 두 함수입니다.

직렬화(Encoding): `jsonEncode`로 Dart 객체를 문자열로

`jsonEncode()` 함수는 Dart 객체를 입력받아 JSON 형식의 문자열로 변환합니다. 이때 입력 가능한 Dart 객체는 `num`, `String`, `bool`, `null`, `List`, `Map` 타입으로 제한됩니다. `Map`의 키는 반드시 `String`이어야 합니다. 사용자 정의 클래스의 인스턴스는 직접 변환할 수 없으며, 이를 변환하는 방법은 나중에 자세히 다루겠습니다.

간단한 `Map` 객체를 JSON 문자열로 인코딩하는 예제를 보겠습니다.


import 'dart:convert';

void main() {
  // Dart Map 객체 생성
  var user = {
    'name': '이순신',
    'age': 47,
    'email': 'sunsin.lee@example.com',
    'isVerified': true,
    'skills': ['전략', '리더십', '해전']
  };

  // jsonEncode 함수를 사용하여 JSON 문자열로 변환
  var jsonString = jsonEncode(user);

  // 결과 출력
  print(jsonString);
  // 출력 결과:
  // {"name":"이순신","age":47,"email":"sunsin.lee@example.com","isVerified":true,"skills":["전략","리더십","해전"]}
}

만약 좀 더 읽기 쉬운 형태로 출력하고 싶다면, `JsonEncoder` 클래스를 사용하여 들여쓰기를 추가할 수 있습니다.


import 'dart:convert';

void main() {
  var user = {
    'name': '이순신',
    'age': 47,
    'email': 'sunsin.lee@example.com',
  };
  
  // 2칸 들여쓰기(space)를 사용하여 보기 좋게 포맷팅
  var encoder = JsonEncoder.withIndent('  ');
  var prettyJsonString = encoder.convert(user);

  print(prettyJsonString);
  /* 출력 결과:
  {
    "name": "이순신",
    "age": 47,
    "email": "sunsin.lee@example.com"
  }
  */
}

역직렬화(Decoding): `jsonDecode`로 문자열을 Dart 객체로

`jsonDecode()` 함수는 `jsonEncode()`와 정반대의 역할을 수행합니다. 즉, JSON 형식의 문자열을 입력받아 Dart 객체로 변환합니다. 반환되는 객체의 타입은 `dynamic`이지만, 실제 런타임 타입은 JSON 문자열의 최상위 구조에 따라 결정됩니다. JSON 객체(`{...}`)는 `Map`으로, JSON 배열(`[...]`)은 `List`으로 변환됩니다.

앞서 생성한 JSON 문자열을 다시 Dart의 `Map` 객체로 디코딩하는 예제입니다.


import 'dart:convert';

void main() {
  var jsonString = '{"name":"강감찬","age":73,"city":"서울","roles":["장군", "재상"]}';

  // jsonDecode의 반환 타입은 dynamic이므로,
  // 이후 안전한 사용을 위해 Map<String, dynamic>으로 타입 캐스팅을 해주는 것이 일반적입니다.
  var decodedData = jsonDecode(jsonString);
  
  // 타입을 확인해봅시다.
  print(decodedData.runtimeType); // 출력: _InternalLinkedHashMap<String, dynamic> (Map의 구현체)

  // 명시적으로 캐스팅하여 사용
  var userMap = decodedData as Map<String, dynamic>;

  // 이제 Map처럼 키를 사용하여 값에 접근할 수 있습니다.
  String name = userMap['name'];
  int age = userMap['age'];
  List<dynamic> roles = userMap['roles']; // List 내부의 타입은 아직 dynamic 입니다.
  
  print('이름: $name');   // 출력: 이름: 강감찬
  print('나이: $age');     // 출력: 나이: 73
  print('첫 번째 역할: ${roles[0]}'); // 출력: 첫 번째 역할: 장군
}

`dynamic` 타입의 함정과 예외 처리의 중요성

`jsonDecode`를 사용할 때 가장 주의해야 할 점은 반환 타입이 `dynamic`이라는 사실입니다. 이는 컴파일 시점에는 타입 체크가 이루어지지 않고, 런타임에 실제 타입이 결정된다는 의미입니다. 이는 편리함을 주기도 하지만, 동시에 치명적인 오류의 원인이 될 수 있습니다.

  • 오타의 위험: `userMap['naem']`과 같이 키 이름을 잘못 입력해도 컴파일러는 오류를 잡아내지 못합니다. 이 코드는 런타임에 `null`을 반환하게 되며, 만약 이 값을 `String` 타입의 변수에 할당하려고 하면 `TypeError`가 발생할 수 있습니다.
  • 예상치 못한 타입: 서버 API의 응답이 변경되어 `age` 필드가 `"73"`과 같이 문자열로 내려올 경우, `int age = userMap['age']` 코드에서 런타임 에러가 발생합니다.

또한, `jsonDecode`는 유효하지 않은 JSON 형식의 문자열(예: 콤마가 빠졌거나, 따옴표가 잘못된 경우)을 만나면 `FormatException`이라는 예외를 발생시킵니다. 외부 API와 같이 우리가 통제할 수 없는 데이터 소스를 다룰 때는 반드시 `try-catch` 블록을 사용하여 예외 상황을 처리해야 합니다.


import 'dart:convert';

void main() {
  var invalidJsonString = '{"name":"세종대왕", "reign_period":}'; // 값이 누락된 잘못된 JSON

  try {
    var userMap = jsonDecode(invalidJsonString) as Map<String, dynamic>;
    print('사용자 이름: ${userMap['name']}');
  } on FormatException catch (e) {
    print('JSON 파싱 에러가 발생했습니다: $e');
  } catch (e) {
    print('알 수 없는 에러가 발생했습니다: $e');
  }
}

이처럼 `dart:convert`는 JSON 처리의 기본을 제공하지만, 대규모 애플리케이션에서 `Map`을 직접 다루는 방식은 코드의 안정성과 유지보수성을 저해하는 요인이 됩니다. 이제 이 문제를 해결하기 위한 더 나은 접근법을 살펴보겠습니다.

3. 진정한 도약: 모델 클래스를 통한 타입 안정성 확보

소프트웨어 공학의 중요한 원칙 중 하나는 '데이터와 그 데이터를 처리하는 행위를 하나로 묶는 것'입니다. `Map`을 직접 사용하는 방식은 데이터의 구조가 코드 곳곳에 문자열 키의 형태로 흩어져 있어 이 원칙을 위배합니다. 이를 해결하는 가장 효과적인 방법은 JSON 데이터 구조를 표현하는 전용 모델 클래스(Model Class)를 작성하는 것입니다.

왜 모델 클래스를 사용해야 하는가?

모델 클래스를 도입하는 것은 단순히 코드를 조금 더 정리하는 수준의 문제가 아닙니다. 이는 개발 패러다임의 전환이며, 다음과 같은 명확하고 강력한 이점을 제공합니다.

  • 타입 안정성 (Type Safety): `user.name`과 같이 클래스의 속성에 접근하게 되므로, `user.naem`과 같은 오타는 컴파일 시점에 즉시 발견됩니다. 런타임에 발생할 수 있었던 수많은 버그를 사전에 예방할 수 있습니다.
  • 코드 가독성 및 자동 완성: `Map`의 키가 어떤 것들이 있는지 기억하거나 문서를 찾아볼 필요가 없습니다. 클래스 정의 자체가 명확한 문서 역할을 하며, IDE(통합 개발 환경)는 `user.`을 입력하는 순간 사용 가능한 모든 속성(`name`, `age`, `email` 등)을 보여주어 개발 속도와 정확성을 비약적으로 향상시킵니다.
  • 데이터 유효성 검사 및 비즈니스 로직 추가: 모델 클래스의 생성자나 메서드 내에서 데이터 유효성 검사(예: 이메일 형식이 올바른지, 나이가 음수가 아닌지)를 수행할 수 있습니다. 또한, `user.isAdult()`와 같이 해당 데이터와 관련된 비즈니스 로직을 클래스 내에 캡슐화하여 코드를 더욱 객체지향적으로 만들 수 있습니다.
  • 유지보수의 용이성: API 명세가 변경되어 `email` 필드가 `emailAddress`로 바뀐다고 상상해 보세요. `Map`을 사용했다면 코드 전체에서 `'email'` 문자열을 찾아 `'emailAddress'`로 바꿔야 하지만, 모델 클래스를 사용하면 `User` 클래스의 해당 속성 이름과 `fromJson` 팩토리 생성자 내부의 키 값만 수정하면 됩니다. 변경의 영향 범위가 명확하게 한 곳으로 집중됩니다.

`fromJson` 팩토리 생성자 패턴

JSON 데이터를 모델 클래스의 인스턴스로 변환하기 위해 가장 널리 사용되는 패턴은 `fromJson`이라는 이름의 팩토리 생성자(factory constructor)를 만드는 것입니다.

JSONPlaceholder라는 테스트용 공개 API의 사용자 데이터를 모델링하는 `User` 클래스를 예로 들어보겠습니다.


// user.dart
class User {
  // 1. 필드는 final로 선언하여 불변(immutable) 객체로 만드는 것을 권장합니다.
  //    이는 상태 관리를 예측 가능하게 만듭니다.
  final int id;
  final String name;
  final String username;
  final String email;

  // 2. 일반 생성자
  User({
    required this.id,
    required this.name,
    required this.username,
    required this.email,
  });

  // 3. 'fromJson' 팩토리 생성자
  //    Map<String, dynamic>을 입력받아 User 인스턴스를 생성합니다.
  //    JSON 역직렬화 로직을 클래스 내부에 캡슐화하는 핵심적인 부분입니다.
  factory User.fromJson(Map<String, dynamic> json) {
    // 4. Map의 키를 사용하여 각 필드를 초기화합니다.
    //    이 과정에서 타입 변환이나 유효성 검사를 수행할 수 있습니다.
    return User(
      id: json['id'] as int,
      name: json['name'] as String,
      username: json['username'] as String,
      email: json['email'] as String,
    );
  }
}

이 패턴의 아름다움은 `User` 클래스가 "JSON `Map`으로부터 자신을 어떻게 생성해야 하는지" 스스로 알고 있다는 점입니다. 데이터 변환의 책임이 명확하게 해당 데이터 모델 클래스에 위치하게 되어 코드의 응집도가 높아집니다.

`toJson` 메서드: 직렬화 로직 캡슐화

역직렬화와 마찬가지로, 직렬화 로직 역시 모델 클래스 내부에 포함시키는 것이 좋습니다. 이는 `toJson`이라는 이름의 일반 메서드를 추가하여 구현할 수 있습니다. 이 메서드는 `User` 인스턴스의 상태를 `Map<String, dynamic>` 형태로 변환하여 반환합니다.


// user.dart (이어서)
class User {
  // ... (기존 필드와 생성자)

  factory User.fromJson(Map<String, dynamic> json) {
    // ... (기존 fromJson 구현)
  }

  // User 인스턴스를 다시 Map<String, dynamic>으로 변환하는 메서드
  // 서버로 데이터를 보내거나 파일에 저장할 때 사용됩니다.
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'username': username,
      'email': email,
    };
  }
}

이제 `User` 클래스는 `fromJson`과 `toJson`을 모두 가짐으로써 완벽한 직렬화/역직렬화 사이클을 자체적으로 처리할 수 있는 완전한 데이터 객체가 되었습니다.

실전 예제: API 통신과 모델 클래스 연동

이제 완성된 `User` 모델을 사용하여 실제 네트워크 요청을 처리하는 방법을 살펴보겠습니다. Flutter/Dart 프로젝트에서 HTTP 통신을 위해 가장 널리 사용되는 `http` 패키지를 사용합니다.

먼저 `pubspec.yaml` 파일에 `http` 패키지를 추가합니다.


dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0 # http 패키지 버전은 최신 버전을 확인하고 명시

그 다음, `http` 패키지와 `dart:convert`를 사용하여 사용자 목록을 가져와 `List`로 변환하는 비동기 함수를 작성할 수 있습니다.


import 'dart:convert';
import 'package:http/http.dart' as http;
// 위에서 정의한 User 클래스가 포함된 파일을 import 합니다.
// import 'user.dart';

// 사용자 목록을 가져와 User 객체의 리스트로 변환하는 비동기 함수
Future<List<User>> fetchUsers() async {
  final response =
      await http.get(Uri.parse('https://jsonplaceholder.typicode.com/users'));

  // 1. 성공적인 응답 확인 (Status Code 200)
  if (response.statusCode == 200) {
    // 2. 응답 본문(JSON 문자열)을 디코딩하여 List<dynamic>으로 변환
    //    응답 본문은 UTF-8로 디코딩해야 한글 깨짐 등을 방지할 수 있습니다.
    List<dynamic> usersJson = jsonDecode(utf8.decode(response.bodyBytes));
    
    // 3. List<dynamic>의 각 요소를 User.fromJson을 사용하여 User 객체로 변환
    //    map() 함수를 사용하여 각 JSON 객체에 대해 변환 함수를 적용하고,
    //    toList()로 최종 결과를 List<User>로 만듭니다.
    List<User> users = usersJson.map((json) => User.fromJson(json)).toList();
    
    return users;
  } else {
    // 4. 실패 시 예외 발생
    //    실제 앱에서는 상태 코드별로 더 상세한 오류 처리가 필요합니다.
    throw Exception('사용자 목록을 불러오는데 실패했습니다. 상태 코드: ${response.statusCode}');
  }
}

void main() async {
  try {
    List<User> users = await fetchUsers();
    print('성공적으로 ${users.length}명의 사용자 정보를 가져왔습니다.');
    
    if (users.isNotEmpty) {
      // 이제 타입이 보장된 객체로 안전하게 데이터에 접근할 수 있습니다.
      print('첫 번째 사용자 이름: ${users.first.name}');
      print('두 번째 사용자 이메일: ${users[1].email}');

      // User 객체를 다시 JSON으로 변환하는 것도 가능합니다.
      var firstUserJsonString = jsonEncode(users.first.toJson());
      print('첫 번째 사용자 JSON: $firstUserJsonString');
    }
  } catch (e) {
    print('에러가 발생했습니다: $e');
  }
}

이 코드는 역할 분리가 명확합니다. `User` 클래스는 데이터의 구조와 직렬화/역직렬화 방법을 정의하고, `fetchUsers` 함수는 네트워크 통신과 데이터 변환 흐름을 관리합니다. `main` 함수는 최종적으로 타입이 보장된 `User` 객체를 사용하여 비즈니스 로직을 수행합니다. 이처럼 각 요소가 자신의 책임에만 집중함으로써 코드 전체의 복잡성이 관리되고 가독성과 유지보수성이 크게 향상됩니다.

심화: 중첩된 JSON 객체 다루기

실제 API 응답은 필드가 중첩된 복잡한 구조를 가지는 경우가 많습니다. 예를 들어, `User` 데이터에 `address`라는 주소 객체가 포함될 수 있습니다.


{
  "id": 1,
  "name": "Leanne Graham",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  }
}

이런 구조는 중첩된 객체 각각에 대해 모델 클래스를 만들어 해결합니다. `Geo` 클래스와 `Address` 클래스를 먼저 정의합니다.


class Geo {
  final String lat;
  final String lng;

  Geo({required this.lat, required this.lng});

  factory Geo.fromJson(Map<String, dynamic> json) {
    return Geo(lat: json['lat'], lng: json['lng']);
  }

  Map<String, dynamic> toJson() => {'lat': lat, 'lng': lng};
}

class Address {
  final String street;
  final String suite;
  final String city;
  final String zipcode;
  final Geo geo;

  Address({
    required this.street,
    required this.suite,
    required this.city,
    required this.zipcode,
    required this.geo,
  });

  factory Address.fromJson(Map<String, dynamic> json) {
    return Address(
      street: json['street'],
      suite: json['suite'],
      city: json['city'],
      zipcode: json['zipcode'],
      // 중첩된 객체는 해당 객체의 fromJson 생성자를 호출하여 생성합니다.
      geo: Geo.fromJson(json['geo']),
    );
  }

  Map<String, dynamic> toJson() => {
    'street': street,
    'suite': suite,
    'city': city,
    'zipcode': zipcode,
    'geo': geo.toJson(), // 중첩된 객체는 toJson() 메서드를 호출합니다.
  };
}

이제 `User` 클래스를 수정하여 `Address` 타입의 필드를 포함시키고, `fromJson`과 `toJson`에서 `Address`의 생성자와 메서드를 호출하도록 합니다.


class User {
  final int id;
  final String name;
  final Address address; // Address 객체를 필드로 가집니다.

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      // Address의 fromJson을 호출하여 Address 인스턴스를 생성합니다.
      address: Address.fromJson(json['address']),
    );
  }

  Map<String, dynamic> toJson() => {
    'id': id,
    'name': name,
    'address': address.toJson(), // Address의 toJson을 호출합니다.
  };
}

이러한 재귀적인 구조를 통해 아무리 복잡하게 중첩된 JSON이라도 체계적이고 타입-세이프하게 다룰 수 있습니다. 각 클래스는 자신의 데이터만 책임지므로, 전체 구조가 명확하고 관리가 용이해집니다.

4. 생산성 혁신: 코드 생성(Code Generation)의 세계

모델 클래스를 직접 작성하는 방식은 매우 강력하지만, 프로젝트의 규모가 커지고 다루어야 할 모델 클래스가 수십, 수백 개로 늘어나면 `fromJson`과 `toJson` 메서드를 작성하는 것이 매우 반복적이고 지루한 작업이 됩니다. 필드 하나를 추가하거나 수정할 때마다 생성자와 `fromJson`, `toJson` 메서드를 모두 수정해야 하며, 이 과정에서 실수가 발생할 가능성도 높아집니다.

이러한 '보일러플레이트(boilerplate)' 코드를 해결하기 위해 Dart 생태계는 코드 생성(Code Generation)이라는 강력한 해법을 제공합니다. 개발자는 데이터 구조의 핵심인 클래스와 필드만 정의하고, 직렬화/역직렬화 로직은 빌드 도구가 자동으로 생성하도록 하는 방식입니다. 이 분야의 표준 패키지가 바로 `json_serializable`입니다.

왜 코드 생성을 사용해야 하는가?

코드 생성은 단순히 타이핑을 줄여주는 것 이상의 가치를 지닙니다.

  • 생산성 극대화: 개발자는 비즈니스 로직과 데이터 모델링이라는 핵심에만 집중할 수 있습니다. 반복적인 코드는 기계에 맡기고 창의적인 문제 해결에 시간을 쏟을 수 있습니다.
  • 인간의 실수 방지: `fromJson`에서 키 이름을 잘못 입력하거나, `toJson`에서 필드 하나를 빠뜨리는 등의 실수는 코드 생성기를 사용하면 원천적으로 발생하지 않습니다. 생성된 코드는 항상 모델 클래스의 정의와 일관성을 유지합니다.
  • 복잡한 타입 처리: `DateTime`, `Enum`, `Uri` 등 JSON으로 직접 표현되지 않는 타입을 다루거나, `JsonKey` 어노테이션을 통해 필드 이름 변경, 기본값 설정, null 처리 등 복잡하고 세밀한 제어를 손쉽게 처리할 수 있습니다.

`json_serializable` 설정 및 사용법

`json_serializable`을 사용하기 위해서는 몇 가지 패키지를 설정해야 합니다.

1. `pubspec.yaml` 파일에 의존성 추가:

  • `dependencies`: 앱의 런타임에 필요한 패키지를 추가합니다. `json_annotation`은 생성된 코드가 참조하는 어노테이션을 제공합니다.
  • `dev_dependencies`: 개발 과정에서만 필요한 패키지를 추가합니다. `build_runner`는 코드 생성 프로세스를 실행하는 도구이며, `json_serializable`은 실제 직렬화 코드를 생성하는 빌더입니다.

dependencies:
  flutter:
    sdk: flutter
  # 런타임에 필요한 어노테이션 패키지
  json_annotation: ^4.9.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  # 코드 생성 실행 도구
  build_runner: ^2.4.9
  # JSON 직렬화 코드 생성기
  json_serializable: ^6.8.0

패키지를 추가한 후에는 터미널에서 `flutter pub get` 또는 `dart pub get`을 실행하여 설치합니다.

2. 모델 클래스 수정:

이제 `User` 클래스를 `json_serializable`이 인식할 수 있도록 수정합니다. `fromJson`과 `toJson`의 실제 구현은 직접 작성하는 대신, 생성될 파일에 위임합니다.


import 'package:json_annotation/json_annotation.dart';

// 1. 'part' 지시어 추가:
//    현재 파일(예: user.dart)과 생성될 파일(user.g.dart)이
//    하나의 라이브러리 일부임을 명시합니다.
//    파일 이름은 '현재파일명.g.dart' 형식이어야 합니다.
part 'user.g.dart';

// 2. 클래스 위에 @JsonSerializable() 어노테이션 추가:
//    이 클래스가 코드 생성의 대상임을 알립니다.
@JsonSerializable()
class User {
  final int id;
  final String name;
  final String username;
  final String email;

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

  // 3. fromJson 팩토리 생성자:
  //    구현부를 생성될 `_$UserFromJson` 함수 호출로 대체합니다.
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);

  // 4. toJson 메서드:
  //    구현부를 생성될 `_$UserToJson` 함수 호출로 대체합니다.
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

3. 코드 생성 명령어 실행:

프로젝트의 루트 디렉토리에서 다음 명령어를 실행합니다. 이 명령어는 프로젝트 내의 모든 코드 생성기를 실행하여 필요한 파일을 만들어냅니다.


# 일회성으로 코드를 생성할 때
dart run build_runner build

# 또는, 파일이 변경될 때마다 자동으로 코드를 다시 생성하고 싶을 때 (추천)
dart run build_runner watch

명령어를 실행하면 `user.dart` 파일 옆에 `user.g.dart`라는 새로운 파일이 생성된 것을 확인할 수 있습니다. 이 파일의 내용은 우리가 직접 열어보거나 수정할 필요가 없지만, 내부를 살펴보면 `_$UserFromJson`과 `_$UserToJson` 함수가 우리가 수동으로 작성했던 것과 유사한 로직으로 구현되어 있는 것을 볼 수 있습니다.

`@JsonKey` 어노테이션으로 세밀하게 제어하기

`json_serializable`의 진정한 강력함은 `@JsonKey` 어노테이션을 통해 다양한 예외 상황과 요구사항을 처리할 수 있다는 점에서 드러납니다. 몇 가지 유용한 사례를 살펴보겠습니다.


import 'package:json_annotation/json_annotation.dart';

part 'product.g.dart';

// @JsonSerializable 어노테이션에 옵션을 줄 수도 있습니다.
// fieldRename: 모든 필드의 이름을 스네이크 케이스(snake_case)로 자동 변환
// createToJson: toJson 메서드 생성 여부 (기본값 true)
@JsonSerializable(fieldRename: FieldRename.snake, createToJson: true)
class Product {
  // @JsonKey: JSON 키 이름과 Dart 필드 이름이 다를 때 매핑
  @JsonKey(name: 'product_id')
  final String id;
  
  final String productName;

  // @JsonKey: JSON에 해당 키가 없을 경우 사용할 기본값 설정
  @JsonKey(defaultValue: 0.0)
  final double price;

  // @JsonKey: null 값을 허용하지 않는 필드인데 JSON에서 null이 올 경우 예외 발생 방지
  @JsonKey(required: false, disallowNullValue: false)
  final bool? isAvailable;
  
  // @JsonKey: 직렬화/역직렬화 과정에서 제외할 필드
  @JsonKey(includeFromJson: false, includeToJson: false)
  final String internalMemo;

  // @JsonKey: 커스텀 함수를 사용하여 DateTime <-> String 변환 처리
  @JsonKey(
    fromJson: _dateTimeFromIso8601,
    toJson: _dateTimeToIso8601
  )
  final DateTime createdAt;

  Product({
    required this.id,
    required this.productName,
    required this.price,
    this.isAvailable,
    this.internalMemo = '',
    required this.createdAt,
  });

  factory Product.fromJson(Map<String, dynamic> json) => _$ProductFromJson(json);
  Map<String, dynamic> toJson() => _$ProductToJson(this);
}

// @JsonKey에서 참조할 커스텀 파싱 함수
DateTime _dateTimeFromIso8601(String dateString) => DateTime.parse(dateString);
String _dateTimeToIso8601(DateTime dateTime) => dateTime.toIso8601String();

이처럼 `json_serializable`과 어노테이션을 활용하면, 개발자는 데이터의 구조와 특별한 규칙을 선언적으로 정의하기만 하면 됩니다. 지루하고 실수하기 쉬운 직렬화 로직의 구현은 완전히 자동화되어, 개발자는 더 높은 수준의 문제에 집중할 수 있게 됩니다.

5. 결론 및 나아갈 방향

지금까지 Dart에서 JSON을 다루는 여정을 함께했습니다. `dart:convert`를 사용한 단순한 문자열 변환에서 시작하여, 타입 안정성과 유지보수성을 위해 모델 클래스를 직접 구현하는 단계를 거쳐, 최종적으로는 `json_serializable`을 통한 코드 생성으로 생산성을 극대화하는 방법에 이르렀습니다.

핵심 요약:

  1. 시작은 `dart:convert`: `jsonEncode()`와 `jsonDecode()`는 Dart의 JSON 처리의 기본입니다. 간단한 데이터나 빠른 프로토타이핑에 유용합니다.
  2. 성장은 모델 클래스와 함께: `Map<String, dynamic>`의 한계를 극복하고 타입 안정성, 코드 가독성, 유지보수성을 확보하려면 반드시 모델 클래스를 작성해야 합니다. `fromJson` 팩토리 생성자와 `toJson` 메서드 패턴은 필수입니다.
  3. 숙달은 코드 생성으로: 프로젝트가 복잡해지면 `json_serializable`과 같은 코드 생성 도구를 도입하여 반복 작업을 자동화하고 실수를 방지하며 생산성을 비약적으로 향상시켜야 합니다.

JSON 처리는 단순히 데이터를 변환하는 기술이 아니라, 애플리케이션의 안정성과 확장성을 결정하는 중요한 아키텍처 설계의 일부입니다. 견고한 데이터 모델링은 잘 만들어진 애플리케이션의 뼈대와 같습니다.

여기서 멈추지 않고 더 깊이 학습하고 싶다면 다음 주제들을 탐구해 보시길 권장합니다.

  • 불변성(Immutability)과 `equatable` / `freezed`: 모델 클래스의 필드를 `final`로 선언하여 불변 객체로 만드는 것은 상태 관리를 단순화하고 버그를 줄이는 좋은 습관입니다. 더 나아가, `equatable`이나 `freezed` 같은 패키지를 사용하면 값 기반의 동등성 비교(`==`)와 `hashCode`를 자동으로 구현해주어, 상태 관리 프레임워크(Bloc, Riverpod 등)와 함께 사용할 때 매우 유용합니다.
  • 에러 처리 심화: 네트워크 레이어에서 발생하는 다양한 HTTP 상태 코드(400, 401, 404, 500 등)와 비즈니스 로직 상의 에러를 어떻게 우아하게 모델링하고 UI에 전달할 것인지에 대한 고민은 애플리케이션의 완성도를 높입니다.
  • JSON을 넘어서: 대부분의 경우 JSON이 훌륭한 선택이지만, 고성능이 요구되거나 엄격한 스키마가 중요한 시스템 간 통신에서는 Protocol Buffers (protobuf)나 FlatBuffers 같은 다른 직렬화 프레임워크가 더 나은 대안이 될 수 있습니다.

꾸준한 학습과 실습을 통해 데이터 처리의 달인이 되어, 더욱 안정적이고 효율적인 Dart 애플리케이션을 만들어나가시길 바랍니다.


0 개의 댓글:

Post a Comment