알 수 없는 라우트 진입 시 빈 화면 멈춤 수정

알 수 없는 라우트로 진입했을 때 앱이 그냥 빈 화면으로 멈추는 문제를 잡았다.

배경

라우팅 설정이 꽤 복잡해진 시점에서 이 버그가 수면 위로 올라왔다. 기능이 추가될수록 라우트 테이블은 점점 길어지는데, 정작 "정의되지 않은 경로"에 대한 처리는 아무도 제대로 챙기지 않고 있었다. 로컬에서 개발할 때는 딥링크나 내부 네비게이션을 직접 타이핑하는 일이 별로 없으니까 발견하기도 쉽지 않다.

문제가 터진 건 QA 단계에서였다. 테스터가 특정 딥링크를 잘못된 파라미터로 실행했더니 앱이 완전히 빈 화면으로 멈춰버렸다. 뒤로가기 버튼도 먹히지 않고, 홈으로 돌아갈 방법도 없는 상태. 사용자 입장에서는 앱이 죽었다고 느낄 수밖에 없는 UX였다.

app/lib/router/app_router.dart 한 파일에서 수정이 이루어진 만큼 핀포인트 수정이었지만, 그 영향은 앱 전체 네비게이션 안정성에 직결된다. 라우터 설정 파일은 작은 변경이 큰 파급을 만드는 대표적인 파일이기 때문에 리뷰할 때 항상 긴장하게 된다.

작업 내용

변경 핵심은 두 가지다.

• fallback route 정의: 매칭되는 라우트가 없을 때 홈 화면으로 리다이렉트
• 스낵바 피드백: 리다이렉트 전에 "잘못된 경로입니다" 메시지를 스낵바로 노출

코드 패턴으로 보면 대략 이런 식의 흐름이다.

// GoRouter 기준 예시 패턴
GoRoute(
  path: '/:unknownPath(.*)',
  redirect: (context, state) {
    // 스낵바 노출은 리다이렉트 직전 or WidgetsBinding으로 next frame 처리
    WidgetsBinding.instance.addPostFrameCallback((_) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('알 수 없는 경로입니다.')),
      );
    });
    return '/home';
  },
),

실제로 GoRouter 같은 선언형 라우터에서 unknown route 처리는 errorBuilder 혹은 redirect 콜백, 또는 와일드카드 라우트 등 여러 방식으로 구현할 수 있다.

이번 케이스는 딥링크로 직접 진입하는 시나리오도 있어서 와일드카드 라우트 + 홈 리다이렉트 조합이 가장 깔끔했다.

회고

솔직히 이 처리를 진작에 해뒀어야 했다. 라우터 파일을 처음 세팅할 때 "나중에 하자"고 미뤘던 게 QA에서 버그로 돌아왔다. 팀장 입장에서 이런 케이스는 꽤 뼈아프다. "지금 당장 동작하는 기능"에 집중하다 보면 "없는 기능"에 대한 방어 코드는 자꾸 후순위로 밀린다. 라우팅 예외 처리, 네트워크 에러 처리, 입력값 경계 케이스 — 이런 것들이 쌓이면 QA 막바지에 예상치 못한 버그로 터진다.

코드리뷰 때도 이 부분을 체크리스트에 추가했다. 새 라우트를 추가하는 PR을 리뷰할 때 "fallback이 여전히 살아 있는가"를 확인하는 항목을 넣어놨다. 라우터는 파일 하나지만 앱 전체 진입점을 책임지는 파일이라 변경이 생길 때마다 회귀 케이스가 생긴다. 특히 와일드카드 라우트는 순서가 틀리면 의도치 않게 정상 라우트까지 잡아버리는 사이드이펙트가 있어서, 이번 작업 이후 라우트 순서에 대한 주석도 같이 달아뒀다.

스낵바를 쓴 이유도 명확하다. 사용자가 "내가 왜 갑자기 홈에 와 있지?"를 이해할 수 있어야 한다. 아무 피드백 없이 홈으로 튕기면 앱이 오동작한다는 인상을 주기 쉽다. 한 줄 메시지라도 있으면 "아, 잘못된 경로였구나"로 인식이 정리된다. UX 관점의 방어 코드도 결국 사용자 신뢰의 문제다.

작은 수정이었지만 팀 전체 라우팅 정책을 다시 점검하는 계기가 됐다. 다음 스프린트 초반에 라우터 관련 컨벤션 문서를 팀 위키에 정리해두기로 했다.

끝.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.