이 문서는 Flutter 학습 문서를 카테고리별로 정리하기 위한 번호 체계를 정의합니다.  

번호는 0000, 0100, 0200처럼 네 자리 숫자로 구분되며,   README 정렬 및 검색 편의를 위해 사용됩니다.

Flutter에서 화면을 구성하는 모든 UI 요소는 위젯으로 표현되며, UI 외에도 입력, 애니메이션, 접근성, 비동기 처리 등 다양한 범위의 위젯들이 존재합니다.
이 영역은 Flutter 공식 Widget Catalog 분류 체계를 참고하여 실전에서 많이 사용하는 항목을 중심으로 정리합니다.

Flutter의 화면 전환, 내비게이션 흐름을 담당하는 기능을 별도 카테고리로 분리하여 관리합니다.
기본 내비게이션 API부터 고급 라우팅 패키지(go_router 등)까지 포함합니다.

Flutter 앱에서 디바이스(OS 기반) 기능 및 외부 SDK/API를 연동하는 모든 기능을 포함하며, 내부 기능과 외부 연동을 번호로 구분합니다.

• 파일명은 Flutter_번호_제목.md 형식으로 작성
• 제목은 명확하고 구체적으로 작성 (예: Flutter_100_ListView.md)
• 각 파일은 해당 카테고리 폴더에 들어있지 않아도 번호로 정렬됨

• Flutter_0000_Document_Guide.md
• Flutter_0050_Dart_Syntax_Basics.md
• Flutter_0100_Basic_Widget.md
• Flutter_0200_HTTP_Request.md
• Flutter_0300_Provider_Usage.md
• Flutter_0400_Navigator_Example.md
• Flutter_8100_WebView_PlatformNotSet.md
• Flutter_8110_WebView_NDKVersionMismatch.md
• Flutter_9999_Sandbox.md

트러블슈팅 문서는 다음 항목 구조로 작성합니다:

이 가이드는 Flutter 문서 관리와 확장을 체계적으로 유지하기 위해 가장 앞에 위치합니다。

기초 (입문 · 핵심 개념)

• Flutter_2000.Networking.Basics.md → 네트워크 기초
• Flutter_2001.Async.Overview.md → 비동기 개념 지도(Future/Stream/Isolate, 언제 무엇을 쓰나)
• Flutter_2001.1.Future.AsyncAwait.Basics.md → Future 기본, async/await 규칙, 반환 타입 정리
• Flutter_2002.Dio.Basics.md → Dio 기본
• Flutter_2003.Future.ThenVsAwait.md → then 체인 vs async/await 비교, 가독성/예외처리 차이
• Flutter_2004.Async.ErrorHandling.md → try/on/catch/finally, StackTrace, rethrow 패턴

응용 (패턴 · 실전 코드)

• Flutter_2004_Sequential_vs_Parallel.md — 순차(await) vs 병렬(Future.wait), 성능/주의점
• Flutter_2005_Stream_Basics.md — 단발성(Future) vs 다발성(Stream), await for, listen
• Flutter_2006_StreamController_Broadcast.md — StreamController, 단일/브로드캐스트, 변환(map, where)
• Flutter_2007_FutureBuilder_Recipes.md — FutureBuilder 상태 설계(로딩/성공/실패), 실수 패턴 교정
• Flutter_2008_StreamBuilder_Recipes.md — StreamBuilder 지속 업데이트 UI, 구독/해제 주의점
• Flutter_2009_EventLoop_Microtask.md — 이벤트 루프, microtask vs event queue, scheduleMicrotask

고급 (성능 · 구조 · 테스트)

• Flutter_2010_Timeout_Cancel_Retry.md — timeout, 취소 토큰(대안), 재시도(backoff) 패턴
• Flutter_2011_Async_in_Widget_Lifecycle.md — initState/dispose에서의 비동기, 메모리릭·race 방지
• Flutter_2012_Isolates_and_compute.md — Isolate/compute로 메인 스레드 블로킹 방지
• Flutter_2013_Async_Performance_Tips.md — jank 방지, 배치 처리, 디바운스/스로틀
• Flutter_2014_Testing_Async.md — 비동기 유닛/위젯 테스트, pump/pumpAndSettle, fake async

연계 (네트워크/상태관리)

• Flutter_2015_Dio_with_Async_Patterns.md — Dio + async 베스트 프랙티스(Interceptor/에러모델)
• Flutter_2016_Result_Either_ErrorModel.md — 성공/실패 타입 모델링(Result/Either) + UI 연동
• Flutter_2017_Async_with_Provider_Riverpod.md — FutureProvider/StreamProvider, cancel-safe 설계
• Flutter_2018_Async_File_IO.md — 파일 읽기/쓰기 비동기 패턴, isolate로 파싱 오프로딩
• Flutter_2019_Concurrency_Race_Conditions.md — 중복 클릭·중복 요청, 최신만 반영 패턴(switchMap 유사)

⸻

보조 링크(카탈로그 교차참조)

• 1011 Async 위젯과 상호 링크: FutureBuilder, StreamBuilder 문서는 1000번대(위젯 카탈로그)에도 요약 카드로 두고, 자세한 내용은 2007/2008로 점프하도록 앵커 연결.

체크박스 상태: [ ] 예정 [~] 작성 중 [x] 완료

• Flutter_2000.Networking.Basics.md

  • 목표: HTTP/REST 개념, http/Dio 개요, JSON 구조(Map/List) 분기 이해
  • 키워드: REST, HTTP 메서드, JSON, http 패키지
  • 예상소요: 40m
  • 선행지식: Dart 기본, 비동기 기초(Future 개념)
  • 실습(필수): JSON 객체/리스트 응답 각각 파싱, 상태코드 분기 처리
  • 실습(심화): 모델 fromJson/toJson 작성 후 리스트 매핑
  • 링크: 2002 Dio Basics ↔ 3000 JSON 파싱, 2007 FutureBuilder

• Flutter_2001.Async.Overview.md

  • 목표: Future/Stream/Isolate 개념 지도와 선택 기준 확립
  • 키워드: 단발성/다발성, 메인스레드, 오프로딩
  • 예상소요: 30m
  • 실습(필수): Future.delayed(300ms) → "hello" 로그
  • 실습(심화): Stream.periodic 5회 카운트 → 콘솔
  • 링크: 2001.1 Async/Await Basics, 2005 Stream Basics(예고)

• Flutter_2001.1.Future.AsyncAwait.Basics.md

  • 목표: async/await 규칙, Future<T> 반환/호출 패턴 이해
  • 키워드: async 필요조건, await/then 비교, 불필요한 await
  • 예상소요: 40m
  • 실습(필수): Future<int> 500ms 뒤 42 리턴 → 버튼 클릭 출력
  • 실습(심화): try/catch로 실패 흐름 가짜 처리
  • 링크: 2007 FutureBuilder, 2003 ThenVsAwait

• Flutter_2002.Dio.Basics.md

  • 목표: Dio 기본 사용(GET/POST), BaseOptions, LogInterceptor, 커스텀 Interceptor, 싱글턴
  • 키워드: Dio, BaseOptions, InterceptorsWrapper, LogInterceptor, Singleton
  • 예상소요: 60m
  • 실습(필수): GET /images/search 1·5건 호출 후 URL 추출
  • 실습(심화): ApiClient 싱글턴으로 공통 헤더·타임아웃 구성, 로그 커스터마이즈
  • 링크: 2015 Dio with Async Patterns, 2007 FutureBuilder

• Flutter_2003.Future.ThenVsAwait.md

  • 목표: then 체인 vs await 가독성/예외 처리 비교
  • 키워드: 콜백 체인, catchError, 가독성
  • 예상소요: 25m
  • 실습(필수): 동일 기능을 then/await 2버전으로 작성, 로그 순서 비교
  • 실습(심화): 에러 발생 시 두 방식의 스택트레이스 차이 캡처

• Flutter_2004.Async.ErrorHandling.md

  • 목표: try/on/catch/finally, rethrow, StackTrace
  • 키워드: 도메인에러→UI메시지 매핑
  • 예상소요: 35m
  • 실습(필수): risky()에서 Exception 던지고 UI에 안전 표시
  • 실습(심화): finally에서 로딩 off 보장하는 미니 헬퍼

• Flutter_2004_Sequential_vs_Parallel.md

  • 목표: 순차(await 체인) vs 병렬(Future.wait) 체감
  • 벤치마크: DateTime.now()로 총 소요 로그
  • 실습(필수): 500ms/700ms 작업 순차 vs 병렬 시간 비교
  • 실습(심화): 일부 실패 시 부분성공 전략(성공만 필터)

• Flutter_2005_Stream_Basics.md

  • 목표: Future↔Stream 차이, await for, listen
  • 실습(필수): 300ms 간격 카운터 1..5 await for 출력
  • 실습(심화): listen으로 구독 시작/해제 버튼

• Flutter_2006_StreamController_Broadcast.md

  • 목표: 단일 vs broadcast, 변환(map, where)
  • 실습(필수): Controller → 두 위젯 동시 구독
  • 실습(심화): where로 짝수만 UI 반영

• Flutter_2007_FutureBuilder_Recipes.md

  • 목표: 로딩/성공/실패 3상태 안전 패턴
  • 안티패턴: future 재생성, 빌드 내 무한 재호출 방지
  • 실습(필수): 성공/실패 토글되는 목 API로 카드 UI

• Flutter_2008_StreamBuilder_Recipes.md

  • 목표: 실시간 업데이트/구독수명 관리
  • 실습(필수): 타이머 스트림 + 일시정지/재개
  • 주의: dispose에서 구독 해제

• Flutter_2009_EventLoop_Microtask.md

  • 목표: event queue vs microtask, scheduleMicrotask
  • 실습(필수): print 순서 실험(then vs scheduleMicrotask)

• Flutter_2010_Timeout_Cancel_Retry.md

  • 목표: timeout, 취소(대안), 지수 백오프
  • 실습(필수): Future.any/타임아웃 가드

• Flutter_2011_Async_in_Widget_Lifecycle.md

  • 목표: initState/dispose 중 비동기 안전처리
  • 실습(필수): mounted 체크, late cancel 패턴

• Flutter_2012_Isolates_and_compute.md

  • 목표: compute/Isolate로 무거운 파싱 오프로딩
  • 벤치마크: 메인 프레임 드랍 vs 오프로딩 비교

• Flutter_2013_Async_Performance_Tips.md

  • 목표: jank 방지, 디바운스/스로틀/배치
  • 실습(필수): 입력 디바운스 검색 리스트

• Flutter_2014_Testing_Async.md

  • 목표: fakeAsync, pump/pumpAndSettle
  • 실습(필수): FutureBuilder 위젯테스트

• Flutter_2015_Dio_with_Async_Patterns.md

  • 목표: Interceptor, 공통 에러모델, 재시도
  • 실습(필수): 성공/실패/타임아웃 3케이스 UI 바인딩

• Flutter_2016_Result_Either_ErrorModel.md

  • 목표: 성공/실패 타입(Result/Either)로 UI 단순화
  • 실습(필수): when(success:..., failure:...) 렌더

• Flutter_2017_Async_with_Provider_Riverpod.md

  • 목표: FutureProvider/StreamProvider, cancel-safe
  • 실습(필수): 탭 전환 중 중복요청 차단

• Flutter_2018_Async_File_IO.md

  • 목표: 파일 IO 비동기 + isolate 파싱
  • 실습(필수): 대용량 JSON 파싱 오프로딩

• Flutter_2019_Concurrency_Race_Conditions.md

  • 목표: 최신값만 반영(switchLatest 유사), 중복 클릭 방지
  • 실습(필수): 빠른 연타에도 마지막 요청만 UI 반영

읽어야할 자료를 모았습니다.
Flutter Docs 순서 그대로 가져왔습니다.

• 1. Get started
  • 1.1. Set up Flutter
  • 1.2. Install Flutter
    • Overview
    • Install manually
    • upgrade SDK
  • 1.3. Learn Flutter
    • 1.3.1. Introduction
    • 1.3.2. Write your first app
    • 1.3.3. Learn the fundamentals
      • 1.3.3.1. Introduction
      • 1.3.3.2. Intro to Dart
      • 1.3.3.3. Widgets
      • 1.3.3.4. Layout
      • 1.3.3.5. State management
      • 1.3.3.6. Handling user input
      • 1.3.3.7. Networking and data
      • 1.3.3.8. Local data and caching
• 2. User interface

  • 2.1. Introduction

  • 2.2. Widget catalog

    • 2.2.1. Basics 가장 기초적인 위젯 구성 요소들
    • 2.2.2. Layout 레이아웃 구성용 위젯
    • 2.2.3. Text 텍스트 표시 및 스타일링 관련 위젯
    • 2.2.4. Input 사용자 입력을 위한 위젯
    • 2.2.5. Assets, Images and Icons 이미지, 아이콘, 에셋 관련 구성 요소
    • 2.2.6. Scrolling 스크롤 가능한 콘텐츠를 구성하는 위젯
    • 2.2.7. Interaction Models 제스처 및 터치 반응 처리 위젯
    • 2.2.8. Styling 테마, 반응형 구성, 패딩 등 스타일링 위젯
    • 2.2.9. Painting and Effects 시각적 효과 및 그리기 관련 위젯
    • 2.2.10. Animation and Motion 애니메이션 효과와 트랜지션 처리
    • 2.2.11. Async 비동기 상태를 다루기 위한 위젯
    • 2.2.12. Accessibility 앱의 접근성을 향상시키는 도구 제공

  • 2.3. Layout

    • 2.3.1. Introduction
    • 2.3.2. Build a layout
    • 2.3.3. List & Grid
      • 2.3.3.1. Create and use lists
      • 2.3.3.2. Create a horizontal list
      • 2.3.3.3. Create a grid view
      • 2.3.3.4. Create a lists with different types of items
      • 2.3.3.5. Create lists with spaced items
      • 2.3.3.6. Work with long lists
    • 2.3.4. Scrolling
      • 2.3.4.1. Overview
      • 2.3.4.2. Use slivers to achieve fancy scrolling
      • 2.3.4.3. Place a floating app bar above a list
      • 2.3.4.4. Create a scrolling parallax effect

  • 2.4. Adaptive & responsive design

    • 2.4.1. Overview
    • 2.4.2. General approach
    • 2.4.3. SafeArea & MediaQuery
    • 2.4.4. Large screens & foldables
    • 2.4.5. User input & accessibility
    • 2.4.6. Capabilities & policies
    • 2.4.7. Automatic platform adaptations
    • 2.4.8. Best practices
    • 2.4.9. Additional resources

  • 2.5. Design & theming

    • 2.5.1. Share styles with themes
    • 2.5.2. Material design
    • 2.5.3. Migrate to Material 3
    • 2.5.4. Text
      • 2.5.4.1. Fonts & typography
      • 2.5.4.2. Use a custom font
      • 2.5.4.3. Export fonts from a package
      • 2.5.4.4. Google Fonts package
    • 2.5.5. Custom graphics
      • 2.5.5.1. Use custom fragment shaders

  • 2.6. Interactivity

    • 2.6.1. Add interactivity to your app
    • 2.6.2. Gestures
      • 2.6.2.1. Introduction
      • 2.6.2.2. Handle taps
      • 2.6.2.3. Drag an object outside an app
      • 2.6.2.4. Drag a Ul element within an app
      • 2.6.2.5. Add Material touch ripples
      • 2.6.2.6. Implement swipe to dismiss
    • 2.6.3. Input & forms
      • 2.6.3.1. Create and style a text field
      • 2.6.3.2. Retrieve the value of a text field
      • 2.6.3.3. Handle changes to a text field
      • 2.6.3.4. Manage focus in text fields Build a form with validation
    • 2.6.4. Display a snackbar
    • 2.6.5. Implement actions & shortcuts
    • 2.6.6. Manage keyboard focus

  • 2.7. Assets & media

    • 2.7.1. Add assets and images
    • 2.7.2. Display images fror le interne
    • 2.7.3. Fade in images with aceholde
    • 2.7.4. Play and pause a video
    • 2.7.5. Transform assets at build

  • 2.8. Navigation & routing

    • 2.8.1. Overview
    • 2.8.2. Add tabs to your app Navigate to a new screen and back
    • 2.8.3. Send data to a new screen
    • 2.8.4. Return data from a screen
    • 2.8.5. Add a drawer to a screen
    • 2.8.6. Set up deep linking
    • 2.8.7. Set up app links for Android
    • 2.8.8. Set up universal links for iOS
    • 2.8.9. Configure web URL strategies

  • 2.9. Animations & transitions

    • 2.9.1. Introduction
    • 2.9.2. Tutorial
    • 2.9.3. Implicit animations
    • 2.9.4. Animate the properties of a container
    • 2.9.5. Fade a widget in and out
    • 2.9.6. Hero animations
    • 2.9.7. Animate a page route transition
    • 2.9.8. Animate using a physics simulation
    • 2.9.9. Staggered animations
    • 2.9.10. Create a staggered menu animation
    • 2.9.11. API overview

  • 2.10. Accessibility & internationalization

    • 2.10.1. Accessibility
    • 2.10.2. Internationalization
• 3. Beyond Ul
  • 3.1. Data & backend
    • 3.1.1. State management
      • 3.1.1.1. Introduction
      • 3.1.1.2. Think declaratively
      • 3.1.1.3. Ephemeral vs app state
      • 3.1.1.4. Simple app state management
      • 3.1.1.5. Options
    • 3.1.2. Networking & http
      • 3.1.2.1. Overview
      • 3.1.2.2. Fetch data from the internet
      • 3.1.2.3. Make authenticated requests
      • 3.1.2.4. Send data to the internet
      • 3.1.2.5. update data over the internet
      • 3.1.2.6. Dele data on ther internet
      • 3.1.2.7. Communicate with WebSockets
    • 3.1.3. Serialization
      • 3.1.3.1. JSON serialization
      • 3.1.3.2. Parse JSON in the background
    • 3.1.4. Persistence
      • 3.1.4.1. Store key-value data on disk
      • 3.1.4.2. Read and write files
      • 3.1.4.3. Persist data with SQList
    • 3.1.5. Firebase
    • 3.1.6. Google APIs
  • 3.2. App architecture
    • 3.2.1. Introduction
    • 3.2.2. Architecture concepts
    • 3.2.3. Guide to app architecture
    • 3.2.4. Architecture case study
    • 3.2.5. Recommendations
    • 3.2.6. Design patterns
  • 3.3. Platform integration
  • 3.4. Packages & plugins
    • 3.4.1. Use packages & plugins
    • 3.4.2. Develop packages & plugins
    • 3.4.3. Swift Package Manager
  • 3.5. Testing & debugging
    • 3.5.1. Testing
      • 3.5.1.1. Overview
      • 3.5.1.2. Unit testing
      • 3.5.1.3. Widget testing
      • 3.5.1.4. Integration testing
      • 3.5.1.5. Test a plugin
      • 3.5.1.6. Handle plugin code in tests
    • 3.5.2. Debugging
      • 3.5.2.1. Debugging tools
      • 3.5.2.2. Debug your app programmatically
      • 3.5.2.3. Use a native
      • 3.5.2.4. language debugger
      • 3.5.2.5. Common Flutter errors
      • 3.5.2.6. Handle errors
      • 3.5.2.7. Report errors to a service
  • 3.6. Performance & optimization
    • 3.6.1. Overview
    • 3.6.2. Impeller
    • 3.6.3. Performance best practices
    • 3.6.4. App size
    • 3.6.5. Deferred components
    • 3.6.6. Rendering performance
    • 3.6.7. Performance profiling
    • 3.6.8. Performance profiling for web
    • 3.6.9. Performance metrics
    • 3.6.10. Concurrency and isolates
    • 3.6.11. Performance FAQ
    • 3.6.12. Appendix
  • 3.7. Deployment
    • 3.7.1. Obfuscate Dart code
    • 3.7.2. Create app flavors for Android
    • 3.7.3. Create app flavors for iOS and macOS
    • 3.7.4. uild and release ar indroid app
    • 3.7.5. Build and release an iOS app
    • 3.7.6. Build and release a macOS app
    • 3.7.7. Build and release a Linux app und and salese a
    • 3.7.8. Build and release a web app
    • 3.7.9. Set up continuous deployment
  • 3.8. Add to an existing app
    • 3.8.1. Introduction
    • 3.8.2. Add to an Android app
    • 3.8.3. Add to an iOS app
    • 3.8.4. Add to a web app
    • 3.8.5. Debug embedded Flutter module
    • 3.8.6. Add multiple Flutter instances
    • 3.8.7. Loading sequence and performance
• 4. Flutter concepts
  • 4.1. Architectural Overview
  • 4.2. Inside Flutter
  • 4.3. Understanding constraints
  • 4.4. Flutter’s build modes
  • 4.5. Hot reload

• 250618 : 초안작성
• 250619 : 트러블슈팅 관련 넘버링 추가
• 250702 : 리팩토링진행 - 모바일 개발 과정과 비슷하게 구성

Flutter를 처음 학습하거나 체계적으로 정리하고 싶은 사용자를 위해, 아래와 같은 단계별 로드맵과 함께 문서 번호 참고 범위를 제시합니다.