· Flutter 개발 · 6 min read
클린 아키텍처 적용하기 - 대규모 Flutter 프로젝트 구조 설계
왜 클린 아키텍처인가
Flutter 앱을 처음 만들 때 많은 사람이 단순하게 시작한다. 뷰와 로직이 뒤섞인 구조로 빠르게 만들다 보면 어느 순간 파일 하나가 500줄을 넘어가고, 어디서 뭘 수정해야 할지 헷갈리는 상황이 온다.
스마트홈 앱은 처음부터 기능이 많았다. BLE, MQTT, REST API, 로컬 DB, 실시간 상태 관리… 이걸 아무 구조 없이 짜면 유지보수 지옥이 될 게 뻔했다. 그래서 초반에 시간을 좀 투자해서 아키텍처부터 잡고 들어갔다.
레이어 구조
프로젝트는 크게 네 개의 레이어로 나뉜다:
lib/
├── core/ # 앱 전반에서 사용하는 공통 코드
│ ├── bindings/ # GetX 바인딩, 라우팅
│ ├── config/ # 환경 설정 (dev/stage/prod)
│ ├── constants/ # 상수 정의
│ ├── services/ # 앱 레벨 서비스 (인증, 푸시)
│ └── utils/ # 유틸리티 함수들
│
├── domain/ # 비즈니스 로직 (외부 의존 없음)
│ ├── models/ # 도메인 모델
│ ├── repositories/ # 리포지토리 인터페이스
│ ├── usecases/ # 유스케이스
│ └── ports/ # 포트(캐시, MQTT 컨텍스트 등)
│
├── data/ # 도메인 인터페이스 구현체
│ ├── repositories/ # 리포지토리 구현
│ ├── services/ # 외부 서비스 (API, BLE, MQTT)
│ ├── models/ # 데이터 모델 (JSON 매핑용)
│ ├── mapper/ # 데이터 모델 → 도메인 모델 변환
│ ├── ble/ # BLE 관련 코드
│ └── cache/ # 캐시 구현
│
└── presentation/ # UI
├── core/ # 공통 위젯, 테마, 컨트롤러
├── signin/ # 로그인/회원가입
├── main/ # 메인 탭
├── device/ # 기기 연결/제어
├── manage/ # 기기/공간/멤버 관리
├── smart/ # 퀵모드/자동화
└── menu/ # 설정/메뉴
Domain 레이어
Domain 레이어는 외부 라이브러리 의존이 없어야 한다. Flutter SDK조차 최대한 쓰지 않는 게 이상적이다. 여기에는 비즈니스 규칙이 담긴다.
Repository 인터페이스 예시:
// domain/repositories/iot_device_mqtt_repository.dart
abstract class IoT DeviceMqttRepository {
Future<void> connect(MqttContext context);
Future<void> disconnect();
Future<void> publishPowerControl(String deviceId, bool isOn);
Future<void> publishTemperatureControl(String deviceId, int temperature);
Stream<IoT DeviceStatus> get statusStream;
}
구현은 data 레이어에서 하고, domain에서는 인터페이스만 정의한다. 덕분에 테스트할 때 Mock 구현체로 쉽게 교체할 수 있다.
Data 레이어
실제 MQTT 통신, API 호출, BLE 연결 등이 여기에 있다:
// data/repositories/iot_device_mqtt_repository_impl.dart
class IoT DeviceMqttRepositoryImpl implements IoT DeviceMqttRepository {
final MqttService _mqttService;
IoT DeviceMqttRepositoryImpl(this._mqttService);
@override
Future<void> publishPowerControl(String deviceId, bool isOn) async {
final topic = 'device/$deviceId/command/power';
final payload = jsonEncode({'power': isOn ? 'on' : 'off'});
await _mqttService.publish(topic, payload);
}
// ...
}
Mapper 패턴
API 응답 JSON과 도메인 모델은 분리한다. data/mapper/ 에서 변환을 담당한다:
// data/mapper/api/iot_device_mapper.dart
class IoT DeviceMapper {
static IoT DeviceDevice fromApiModel(IoT DeviceApiModel model) {
return IoT DeviceDevice(
id: model.deviceId,
name: model.nickname ?? model.modelName,
status: _mapStatus(model.statusCode),
);
}
}
API 스펙이 바뀌어도 Mapper만 수정하면 된다. Domain 모델은 건드리지 않아도 된다.
Presentation 레이어
GetX의 Controller가 여기에 있다. View는 Controller를 통해서만 데이터를 가져오고, Controller는 Repository를 통해서만 데이터를 가져온다:
// presentation/device/control/iot_device/iot_device_control_controller.dart
class IoT DeviceControlController extends GetxController {
final IoT DeviceMqttRepository _mqttRepo;
final Rx<IoT DeviceStatus?> status = Rx(null);
IoT DeviceControlController(this._mqttRepo);
@override
void onInit() {
super.onInit();
_mqttRepo.statusStream.listen((s) => status.value = s);
}
Future<void> togglePower() async {
final current = status.value?.isOn ?? false;
await _mqttRepo.publishPowerControl(deviceId, !current);
}
}
테스트 모드 구현이 깔끔해진다
이 구조의 가장 큰 장점 중 하나가 테스트 모드다. 실제 IoT 기기 기기 없이 개발할 때 data/test/ 에 Mock 구현체를 두고 교체해서 쓴다:
// data/test/test_iot_device_impl.dart
class TestIoT DeviceMqttRepositoryImpl implements IoT DeviceMqttRepository {
final _controller = StreamController<IoT DeviceStatus>.broadcast();
@override
Future<void> publishPowerControl(String deviceId, bool isOn) async {
// 실제 MQTT 대신 로컬에서 상태 변경 시뮬레이션
await Future.delayed(const Duration(milliseconds: 500));
_controller.add(IoT DeviceStatus(isOn: isOn, temperature: 22));
}
// ...
}
GetX Binding에서 환경에 따라 구현체를 교체해주면 된다.
처음에 느꼈던 불편함
솔직히 처음에는 이 구조가 너무 과하다고 느꼈다. 간단한 기능 하나 추가하려면 model → repository interface → repository impl → mapper → controller → view 순으로 파일을 여러 개 만들어야 했다.
그런데 프로젝트가 어느 정도 커지고 나서부터는 확실히 관리가 쉬워졌다. 새 기능을 추가할 때 어디에 뭘 써야 할지 명확하고, 버그가 생겼을 때도 어느 레이어 문제인지 좁혀지는 속도가 빨라졌다.
다음 편은 GetX로 상태관리와 라우팅을 어떻게 구성했는지 다룬다.