앱은 대부분 서버에서 데이터를 받아와서 화면에 보여준다. 비동기 글에서는 Future.delayed로 서버 요청을 흉내 냈는데, 이번엔 진짜 서버에 요청을 보내본다. 이 글은 dio 5.x 기준이고, 연습용 공개 API(jsonplaceholder)를 쓴다. 먼저 설치한다.

flutter pub add dio

사용자 한 명의 정보를 받아와서 이름을 출력하는 코드를 짜본다. 비동기 글의 습관이 아직 안 붙었다면 이렇게 쓰기 쉽다.

import 'package:dio/dio.dart';

Future<void> main() async {
  final dio = Dio();
  final response = dio.get('https://jsonplaceholder.typicode.com/users/1');
  print(response.data); // 여기서 에러남
}

에디터에 빨간 줄이 뜬다.

The getter 'data' isn't defined for the type 'Future<Response<dynamic>>'.

dio.get은 응답이 아니라 Future<Response>, 즉 "나중에 응답이 도착한다"는 약속을 돌려준다. Future에는 data가 없다.

해결: await로 응답을 꺼낸다

import 'package:dio/dio.dart';

Future<void> main() async {
  final dio = Dio();
  final response = await dio.get('https://jsonplaceholder.typicode.com/users/1');

  print(response.statusCode); // 200
  print(response.data['name']); // Leanne Graham
}

• await: 응답이 도착할 때까지 이 줄에서 기다린다. 이 함수에는 async가 붙어 있어야 한다
• response.statusCode: HTTP 상태 코드다. 200이면 성공이다
• response.data: 응답 본문이다. 서버가 JSON을 주면 dio가 자동으로 Map이나 List로 바꿔서 준다. 문자열을 직접 jsonDecode할 필요가 없다

response.data의 타입은 dynamic이다. 에디터가 안에 뭐가 있는지 모른다는 뜻이라, response.data['name']에서 오타를 내도 컴파일은 통과하고 실행해서 null이 나온다. 이 문제는 뒤에서 모델 클래스로 푼다.

Dio 한 번 설정해서 계속 쓰기

주소의 앞부분을 매번 쓰는 건 번거롭다. BaseOptions로 공통 설정을 한 번 정한다.

final dio = Dio(BaseOptions(
  baseUrl: 'https://jsonplaceholder.typicode.com',
  connectTimeout: const Duration(seconds: 5),
  receiveTimeout: const Duration(seconds: 5),
));

final response = await dio.get('/users/1'); // baseUrl 뒤에 붙음

• baseUrl: 모든 요청 주소의 앞부분이다
• connectTimeout, receiveTimeout: 연결과 응답을 기다리는 최대 시간이다. 정하지 않으면 서버가 응답하지 않을 때 사용자가 한참 기다린다

Dio 객체는 앱 전체에서 하나를 만들어서 공유하는 게 보통이다. 요청할 때마다 Dio()를 새로 만들면 설정도 매번 다시 해야 한다.

쿼리와 본문을 보낼 때는 이렇게 쓴다.

// GET /users?page=1&limit=10
await dio.get('/users', queryParameters: {'page': 1, 'limit': 10});

// POST /users, 본문에 data를 JSON으로 담아 보냄
await dio.post('/users', data: {'name': '홍길동'});

data에 Map을 넣으면 JSON으로 바꿔서 보낸다.

삽질 포인트 1: 404인데 에러가 난다 - dio는 실패 응답을 예외로 던진다

없는 사용자를 요청해보자.

final response = await dio.get('/users/9999');
print(response.data); // 여기까지 오지 못함

jsonplaceholder는 없는 사용자에 404를 준다. 이때 dio는 응답을 돌려주는 대신 DioException을 던진다. Dart의 http 패키지는 404도 그냥 응답으로 주고 statusCode를 직접 확인하게 하는데, dio는 2xx가 아니면 예외로 취급한다. 그래서 try/catch가 필요하다.

try {
  final response = await dio.get('/users/9999');
  print(response.data);
} on DioException catch (e) {
  if (e.response?.statusCode == 404) {
    print('없는 사용자예요');
  } else {
    print('요청 실패: ${e.type}');
  }
}

• on DioException catch (e): dio가 던진 예외만 잡는다. 비동기 글의 try/catch에 예외 타입을 지정한 형태다
• e.response?.statusCode: 서버가 응답을 줬다면 상태 코드가 있다. 서버에 아예 닿지 못했다면 response가 null이라서 ?.가 필요하다. null safety 글에서 본 그 연산자다
• e.type: 실패한 이유다. 연결 시간 초과(connectionTimeout), 서버가 실패 응답을 줌(badResponse), 인터넷이 없음(connectionError) 같은 종류로 나뉜다

예전 글에는 DioError가 많이 보인다. 5.x부터 DioException으로 바뀌었으니 새 코드에서는 DioException을 쓴다.

응답을 모델 클래스로 바꾸기

response.data가 dynamic이라 오타를 컴파일러가 못 잡는 문제를, 응답을 클래스로 바꿔서 푼다. 생성자 글에서 본 factory fromJson이 바로 이 자리에 쓰인다.

class User {
  final int id;
  final String name;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'] as int,
      name: json['name'] as String,
    );
  }
}

Future<User> fetchUser(int id) async {
  final response = await dio.get('/users/$id');
  return User.fromJson(response.data as Map<String, dynamic>);
}

이제 호출하는 쪽에서는 user.name처럼 쓴다. user.nmae로 오타를 내면 에디터가 바로 빨간 줄을 친다. fromJson을 직접 쓰는 게 필드가 늘어나면 번거로운데, 이걸 자동으로 만들어주는 방법은 다음 글에서 다룬다.

목록(List)은 map으로 하나씩 바꾼다. 컬렉션 글에서 본 .toList() 습관이 여기서도 필요하다.

Future<List<User>> fetchUsers() async {
  final response = await dio.get('/users');
  final list = response.data as List;
  return list
      .map((json) => User.fromJson(json as Map<String, dynamic>))
      .toList();
}

삽질 포인트 2: 에뮬레이터에서만, 또는 릴리스에서만 안 된다

코드는 맞는데 통신이 안 되는 경우는 대부분 코드 밖의 설정이다.

• 안드로이드 릴리스 빌드에서만 안 된다: 디버그 실행에서는 되는데 배포용으로 빌드하면 안 되는 경우다. 앱의 AndroidManifest.xml에 <uses-permission android:name="android.permission.INTERNET"/>가 있는지 확인한다. 디버그용 설정에만 들어 있고 정식 설정에는 빠져 있을 수 있다
• 내 컴퓨터의 서버에 localhost로 접속이 안 된다: 안드로이드 에뮬레이터에게 localhost는 에뮬레이터 자기 자신이다. 내 컴퓨터는 10.0.2.2로 접속한다. iOS 시뮬레이터는 localhost가 그대로 내 컴퓨터를 가리킨다
• iOS에서 http:// 주소만 막힌다: iOS는 암호화되지 않은 http 통신을 기본으로 막는다. 서버를 https로 바꾸는 게 정석이다

인터셉터: 모든 요청에 공통으로 끼어들기

로그인 토큰을 모든 요청에 붙이거나 로그를 남기고 싶을 때, 요청마다 코드를 쓰지 않고 인터셉터를 한 번 등록한다.

dio.interceptors.add(
  InterceptorsWrapper(
    onRequest: (options, handler) {
      options.headers['Authorization'] = 'Bearer $token'; // 모든 요청에 토큰
      handler.next(options); // 다음 단계로 진행
    },
    onError: (DioException e, handler) {
      print('실패: ${e.requestOptions.path}');
      handler.next(e);
    },
  ),
);

onRequest는 요청을 보내기 직전에, onError는 실패했을 때 실행된다. 마지막의 handler.next(...)를 빼먹으면 요청이 거기서 멈춘다.

Compose, SwiftUI와 비교하면

// Kotlin - Retrofit
interface UserApi {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}
// JSON -> User 변환은 컨버터가 자동으로 해줌

// Swift - URLSession
let (data, _) = try await URLSession.shared.data(from: url)
let user = try JSONDecoder().decode(User.self, from: data)

• 요청 보내기: Flutter dio.get('/users/1') / Kotlin Retrofit 인터페이스 함수 / Swift URLSession.shared.data
• 기다리기: Flutter await / Kotlin suspend / Swift await
• JSON을 객체로: Flutter는 fromJson을 직접 작성 / Kotlin은 컨버터가 자동 / Swift는 Codable + JSONDecoder가 자동
• 실패 처리: Flutter DioException / Kotlin HttpException 등 / Swift throws 에러
• 공통 처리: Flutter 인터셉터 / Kotlin OkHttp 인터셉터 / Swift 직접 구성

Retrofit이 dio와 가장 닮았다. 둘 다 서버 통신 라이브러리고, OkHttp의 인터셉터와 dio의 인터셉터는 개념이 같다. 다만 Retrofit과 Swift의 Codable은 JSON을 객체로 자동 변환해주는 반면, Dart에서는 fromJson을 직접 써야 한다는 게 가장 큰 차이다.

참고: dio와 http 패키지

Dart에는 더 가벼운 http 패키지도 있다. 간단한 요청만 한다면 충분하다. dio는 타임아웃, 인터셉터, 요청 취소, 파일 업로드 같은 기능이 기본으로 들어 있어서, 앱이 커질수록 편해진다. 이 시리즈는 dio를 기준으로 간다.

정리

• dio.get은 Future<Response>를 돌려주므로 await로 꺼내야 response.data를 쓸 수 있다
• JSON 응답은 dio가 자동으로 Map이나 List로 바꿔주지만 타입이 dynamic이라, 모델 클래스의 factory fromJson으로 바꿔서 쓴다
• Dio는 BaseOptions로 baseUrl과 타임아웃을 정해서 앱 전체에서 하나를 공유한다
• dio는 2xx가 아닌 응답을 DioException으로 던지므로 try/catch로 감싸고, e.response?.statusCode나 e.type으로 실패 이유를 구분한다
• 코드가 맞는데 통신이 안 되면 안드로이드의 INTERNET 권한, 에뮬레이터의 10.0.2.2, iOS의 http 차단을 의심한다
• 토큰이나 로그처럼 모든 요청에 공통인 처리는 인터셉터에 한 번만 등록한다

다음 글에서는 fromJson을 직접 쓰는 수고를 줄여주는 json_serializable과 freezed를 다뤄보겠다.