Flutter 튜토리얼 29편: HTTP 요청과 REST API

요약#

핵심 요지#

문제 정의: 대부분의 앱은 서버에서 데이터를 가져오거나 보내야 한다. HTTP 통신 방법을 모르면 앱을 만들 수 없다.
핵심 주장: http 패키지와 FutureBuilder를 조합하면 서버 통신을 선언적으로 처리할 수 있다.
주요 근거: Flutter 공식 권장 패턴으로, 비동기 데이터를 UI에 자연스럽게 연결한다.
실무 기준: GET, POST, PUT, DELETE 요청과 에러 처리, JSON 파싱을 모두 다룬다.
한계: 인터셉터나 캐싱이 필요하면 Dio 같은 고급 패키지를 고려해야 한다.

문서가 설명하는 범위#

http 패키지 설치와 기본 사용법
GET 요청으로 데이터 가져오기
JSON을 Dart 객체로 변환하기
FutureBuilder로 비동기 데이터 표시하기
POST 요청으로 데이터 보내기
에러 처리와 로딩 상태 관리

읽는 시간: 15분 | 난이도: 초급~중급

참고 자료#

Fetch data from the internet - 공식 네트워킹 가이드
http package - 공식 HTTP 패키지
JSON and serialization - JSON 직렬화 가이드
Send data to the internet - 데이터 전송 가이드

문제 상황#

앱을 만들다 보면 서버에서 데이터를 가져와야 합니다. 사용자 정보, 상품 목록, 뉴스 피드… 대부분의 데이터는 서버에 있습니다.

서버 통신이 필요한 상황#

1
상황 1: 뉴스 앱에서 최신 기사 목록을 가져온다
2
상황 2: 쇼핑 앱에서 상품 정보를 가져온다
3
상황 3: SNS 앱에서 새 게시물을 서버에 저장한다
4
상황 4: 로그인 후 사용자 프로필을 가져온다

문제는 다음과 같습니다.

네트워크 요청은 비동기¹로 처리해야 한다.
서버 응답은 보통 JSON 형식²이다.
네트워크 오류나 서버 에러를 처리해야 한다.
로딩 중에는 사용자에게 피드백을 줘야 한다.

이 모든 걸 직접 구현하면 복잡해집니다. 다행히 Flutter는 이를 쉽게 해결할 수 있는 도구를 제공합니다.

해결 방법#

http 패키지로 서버와 통신하고, FutureBuilder로 결과를 화면에 표시합니다. 데이터 흐름은 다음과 같습니다.

graph LR A[HTTP 요청] --> B[서버 응답] B --> C[JSON 파싱] C --> D[Dart 객체] D --> E[FutureBuilder] E --> F[화면 표시]

챕터 1: http 패키지 설정하기#

Why#

NOTE
Flutter에서 HTTP 요청을 보내려면 별도 패키지가 필요합니다. http 패키지는 Flutter 팀이 만든 공식 패키지입니다.

간단하고 직관적인 API

GET, POST, PUT, DELETE 모두 지원

대부분의 앱에 충분한 기능

복잡한 기능(인터셉터, 캐싱)이 필요하면 Dio를 고려하세요. 하지만 처음 배울 때는 http가 가장 좋습니다.

What#

NOTE
http 패키지를 설치하고 임포트합니다.
pubspec.yaml
1
dependencies:
2
  http: ^1.2.0
1
import 'package:http/http.dart' as http;
2
import 'dart:convert';  // JSON 파싱용
as http는 패키지에 별명을 붙입니다. http.get(), http.post() 처럼 명확하게 사용할 수 있습니다.

How#

TIP
터미널에서 패키지를 설치합니다.
Terminal window
1
flutter pub add http
설치 후 앱을 다시 실행하세요. 핫 리로드로는 새 패키지가 적용되지 않습니다.
Android 설정: 인터넷 권한이 기본으로 활성화되어 있습니다. iOS 설정: HTTP(비암호화) 통신이 필요하면 Info.plist를 수정해야 합니다. 대부분의 API는 HTTPS를 사용하므로 추가 설정이 필요 없습니다.

Watch out#

WARNING
패키지 버전 확인: pub.dev에서 최신 버전을 확인하세요. 네트워크 권한: 에뮬레이터에서는 잘 되는데 실기기에서 안 되면 권한 문제입니다. HTTPS 필수: iOS는 기본적으로 HTTP 통신을 차단합니다. 테스트용 로컬 서버라면 Info.plist에 예외를 추가해야 합니다.

챕터 2: GET 요청으로 데이터 가져오기#

Why#

NOTE
GET 요청은 서버에서 데이터를 읽어오는 요청입니다. 가장 많이 사용하는 HTTP 메서드입니다.

상품 목록 가져오기

사용자 프로필 조회

검색 결과 받기

GET 요청에는 본문(body)이 없습니다. 필요한 정보는 URL에 포함시킵니다.

What#

NOTE
http.get()으로 서버에 요청을 보내고 응답을 받습니다.
1
Future<Album> fetchAlbum() async {
2
  // 1. 서버에 GET 요청 보내기
3
  final response = await http.get(
4
    Uri.parse('https://jsonplaceholder.typicode.com/albums/1'),
5
  );
6

7
  // 2. 응답 상태 코드 확인
8
  if (response.statusCode == 200) {
9
    // 성공: JSON을 Dart 객체로 변환
10
    return Album.fromJson(
11
      jsonDecode(response.body) as Map<String, dynamic>,
12
    );
13
  } else {
14
    // 실패: 에러 던지기
15
    throw Exception('앨범을 불러오지 못했습니다');
16
  }
17
}
핵심 포인트:

await: 응답이 올 때까지 기다린다

response.statusCode: HTTP 상태 코드 (200은 성공)

response.body: 응답 본문 (JSON 문자열)

jsonDecode(): JSON 문자열을 Map으로 변환

How#

TIP

전체 예제를 살펴봅시다.

1단계: 데이터 모델 만들기

1
class Album {
2
  final int userId;
3
  final int id;
4
  final String title;
5

6
  const Album({
7
    required this.userId,
8
    required this.id,
9
    required this.title,
10
  });
11

12
  // JSON → Dart 객체
13
  factory Album.fromJson(Map<String, dynamic> json) {
14
    return Album(
15
      userId: json['userId'] as int,
16
      id: json['id'] as int,
17
      title: json['title'] as String,
18
    );
19
  }
20
}

2단계: HTTP 요청 함수 만들기

1
Future<Album> fetchAlbum() async {
2
  final response = await http.get(
3
    Uri.parse('https://jsonplaceholder.typicode.com/albums/1'),
4
  );
5

6
  if (response.statusCode == 200) {
7
    return Album.fromJson(jsonDecode(response.body));
8
  } else {
9
    throw Exception('앨범 로딩 실패');
10
  }
11
}

3단계: 위젯에서 호출하기

1
class _MyAppState extends State<MyApp> {
2
  late Future<Album> futureAlbum;
3

4
  @override
5
  void initState() {
6
    super.initState();
7
    futureAlbum = fetchAlbum();  // 딱 한 번만 호출
8
  }
9

10
  @override
11
  Widget build(BuildContext context) {
12
    return FutureBuilder<Album>(
13
      future: futureAlbum,
14
      builder: (context, snapshot) {
15
        if (snapshot.hasData) {
16
          return Text(snapshot.data!.title);
17
        } else if (snapshot.hasError) {
18
          return Text('에러: ${snapshot.error}');
19
        }
20
        return CircularProgressIndicator();
21
      },
22
    );
23
  }
24
}

initState에서 호출하는 이유: build에서 호출하면 리빌드될 때마다 요청이 반복됩니다.

Watch out#

WARNING
흔한 실수 1: build 메서드에서 fetchAlbum() 호출
1
// 잘못된 코드
2
Widget build(BuildContext context) {
3
  return FutureBuilder<Album>(
4
    future: fetchAlbum(),  // 매번 새로 호출됨!
5
    builder: ...
6
  );
7
}
이러면 화면이 리빌드될 때마다 서버에 요청합니다. 반드시 initState에서 Future를 저장해두세요.
흔한 실수 2: 상태 코드 무시
1
// 위험한 코드
2
final response = await http.get(url);
3
return Album.fromJson(jsonDecode(response.body));  // 에러여도 파싱 시도
서버가 에러를 반환해도 파싱을 시도하면 앱이 죽습니다. 항상 statusCode를 확인하세요.

챕터 3: FutureBuilder로 화면 구성하기#

Why#

NOTE
HTTP 요청은 비동기입니다. 결과가 올 때까지 화면에 뭘 보여줄지 정해야 합니다.
FutureBuilder는 Future의 상태에 따라 다른 위젯을 보여줍니다.

대기 중: 로딩 스피너

완료: 데이터 표시

에러: 에러 메시지

이게 Flutter의 선언적 UI³ 패턴입니다.

What#

NOTE
FutureBuilder는 세 가지 상태를 처리합니다.
1
FutureBuilder<Album>(
2
  future: futureAlbum,
3
  builder: (context, snapshot) {
4
    // 1. 데이터가 있으면
5
    if (snapshot.hasData) {
6
      return Text(snapshot.data!.title);
7
    }
8

9
    // 2. 에러가 있으면
10
    if (snapshot.hasError) {
11
      return Text('에러: ${snapshot.error}');
12
    }
13

14
    // 3. 아직 기다리는 중이면
15
    return CircularProgressIndicator();
16
  },
17
);
snapshot의 주요 속성:

hasData: 데이터가 있는지

hasError: 에러가 발생했는지

data: 실제 데이터 (null일 수 있음)

error: 에러 객체

connectionState: 연결 상태

How#

TIP

더 세밀한 상태 관리가 필요하면 connectionState를 사용합니다.

1
FutureBuilder<Album>(
2
  future: futureAlbum,
3
  builder: (context, snapshot) {
4
    switch (snapshot.connectionState) {
5
      case ConnectionState.none:
6
        return Text('요청 전');
7
      case ConnectionState.waiting:
8
        return Column(
9
          mainAxisAlignment: MainAxisAlignment.center,
10
          children: [
11
            CircularProgressIndicator(),
12
            SizedBox(height: 16),
13
            Text('데이터를 불러오는 중...'),
14
          ],
15
        );
16
      case ConnectionState.done:
17
        if (snapshot.hasError) {
18
          return Column(
19
            mainAxisAlignment: MainAxisAlignment.center,
20
            children: [
21
              Icon(Icons.error, color: Colors.red, size: 48),
22
              SizedBox(height: 16),
23
              Text('오류가 발생했습니다'),
24
              TextButton(
25
                onPressed: () {
26
                  setState(() {
27
                    futureAlbum = fetchAlbum();  // 재시도
28
                  });
29
                },
30
                child: Text('다시 시도'),
31
              ),
32
            ],
33
          );
34
        }
35
        return Text(snapshot.data!.title);
36
      default:
37
        return SizedBox.shrink();
38
    }
39
  },
40
);

에러 상태에서 “다시 시도” 버튼을 제공하면 사용자 경험이 좋아집니다.

Watch out#

WARNING
snapshot.data 사용 시 주의:
1
// 위험: data가 null일 수 있음
2
Text(snapshot.data!.title);
3

4
// 안전: null 체크 후 사용
5
if (snapshot.hasData) {
6
  Text(snapshot.data!.title);
7
}
hasData가 true여도 타입 시스템은 모릅니다. ! 연산자로 null이 아님을 알려주거나, null 체크를 하세요.
initial data 활용: 캐시된 데이터가 있으면 initialData로 넘길 수 있습니다.
1
FutureBuilder<Album>(
2
  future: futureAlbum,
3
  initialData: cachedAlbum,  // 로딩 중에도 이전 데이터 표시
4
  builder: ...
5
);

챕터 4: POST 요청으로 데이터 보내기#

Why#

NOTE
POST 요청은 서버에 데이터를 보내는 요청입니다. 새로운 리소스를 생성할 때 사용합니다.

회원가입 정보 전송

새 게시물 작성

주문 생성

GET과 달리 요청 본문(body)에 데이터를 담습니다.

What#

NOTE

http.post()로 데이터를 서버에 보냅니다.

1
Future<Album> createAlbum(String title) async {
2
  final response = await http.post(
3
    Uri.parse('https://jsonplaceholder.typicode.com/albums'),
4
    headers: <String, String>{
5
      'Content-Type': 'application/json; charset=UTF-8',
6
    },
7
    body: jsonEncode(<String, String>{
8
      'title': title,
9
    }),
10
  );
11

12
  if (response.statusCode == 201) {  // 201: Created
13
    return Album.fromJson(jsonDecode(response.body));
14
  } else {
15
    throw Exception('앨범 생성 실패');
16
  }
17
}

핵심 포인트:

headers: 콘텐츠 타입 지정 (JSON임을 알림)
body: 보낼 데이터 (JSON 문자열로 변환)
jsonEncode(): Map을 JSON 문자열로 변환
상태 코드 201은 “생성 성공”을 의미

How#

TIP

POST 요청을 UI와 연결하는 전체 예제입니다.

1
class CreateAlbumScreen extends StatefulWidget {
2
  @override
3
  _CreateAlbumScreenState createState() => _CreateAlbumScreenState();
4
}
5

6
class _CreateAlbumScreenState extends State<CreateAlbumScreen> {
7
  final TextEditingController _controller = TextEditingController();
8
  Future<Album>? _futureAlbum;
9

10
  @override
11
  Widget build(BuildContext context) {
12
    return Column(
13
      children: [
14
        TextField(
15
          controller: _controller,
16
          decoration: InputDecoration(
17
            labelText: '앨범 제목',
18
          ),
19
        ),
20
        ElevatedButton(
21
          onPressed: () {
22
            setState(() {
23
              _futureAlbum = createAlbum(_controller.text);
24
            });
25
          },
26
          child: Text('생성'),
27
        ),
28

29
        // 결과 표시
30
        if (_futureAlbum != null)
31
          FutureBuilder<Album>(
32
            future: _futureAlbum,
33
            builder: (context, snapshot) {
34
              if (snapshot.hasData) {
35
                return Text('생성됨: ${snapshot.data!.title}');
36
              } else if (snapshot.hasError) {
37
                return Text('에러: ${snapshot.error}');
38
              }
39
              return CircularProgressIndicator();
40
            },
41
          ),
42
      ],
43
    );
44
  }
45
}

버튼을 누르면 POST 요청이 발생하고, 결과가 화면에 표시됩니다.

Watch out#

WARNING
Content-Type 헤더 필수: 헤더 없이 보내면 서버가 JSON을 인식 못 합니다.
1
// 잘못된 코드
2
await http.post(url, body: jsonEncode(data));  // 헤더 없음
3

4
// 올바른 코드
5
await http.post(
6
  url,
7
  headers: {'Content-Type': 'application/json; charset=UTF-8'},
8
  body: jsonEncode(data),
9
);
상태 코드 주의: POST 성공은 보통 201(Created)입니다. 서버마다 다를 수 있으니 API 문서를 확인하세요.
중복 요청 방지: 버튼을 빠르게 연타하면 요청이 여러 번 갑니다. 로딩 중에는 버튼을 비활성화하세요.

챕터 5: 데이터 모델 설계하기#

Why#

NOTE
서버 응답(JSON)을 그대로 사용하면 문제가 많습니다.

타입 안전성이 없다 (json['title']이 String인지 모름)

오타를 컴파일러가 잡지 못한다

자동완성이 안 된다

Dart 클래스로 변환하면 이 문제가 해결됩니다. 이를 역직렬화(deserialization)라고 합니다.

What#

NOTE

JSON을 Dart 객체로 변환하는 클래스를 만듭니다.

1
class Album {
2
  final int userId;
3
  final int id;
4
  final String title;
5

6
  const Album({
7
    required this.userId,
8
    required this.id,
9
    required this.title,
10
  });
11

12
  // JSON → Dart 객체 (역직렬화)
13
  factory Album.fromJson(Map<String, dynamic> json) {
14
    return Album(
15
      userId: json['userId'] as int,
16
      id: json['id'] as int,
17
      title: json['title'] as String,
18
    );
19
  }
20

21
  // Dart 객체 → JSON (직렬화)
22
  Map<String, dynamic> toJson() {
23
    return {
24
      'userId': userId,
25
      'id': id,
26
      'title': title,
27
    };
28
  }
29
}

fromJson: 서버에서 받은 데이터를 객체로 변환 toJson: 객체를 서버에 보낼 JSON으로 변환

How#

TIP

목록 데이터를 파싱하는 방법입니다.

1
// 서버 응답: [{"id": 1, "title": "..."}, {"id": 2, "title": "..."}]
2

3
Future<List<Album>> fetchAlbums() async {
4
  final response = await http.get(
5
    Uri.parse('https://jsonplaceholder.typicode.com/albums'),
6
  );
7

8
  if (response.statusCode == 200) {
9
    // JSON 배열을 List<Album>으로 변환
10
    final List<dynamic> jsonList = jsonDecode(response.body);
11
    return jsonList
12
        .map((json) => Album.fromJson(json))
13
        .toList();
14
  } else {
15
    throw Exception('앨범 목록 로딩 실패');
16
  }
17
}

중첩된 JSON 처리:

1
// 서버 응답: {"user": {"name": "John", "email": "..."}}
2
class Response {
3
  final User user;
4

5
  factory Response.fromJson(Map<String, dynamic> json) {
6
    return Response(
7
      user: User.fromJson(json['user']),  // 중첩 객체 파싱
8
    );
9
  }
10
}

Watch out#

WARNING
null 처리: 서버가 null을 보낼 수 있습니다.
1
// 위험: null이면 에러
2
title: json['title'] as String,
3

4
// 안전: 기본값 제공
5
title: json['title'] as String? ?? '제목 없음',
타입 캐스팅 주의: JSON 숫자가 int인지 double인지 확인하세요.
1
// 서버가 1.0을 보내면 실패
2
id: json['id'] as int,
3

4
// 안전: num으로 받아서 변환
5
id: (json['id'] as num).toInt(),
코드 생성 도구: 모델이 많아지면 json_serializable 패키지를 고려하세요. 반복적인 fromJson/toJson 코드를 자동 생성해줍니다.

챕터 6: 에러 처리 패턴#

Why#

NOTE
네트워크 요청은 실패할 수 있습니다.

인터넷 연결 끊김

서버 점검 중

타임아웃

잘못된 요청

이런 상황에 앱이 죽으면 안 됩니다. 사용자에게 적절한 피드백을 줘야 합니다.

What#

NOTE

try-catch로 에러를 잡고 적절히 처리합니다.

1
Future<Album> fetchAlbum() async {
2
  try {
3
    final response = await http.get(
4
      Uri.parse('https://jsonplaceholder.typicode.com/albums/1'),
5
    ).timeout(Duration(seconds: 10));  // 타임아웃 설정
6

7
    if (response.statusCode == 200) {
8
      return Album.fromJson(jsonDecode(response.body));
9
    } else if (response.statusCode == 404) {
10
      throw NotFoundException('앨범을 찾을 수 없습니다');
11
    } else if (response.statusCode >= 500) {
12
      throw ServerException('서버에 문제가 발생했습니다');
13
    } else {
14
      throw Exception('알 수 없는 오류: ${response.statusCode}');
15
    }
16
  } on SocketException {
17
    throw NetworkException('인터넷 연결을 확인하세요');
18
  } on TimeoutException {
19
    throw NetworkException('서버 응답이 너무 느립니다');
20
  } on FormatException {
21
    throw DataException('데이터 형식이 올바르지 않습니다');
22
  }
23
}

커스텀 예외 클래스를 만들면 에러 종류를 구분할 수 있습니다.

How#

TIP

예외 클래스를 정의하고 UI에서 활용합니다.

1
// 커스텀 예외 정의
2
class NetworkException implements Exception {
3
  final String message;
4
  NetworkException(this.message);
5
}
6

7
class ServerException implements Exception {
8
  final String message;
9
  ServerException(this.message);
10
}
11

12
// UI에서 에러 타입별 처리
13
FutureBuilder<Album>(
14
  future: futureAlbum,
15
  builder: (context, snapshot) {
16
    if (snapshot.hasError) {
17
      final error = snapshot.error;
18

19
      if (error is NetworkException) {
20
        return Column(
21
          children: [
22
            Icon(Icons.wifi_off, size: 48),
23
            Text(error.message),
24
            ElevatedButton(
25
              onPressed: _retry,
26
              child: Text('다시 시도'),
27
            ),
28
          ],
29
        );
30
      }
31

32
      if (error is ServerException) {
33
        return Column(
34
          children: [
35
            Icon(Icons.cloud_off, size: 48),
36
            Text(error.message),
37
          ],
38
        );
39
      }
40

41
      return Text('오류: $error');
42
    }
43
    // ...
44
  },
45
);

에러 타입에 따라 다른 UI를 보여주면 사용자가 상황을 이해하기 쉽습니다.

Watch out#

WARNING
모든 예외를 catch하지 마세요:
1
// 나쁜 패턴: 모든 에러 무시
2
try {
3
  return await fetchData();
4
} catch (e) {
5
  return null;  // 문제가 뭔지 알 수 없음
6
}
예외를 삼키면 디버깅이 어려워집니다. 최소한 로그는 남기세요.
사용자 친화적 메시지: 기술적인 에러 메시지를 그대로 보여주지 마세요.
1
// 나쁨: "SocketException: Connection refused"
2
// 좋음: "인터넷 연결을 확인하세요"

한계#

이 튜토리얼에서 다룬 http 패키지는 기본적인 HTTP 통신에 적합합니다. 다음과 같은 고급 기능이 필요하면 다른 도구를 고려하세요.

http 패키지의 한계:

기능	http	Dio
기본 HTTP 요청	O	O
인터셉터	X	O
요청 취소	X	O
파일 업로드 진행률	X	O
자동 재시도	X	O
캐싱	X	O

대안 패키지:

Dio: 인터셉터, 요청 취소, FormData 등 고급 기능
Retrofit: 타입 안전한 API 클라이언트 (코드 생성)
Chopper: Retrofit과 유사, Dart 친화적

다음 튜토리얼에서 실제 CRUD 작업을 구현하며 이 개념들을 활용합니다.

비동기(Asynchronous): 작업이 완료될 때까지 기다리지 않고 다음 코드를 실행하는 방식. 네트워크 요청은 시간이 걸리므로 비동기로 처리해야 앱이 멈추지 않습니다. ↩
JSON(JavaScript Object Notation): 데이터를 주고받는 표준 형식. {"key": "value"} 형태로, 사람이 읽기 쉽고 대부분의 언어에서 파싱할 수 있습니다. ↩
선언적 UI(Declarative UI): “어떻게 변경할지”가 아니라 “무엇을 보여줄지”를 선언하는 방식. 상태가 바뀌면 Flutter가 알아서 UI를 업데이트합니다. ↩

Flutter 튜토리얼 29편: HTTP 요청과 REST API

요약#

핵심 요지#

문서가 설명하는 범위#

참고 자료#

문제 상황#

서버 통신이 필요한 상황#

해결 방법#

챕터 1: http 패키지 설정하기#

Why#

What#

How#

Watch out#

챕터 2: GET 요청으로 데이터 가져오기#

Why#

What#

How#

Watch out#

챕터 3: FutureBuilder로 화면 구성하기#

Why#

What#

How#

Watch out#

챕터 4: POST 요청으로 데이터 보내기#

Why#

What#

How#

Watch out#

챕터 5: 데이터 모델 설계하기#

Why#

What#

How#

Watch out#

챕터 6: 에러 처리 패턴#

Why#

What#

How#

Watch out#

한계#

Footnotes#

공유

목차