flutter-dart-code-review

name	flutter-dart-code-review
description	위젯 모범 사례, 상태 관리 패턴(BLoC, Riverpod, Provider, GetX, MobX, Signals), Dart 관용구, 성능, 접근성, 보안 및 클린 아키텍처를 아우르는 라이브러리에 독립적인 Flutter/Dart 코드 리뷰 체크리스트입니다.
origin	ECC

Flutter/Dart 코드 리뷰 모범 사례

Flutter/Dart 애플리케이션 리뷰를 위한 포괄적이고 라이브러리에 독립적인 체크리스트입니다. 이 원칙들은 어떤 상태 관리 솔루션, 라우팅 라이브러리 또는 DI 프레임워크를 사용하는지와 관계없이 적용됩니다.

---

1. 전반적인 프로젝트 건강 상태

• 프로젝트가 일관된 폴더 구조를 따르고 있는가 (기능 중심 또는 레이어 중심)
• UI, 비즈니스 로직, 데이터 레이어가 적절히 분리되어 있는가
• 위젯 내에 비즈니스 로직이 없는가 (위젯은 순수하게 표현만 담당해야 함)
• pubspec.yaml이 깨끗한가 (미사용 의존성 제거, 버전 고정 등)
• analysis_options.yaml에 엄격한 린트 규칙과 분석기 설정이 포함되어 있는가
• 프로덕션 코드에 print() 문이 없는가 (dart:developer의 log() 또는 로깅 패키지 사용)
• 생성된 파일(.g.dart, .freezed.dart, .gr.dart)이 최신 상태이거나 .gitignore에 포함되어 있는가
• 플랫폼별 코드가 추상화 뒤에 격리되어 있는가

---

2. Dart 언어의 함정

• 암시적 dynamic (Implicit dynamic): 타입 어노테이션 누락으로 인한 dynamic 발생 확인 — strict-casts, strict-inference, strict-raw-types 활성화 권장
• Null safety 오용: 적절한 null 체크나 Dart 3 패턴 매칭(if (value case var v?)) 대신 과도한 ! (bang 연산자) 사용 여부
• 타입 프로모션 실패: 로컬 변수 프로모션이 가능한 상황에서 this.field를 사용하고 있지 않은가
• 너무 넓은 예외 처리: on 절 없는 catch (e) 사용 자제; 항상 예외 타입을 명시할 것
• Error 캐치: Error의 하위 타입들은 버그를 나타내므로 캐치해서는 안 됨
• 불필요한 async: await를 한 번도 하지 않는 함수에 async 마크가 되어 있지 않은가 (불필요한 오버헤드 발생)
• late 남용: Null 허용 처리나 생성자 초기화가 더 안전한 상황에서 late를 사용하고 있지 않은가 (런타임 에러 위험)
• 루프 내 문자열 결합: 반복적인 문자열 생성 시 + 대신 StringBuffer를 사용하고 있는가
• const 컨텍스트의 가변 상태: const 생성자 클래스의 필드가 가변(mutable) 상태가 아닌가
• Future 반환 값 무시: 의도를 명확히 하기 위해 await를 사용하거나 명시적으로 unawaited()를 호출하는가
• var vs final: 로컬 변수에는 final을, 컴파일 타임 상수에는 const를 우선적으로 사용하는가
• 상대 경로 임포트: 일관성을 위해 package: 임포트를 사용하고 있는가
• 가변 컬렉션 노출: 공개 API는 원시 List/Map 대신 수정 불가능한 뷰(unmodifiable view)를 반환하는가
• Dart 3 패턴 매칭 활용: 장황한 is 체크와 수동 캐스팅 대신 switch 표현식이나 if-case를 사용하고 있는가
• 다중 반환을 위한 일회용 클래스: 일회성 DTO 대신 Dart 3 레코드 (String, int)를 사용하고 있는가
• 프로덕션 내 print(): dart:developer log() 또는 로깅 패키지를 사용하는가; print()는 로그 레벨이 없고 필터링이 불가능함

---

3. 위젯 모범 사례

위젯 분해 (Decomposition):

• 단일 위젯의 build() 메서드가 80-100라인을 초과하지 않는가
• 캡슐화뿐만 아니라 변경 주기(리빌드 경계)를 기준으로 위젯이 분리되어 있는가
• 위젯을 반환하는 프라이빗 _build*() 헬퍼 메서드 대신 별도의 위젯 클래스로 추출되어 있는가 (엘리먼트 재사용, const 전파 및 프레임워크 최적화 가능)
• 가변 로컬 상태가 필요 없는 경우 Stateful 대신 Stateless 위젯을 선호하는가
• 재사용 가능한 위젯이 별도의 파일로 분리되어 있는가

Const 사용:

• 가능한 모든 곳에 const 생성자를 사용하여 불필요한 리빌드를 방지하고 있는가
• 변경되지 않는 컬렉션에 const 리터럴을 사용하는가 (const [], const {})
• 모든 필드가 final인 경우 생성자를 const로 선언했는가

Key 사용:

• 리스트/그리드에서 재정렬 시 상태를 보존하기 위해 ValueKey를 사용하고 있는가
• GlobalKey는 트리 전체에서 상태 접근이 정말로 필요한 경우에만 제한적으로 사용하고 있는가
• build() 내에서 UniqueKey 사용을 피하고 있는가 (매 프레임마다 리빌드를 강제함)
• 데이터 객체 자체를 식별 기준으로 삼을 때 ObjectKey를 사용하고 있는가

테마 및 디자인 시스템:

• 색상을 Theme.of(context).colorScheme에서 가져오는가 (하드코딩된 Colors.red 또는 헥사 코드 금지)
• 텍스트 스타일을 Theme.of(context).textTheme에서 가져오는가 (폰트 크기가 하드코딩된 인라인 TextStyle 금지)
• 다크 모드 호환성이 검증되었는가 (밝은 배경을 가정하지 않음)
• 간격과 크기 조절에 매직 넘버 대신 일관된 디자인 토큰이나 상수를 사용하고 있는가

Build 메서드 복잡도:

• build() 내에 네트워크 호출, 파일 I/O 또는 무거운 계산 로직이 없는가
• build() 내에 Future.then()이나 async 작업이 없는가
• build() 내에 구독 생성(.listen())이 없는가
• setState() 호출 범위를 최소한의 서브트리로 국한하고 있는가

---

4. 상태 관리 (라이브러리에 독립적인 원칙)

이 원칙들은 모든 Flutter 상태 관리 솔루션(BLoC, Riverpod, Provider, GetX, MobX, Signals, ValueNotifier 등)에 적용됩니다.

아키텍처:

• 비즈니스 로직이 위젯 레이어 외부에 있는가 (BLoC, Notifier, Controller, Store, ViewModel 등)
• 상태 관리자가 내부에서 의존성을 생성하지 않고 외부에서 주입받고 있는가
• 서비스 또는 저장소(Repository) 레이어가 데이터 소스를 추상화하고 있는가 (위젯이나 상태 관리자가 API/DB를 직접 호출하지 않음)
• 상태 관리자가 단일 책임 원칙을 따르고 있는가
• 컴포넌트 간 의존성이 해당 솔루션의 컨벤션을 따르는가:
  • Riverpod: ref.watch를 통한 프로바이더 간 의존성은 정상적이나, 순환 참조나 과도하게 복잡한 체인은 주의
  • BLoC: 블록 간 직접 의존성보다는 공유 저장소나 표현 레이어에서의 조율을 선호
  • 기타 솔루션: 문서화된 컴포넌트 간 통신 컨벤션을 준수

불변성 및 값 비교 (불변 상태 솔루션: BLoC, Riverpod, Redux용):

• 상태 객체가 불변(immutable)인가 — copyWith()나 생성자를 통해 새 인스턴스를 생성하며, 내부 값을 직접 수정하지 않음
• 상태 클래스가 ==와 hashCode를 올바르게 구현했는가 (모든 필드 비교 포함)
• 프로젝트 전체에서 비교 방식이 일관적인가 (수동 오버라이드, Equatable, freezed, Dart records 등)
• 상태 객체 내부의 컬렉션이 가변 List/Map으로 노출되지 않는가

반응형 규칙 (가변 반응형 솔루션: MobX, GetX, Signals용):

• 상태 수정이 해당 솔루션의 반응형 API를 통해서만 이루어지는가 (MobX의 @action, signals의 .value, GetX의 .obs) — 직접 필드 수정 시 변경 추적 불가
• 파생된 값(derived values)을 중복 저장하지 않고 솔루션의 계산(computed) 메커니즘을 사용하는가
• Reaction과 Disposer가 적절히 정리(clean up)되는가

상태 설계:

• 상호 배타적인 상태들이 불가능한 상태를 표현할 수 없는 구조인가 (불리언 플래그 isLoading, isError 등의 나열 대신 Sealed types나 Union variants 사용)
• 모든 비동기 작업이 로딩, 성공, 에러 상태를 명확히 구분하여 모델링하는가
• UI에서 모든 상태 케이스를 누락 없이 처리하고 있는가
• 에러 상태는 화면에 표시할 에러 정보를 포함하고, 로딩 상태는 오래된 데이터를 포함하지 않는가
• Null 허용 데이터를 로딩 인디케이터 대용으로 사용하지 않고 명시적인 상태를 사용하는가

// 나쁨 — 불리언 플래그들의 조합은 불가능한 상태를 허용함
class UserState {
  bool isLoading = false;
  bool hasError = false; // isLoading && hasError 같은 상태가 표현 가능함!
  User? user;
}

// 좋음 (불변 방식) — sealed 타입을 통해 불가능한 상태를 원천 차단
sealed class UserState {}
class UserInitial extends UserState {}
class UserLoading extends UserState {}
class UserLoaded extends UserState {
  final User user;
  const UserLoaded(this.user);
}
class UserError extends UserState {
  final String message;
  const UserError(this.message);
}

리빌드 최적화:

• 상태를 소비하는 위젯(Builder, Consumer, Observer, Obx, Watch 등)의 범위를 최대한 좁게 설정했는가
• 상태가 바뀔 때마다 매번 리빌드하지 않고, 특정 필드가 변경될 때만 리빌드되도록 셀렉터(Selector)를 사용하는가
• 트리 전체로 리빌드가 전파되는 것을 막기 위해 const 위젯을 사용하는가
• 계산/파생 상태가 중복 저장되지 않고 반응형으로 계산되는가

구독 및 해제 (Disposal):

• 모든 수동 구독(.listen())이 dispose() / close()에서 취소되는가
• 더 이상 필요 없는 Stream controller가 닫히는가
• 타이머가 해제 라이프사이클에서 취소되는가
• 수동 구독보다는 프레임워크가 관리하는 라이프사이클(선언적 빌더 등)을 선호하는가
• 비동기 콜백 내에서 setState 호출 전 mounted 여부를 확인하는가
• await 이후 BuildContext 사용 시 context.mounted를 확인하는가 (Flutter 3.7+; 만료된 컨텍스트는 크래시 원인)
• 비동기 작업 후 위젯이 여전히 마운트되어 있는지 확인하지 않고 내비게이션, 다이얼로그, 스낵바를 호출하지 않는가
• BuildContext를 싱글톤, 상태 관리자 또는 스태틱 필드에 저장하지 않는가

로컬 상태 vs 전역 상태:

• 일시적인 UI 상태(체크박스, 슬라이더, 애니메이션 등)에 로컬 상태(setState, ValueNotifier)를 사용하는가
• 공유 상태를 필요한 수준까지만 끌어올리고(lifting state up), 불필요하게 전역화하지 않았는가
• 기능(feature) 단위 스코프를 가진 상태가 해당 기능이 끝나면 적절히 해제되는가

---

5. 성능

불필요한 리빌드:

• 루트 위젯 레벨에서 setState()를 호출하지 않는가
• const 위젯을 사용해 리빌드 전파를 차단하는가
• 독립적으로 다시 그려지는 복잡한 서브트리에 RepaintBoundary를 사용하는가
• 애니메이션과 무관한 서브트리에 AnimatedBuilder의 child 파라미터를 활용하는가

build() 내 무거운 작업:

• build() 내에서 큰 컬렉션의 정렬, 필터링, 매핑 작업을 하지 않는가 (상태 관리 레이어에서 처리 권장)
• build() 내에서 정규표현식을 컴파일하지 않는가
• MediaQuery.of(context) 대신 필요한 정보만 가져오는 전용 메서드(예: MediaQuery.sizeOf(context))를 사용하는가

이미지 최적화:

• 네트워크 이미지에 캐싱을 적용하고 있는가
• 대상 기기에 적합한 해상도를 사용하고 있는가 (썸네일에 4K 이미지 사용 금지)
• Image.asset 사용 시 cacheWidth/cacheHeight를 지정해 표시 크기에 맞춰 디코딩하는가
• 네트워크 이미지 로딩 시 플레이스홀더와 에러 위젯을 제공하는가

지연 로딩 (Lazy Loading):

• 크거나 동적인 리스트에 ListView(children: [...]) 대신 ListView.builder / GridView.builder를 사용하는가
• 대용량 데이터 세트에 페이지네이션(Pagination)을 구현했는가
• 웹 빌드 시 무거운 라이브러리에 지연 로딩(deferred as)을 적용했는가

기타:

• 애니메이션에서 Opacity 위젯 대신 AnimatedOpacity 또는 FadeTransition을 사용하는가
• 애니메이션 중 클리핑(clipping)을 피하고 이미지를 미리 잘라두었는가
• 위젯에서 operator ==를 오버라이드하지 않고 const 생성자를 활용하는가
• 레이아웃 패스를 추가로 발생시키는 고정 치수 위젯(IntrinsicHeight, IntrinsicWidth) 사용을 최소화하는가

---

6. 테스트

테스트 종류 및 기대 사항:

• 유닛 테스트: 모든 비즈니스 로직(상태 관리자, 저장소, 유틸리티 함수)을 커버하는가
• 위젯 테스트: 개별 위젯의 동작, 상호작용 및 시각적 출력을 테스트하는가
• 통합 테스트: 핵심 사용자 흐름을 엔드 투 엔드로 테스트하는가
• 골든 테스트(Golden tests): 디자인상 중요한 UI 컴포넌트의 픽셀 단위 비교를 수행하는가

커버리지 목표:

• 비즈니스 로직의 라인 커버리지 80% 이상을 목표로 하는가
• 모든 상태 전이(loading → success, loading → error, retry 등)에 대응하는 테스트가 있는가
• 에지 케이스(빈 상태, 에러 상태, 로딩 상태, 경계값 등)를 테스트하는가

테스트 격리:

• 외부 의존성(API 클라이언트, DB, 서비스 등)을 모킹(mock)하거나 페이킹(fake)하는가
• 각 테스트 파일이 정확히 하나의 클래스/유닛만 테스트하는가
• 구현 세부 사항이 아닌 동작(behavior)을 검증하는가
• 테스트 케이스 간에 공유되는 가변 상태가 없는가

위젯 테스트 품질:

• 비동기 작업을 위해 pumpWidget과 pump를 올바르게 사용하는가
• find.byType, find.text, find.byKey 등을 상황에 맞게 활용하는가
• 타이밍에 의존하는 불안정한 테스트를 피하기 위해 pumpAndSettle 또는 명시적인 pump(Duration)를 사용하는가
• 테스트가 CI에서 실행되며 실패 시 머지(merge)가 차단되는가

---

7. 접근성 (Accessibility)

시맨틱 위젯:

• 자동 레이블이 부족한 곳에 Semantics 위젯을 사용하여 스크린 리더용 레이블을 제공하는가
• 순수 장식용 요소에 ExcludeSemantics를 사용하는가
• 관련된 위젯들을 하나의 접근성 요소로 묶기 위해 MergeSemantics를 사용하는가
• 이미지에 semanticLabel 속성이 설정되어 있는가

스크린 리더 지원:

• 모든 상호작용 요소가 포커스 가능하며 의미 있는 설명을 포함하는가
• 포커스 순서가 논리적인가 (시각적 읽기 순서 준수)

시각적 접근성:

• 배경 대비 텍스트 명암비가 4.5:1 이상인가
• 터치 대상 크기가 최소 48x48 픽셀 이상인가
• 상태 표시를 색상에만 의존하지 않는가 (아이콘/텍스트 병행 사용)
• 시스템 폰트 크기 설정에 따라 텍스트가 적절히 스케일링되는가

상호작용 접근성:

• 아무 동작도 하지 않는 onPressed 콜백이 없는가 (동작을 구현하거나 버튼을 비활성화할 것)
• 에러 필드가 수정 방법을 제안하는가
• 데이터 입력 중 예기치 않게 컨텍스트가 변경되지 않는가

---

8. 플랫폼별 고려 사항

iOS/Android 차이점:

• 상황에 맞게 플랫폼 적응형(platform-adaptive) 위젯을 사용하고 있는가
• 뒤로 가기 내비게이션이 각 플랫폼 관습에 맞게 처리되는가 (Android 뒤로 가기 버튼, iOS 스와이프)
• 상태 표시줄과 세이프 에어리어(Safe area)를 SafeArea 위젯으로 처리했는가
• 플랫폼별 권한이 AndroidManifest.xml과 Info.plist에 정의되어 있는가

반응형 디자인:

• LayoutBuilder나 MediaQuery를 사용하여 반응형 레이아웃을 구현했는가
• 중단점(breakpoint)이 일관되게 정의되었는가 (폰, 태블릿, 데스크톱)
• 작은 화면에서 텍스트가 넘치지(overflow) 않는가 — Flexible, Expanded, FittedBox 활용
• 가로 모드(Landscape) 테스트를 거쳤거나 명시적으로 잠금 처리했는가
• 웹 전용: 마우스/키보드 상호작용 지원, 호버(hover) 상태 존재 확인

---

9. 보안

안전한 저장소:

• 민감한 데이터(토큰, 자격 증명 등)를 플랫폼 보안 저장소(iOS의 Keychain, Android의 EncryptedSharedPreferences)에 저장하는가
• 비밀번호 등을 평문 저장소에 저장하지 않는가
• 민감한 작업에 생체 인증 게이팅을 고려했는가

API 키 관리:

• Dart 소스 코드에 API 키를 하드코딩하지 않았는가 — --dart-define, 버전 관리에서 제외된 .env 파일 또는 컴파일 타임 구성을 사용할 것
• 시크릿 정보가 git에 커밋되지 않았는가 (.gitignore 확인)
• 정말 중요한 키의 경우 백엔드 프록시를 사용하는가 (클라이언트가 서버 시크릿을 가져서는 안 됨)

입력 유효성 검사:

• 모든 사용자 입력을 API로 보내기 전에 유효성 검사를 거치는가
• 폼 검증 시 적절한 검증 패턴을 사용하는가
• 사용자 입력을 원시 SQL이나 문자열 보간에 직접 사용하지 않는가
• 내비게이션 전 딥링크 URL의 유효성을 검사하고 정제(sanitize)하는가

네트워크 보안:

• 모든 API 호출에 HTTPS를 강제하는가
• 고보안 앱의 경우 인증서 핀닝(Certificate pinning)을 고려했는가
• 인증 토큰 갱신 및 만료 처리가 올바르게 이루어지는가
• 민감한 데이터가 로그에 기록되거나 출력되지 않는가

---

10. 패키지/의존성 리뷰

pub.dev 패키지 평가:

• Pub points 점수를 확인했는가 (130/160점 이상 권장)
• Likes와 Popularity 등 커뮤니티 지표를 확인했는가
• 게시자가 pub.dev에서 **인증(verified)**되었는지 확인했는가
• 마지막 업데이트 날짜를 확인했는가 (1년 이상 지난 패키지는 위험 요소)
• 이슈 대응 속도 및 유지 보수 상태를 확인했는가
• 프로젝트 라이선스와 호환되는가
• 지원 플랫폼이 대상 플랫폼을 모두 커버하는가

버전 제약:

• 캐럿 구문(^1.2.3)을 사용해 호환 가능한 업데이트를 허용하는가
• 정말 필요한 경우에만 특정 버전을 고정(pin)하는가
• 정기적으로 flutter pub outdated를 실행해 오래된 의존성을 확인하는가
• 프로덕션 pubspec.yaml에 임시 수정 목적의 의존성 오버라이드(dependency_overrides)가 남아 있지 않은가
• 전이 의존성(transitive dependencies) 개수를 최소화하여 공격 표면을 줄이고 있는가

모노레포 관련 (melos/workspace):

• 내부 패키지가 다른 패키지의 public API만 임포트하는가 (내부 src/ 임포트 금지)
• 내부 패키지 의존성에 하드코딩된 상대 경로 대신 워크스페이스 해석을 사용하는가
• 모든 하위 패키지가 루트의 analysis_options.yaml을 공유하거나 상속하는가

---

11. 내비게이션 및 라우팅

일반 원칙 (모든 솔루션 공통):

• 하나의 라우팅 방식을 일관되게 사용하는가 (명령형 Navigator.push와 선언적 라우터를 섞어 쓰지 않음)
• 라우트 인자에 타입을 지정했는가 (Map<String, dynamic>이나 Object? 캐스팅 지양)
• 라우트 경로를 상수, 열거형 또는 생성된 코드로 정의했는가 (매직 스트링 금지)
• 인증 가드/리다이렉트 로직이 각 화면에 분산되지 않고 중앙 집중화되었는가
• Android와 iOS 모두에 대해 딥링크가 구성되어 있는가
• 이동 전 딥링크 URL의 유효성을 검사하고 정제하는가
• 내비게이션 상태를 테스트할 수 있는가
• 모든 플랫폼에서 뒤로 가기 동작이 올바른가

---

12. 에러 핸들링

프레임워크 에러 처리:

• 프레임워크 에러(빌드, 레이아웃, 페인트)를 잡기 위해 FlutterError.onError를 오버라이드했는가
• Flutter가 잡지 못한 비동기 에러를 처리하기 위해 PlatformDispatcher.instance.onError를 설정했는가
• 릴리스 모드용으로 ErrorWidget.builder를 커스터마이징했는가 (붉은 화면 대신 사용자 친화적 UI 제공)
• runApp 주변을 전역 에러 캡처 래퍼로 감쌌는가 (예: runZonedGuarded, Sentry/Crashlytics 래퍼)

에러 보고:

• 에러 보고 서비스(Firebase Crashlytics, Sentry 등)가 통합되어 있는가
• 치명적이지 않은 에러도 스택 트레이스와 함께 보고되는가
• 상태 관리 에러 옵저버가 에러 보고 서비스와 연결되어 있는가
• 디버깅을 위해 사용자 식별 정보(User ID 등)가 에러 리포트에 포함되는가

우아한 성능 저하 (Graceful Degradation):

• API 에러 발생 시 앱이 크래시되지 않고 사용자 친화적인 에러 UI를 보여주는가
• 일시적인 네트워크 장애에 대한 재시도 메커니즘이 있는가
• 오프라인 상태를 적절히 처리하는가
• 상태 관리 내의 에러 상태가 표시용 정보를 포함하고 있는가
• 원시 예외(네트워크, 파싱 에러 등)가 UI에 도달하기 전 사용자 친화적이고 지역화된 메시지로 매핑되는가 (사용자에게 로우 레벨 예외 문자열 노출 금지)

---

13. 국제화 (l10n)

설정:

• 지역화 솔루션이 구성되었는가 (Flutter 내장 ARB/l10n, easy_localization 등)
• 앱 구성에 지원되는 로케일(locale)이 선언되었는가

콘텐츠:

• 사용자에게 보이는 모든 문자열이 지역화 시스템을 사용하는가 (위젯 내 하드코딩된 문자열 금지)
• 템플릿 파일에 번역가를 위한 설명/컨텍스트가 포함되어 있는가
• 복수형, 성별, 선택형 문구에 ICU 메시지 구문을 사용하는가
• 플레이스홀더에 타입이 정의되어 있는가
• 지원하는 모든 언어에 대해 키가 누락되지 않았는가

코드 리뷰:

• 프로젝트 전체에서 지역화 접근 방식이 일관적인가
• 날짜, 시간, 숫자 및 통화 포맷이 로케일을 인식하는가
• 아랍어, 히브리어 등을 타겟팅하는 경우 텍스트 방향성(RTL)을 지원하는가
• 지역화 텍스트 생성 시 문자열 결합 대신 파라미터화된 메시지를 사용하는가

---

14. 의존성 주입 (DI)

원칙 (모든 DI 방식 공통):

• 레이어 경계에서 구체적인 구현이 아닌 추상화(인터페이스)에 의존하는가
• 클래스 내부에서 의존성을 직접 생성하지 않고 외부(생성자, DI 프레임워크 등)로부터 주입받는가
• 객체의 생명주기(Singleton, Factory, Lazy Singleton 등)를 명확히 구분하여 등록했는가
• 환경별 바인딩(dev/staging/prod)에 런타임 if 체크 대신 구성을 사용했는가
• DI 그래프에 순환 의존성이 없는가
• 서비스 로케이터 호출이 비즈니스 로직 전체에 흩어져 있지 않은가

---

15. 정적 분석

설정:

• 엄격한 설정이 활성화된 analysis_options.yaml이 존재하는가
• 분석기 설정: strict-casts: true, strict-inference: true, strict-raw-types: true
• 포괄적인 린트 규칙 세트가 포함되어 있는가 (very_good_analysis, flutter_lints 등)
• 모노레포의 모든 하위 패키지가 루트 분석 설정을 상속하거나 공유하는가

강제 사항:

• 커밋된 코드에 해결되지 않은 분석기 경고가 없는가
• 린트 억제(// ignore:) 사용 시 정당한 이유가 주석으로 설명되어 있는가
• CI에서 flutter analyze가 실행되며 실패 시 머지가 차단되는가

반드시 확인해야 할 주요 규칙:

• prefer_const_constructors — 위젯 트리 성능 최적화
• avoid_print — 적절한 로깅 사용 유도
• unawaited_futures — 비동기 에러 방지
• prefer_final_locals — 변수 레벨의 불변성 확보
• always_declare_return_types — 명확한 API 계약
• avoid_catches_without_on_clauses — 특정 에러 처리 강제
• always_use_package_imports — 일관된 임포트 스타일

---

상태 관리 빠른 참조

아래 표는 인기 있는 상태 관리 솔루션들이 공통 원칙을 어떻게 구현하는지 보여줍니다. 프로젝트에서 사용하는 솔루션에 맞춰 리뷰 규칙을 조정하세요.

원칙	BLoC/Cubit	Riverpod	Provider	GetX	MobX	Signals	내장 기능
상태 컨테이너	Bloc/Cubit	Notifier/AsyncNotifier	ChangeNotifier	GetxController	Store	signal()	StatefulWidget
UI 소비자	BlocBuilder	ConsumerWidget	Consumer	Obx/GetBuilder	Observer	Watch	setState
셀렉터	BlocSelector/buildWhen	ref.watch(p.select(...))	Selector	해당 없음	computed	computed()	해당 없음
사이드 이펙트	BlocListener	ref.listen	Consumer 콜백	ever()/once()	reaction	effect()	콜백 함수
해제 (Disposal)	BlocProvider에 의해 자동 처리	.autoDispose	Provider에 의해 자동 처리	onClose()	ReactionDisposer	수동 처리	dispose()
테스트	blocTest()	ProviderContainer	ChangeNotifier 직접 테스트	테스트 내 Get.put	Store 직접 테스트	Signal 직접 테스트	위젯 테스트

---

참고 자료

• Effective Dart: Style
• Effective Dart: Usage
• Effective Dart: Design
• Flutter Performance Best Practices
• Flutter Testing Overview
• Flutter Accessibility
• Flutter Internationalization
• Flutter Navigation and Routing
• Flutter Error Handling
• Flutter State Management Options