Dart 튜토리얼 22편: CLI 앱과 HTTP 서버(args·dart:io·서버 패키지)

Why#

NOTE

CLI 앱은 입력이 “함수 호출”이 아니라 “커맨드라인 인자”로 들어옵니다.
그래서 앱 구조는 시작부터 “인자 처리”를 중심으로 잡는 편이 자연스럽습니다.

What#

NOTE

예시 앱 dcat은 “인자로 받은 파일 경로들을 읽어서 출력한다”는 목표를 갖습니다.
경로가 없으면 표준 입력을 그대로 받아 표준 출력으로 흘려보내는 동작이 제시됩니다.

How#

TIP

다음 코드는 예시 앱의 전체 흐름(인자 파싱 → 경로 목록 → 처리)을 보여줍니다.
코드 블록 안 주석은 한글로 맞췄습니다.

1
import 'dart:convert';
2
import 'dart:io';
3

4
import 'package:args/args.dart';
5

6
const lineNumber = 'line-number';
7

8
void main(List<String> arguments) {
9
  exitCode = 0; // 성공을 기본값으로 둔다.
10
  final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');
11

12
  ArgResults argResults = parser.parse(arguments);
13
  final paths = argResults.rest;
14

15
  dcat(paths, showLineNumbers: argResults[lineNumber] as bool);
16
}
17

18
Future<void> dcat(List<String> paths, {bool showLineNumbers = false}) async {
19
  if (paths.isEmpty) {
20
    // 인자로 파일이 없으면 표준 입력을 받아서 그대로 출력한다.
21
    await stdin.pipe(stdout);
22
  } else {
23
    for (final path in paths) {
24
      var lineNumber = 1;
25
      final lines = utf8.decoder
26
          .bind(File(path).openRead())
27
          .transform(const LineSplitter());
28
      try {
29
        await for (final line in lines) {
30
          if (showLineNumbers) {
31
            stdout.write('${lineNumber++} ');
32
          }
33
          stdout.writeln(line);
34
        }
35
      } catch (_) {
36
        await _handleError(path);
37
      }
38
    }
39
  }
40
}
41

42
Future<void> _handleError(String path) async {
43
  if (await FileSystemEntity.isDirectory(path)) {
44
    stderr.writeln('error: $path is a directory');
45
  } else {
46
    exitCode = 2;
47
  }
48
}

Watch out#

WARNING

이 흐름을 그대로 따라가면 “비동기”(Future¹¹, Stream¹²)가 자연스럽게 섞입니다.
따라서 async/await가 익숙하지 않다면, 비동기 기초를 먼저 짧게 복습하고 오는 편이 좋습니다.

결론: CLI 앱은 “인자 → 경로 목록 → 처리 함수” 구조로 시작하면, 기능이 늘어도 흐름이 유지됩니다.

Why#

NOTE

인자 파싱을 문자열로 직접 처리하면 옵션이 늘어날수록 버그가 늘어납니다.
그래서 인자 파싱 전용 패키지를 쓰는 흐름이 제시됩니다.

What#

NOTE

args 패키지는 원시 커맨드라인 인자를 옵션/플래그/값으로 바꾸는 파서를 제공합니다.
핵심 타입은 ArgParser와 ArgResults입니다.

How#

TIP

예시에서는 -n 플래그를 추가하고, 파싱 결과의 나머지 값을 rest로 읽습니다.

1
void main(List<String> arguments) {
2
  exitCode = 0; // 성공을 기본값으로 둔다.
3
  final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');
4

5
  ArgResults argResults = parser.parse(arguments);
6
  final paths = argResults.rest;
7

8
  dcat(paths, showLineNumbers: argResults[lineNumber] as bool);
9
}

Watch out#

WARNING

파싱 결과는 “플래그/옵션”과 “나머지 인자(rest)”를 분리합니다.
따라서 파일 경로처럼 “옵션이 아닌 값”은 rest로 읽는 규칙을 코드로 고정해야 합니다.

결론: 인자 파싱은 args로 표준화하고, “옵션 vs rest” 경계를 명확히 둡니다.

Why#

NOTE

CLI의 입력은 파일이 될 수도 있고 표준 입력이 될 수도 있습니다.
둘을 분기 처리하더라도 “최종 출력”은 표준 출력으로 모으는 편이 단순합니다.

What#

NOTE

표준 입력을 그대로 표준 출력으로 전달하는 방식으로 stdin.pipe(stdout)가 제시됩니다.
파일 입력은 openRead()로 바이트 스트림을 만들고, utf8.decoder와 LineSplitter로 줄 단위 처리합니다.

How#

TIP

표준 입력을 받는 경우는 한 줄로 처리합니다.

1
await stdin.pipe(stdout);

파일을 줄 단위로 처리하는 흐름은 다음과 같습니다.

1
final lines = utf8.decoder
2
    .bind(File(path).openRead())
3
    .transform(const LineSplitter());
4
await for (final line in lines) {
5
  stdout.writeln(line);
6
}

Watch out#

WARNING

파일이 디렉터리이거나 읽기 실패가 발생하면 예외가 발생할 수 있습니다.
예시는 실패 시 stderr¹³로 메시지를 출력하고, exitCode¹⁴를 바꾸는 방식으로 처리합니다.

결론: 입력은 스트림으로 받고, 출력은 표준 출력으로 모으되, 실패는 표준 에러와 종료 코드로 표현합니다.

Why#

NOTE

서버는 인증/라우팅/미들웨어 같은 기능을 반복해서 필요로 합니다.
이 기능을 매번 직접 구현하면 유지보수가 어려워집니다.

What#

NOTE

서버·CLI 개발에서 유용한 커뮤니티 패키지 목록이 제시됩니다.
예를 들어 서버에서는 shelf 같은 미들웨어 모델을 제공하는 패키지가 언급됩니다.
또한 HTTP 서버 샘플로 shelf 기반 샘플과, Google APIs를 사용하는 샘플이 소개됩니다.

How#

TIP

필요한 기능 키워드로 pub.dev에서 검색하고, 플랫폼 지원 조건(서버/CLI)을 기준으로 선택합니다.
예를 들어 CLI에서는 args, 서버에서는 shelf 같은 패키지가 대표로 제시됩니다.

Watch out#

WARNING

패키지를 가져다 쓰면 편해지는 만큼, “플랫폼 지원”과 “버전/보안” 관점의 관리가 필요합니다.
따라서 의존성은 pubspec.yaml¹⁵로 명시하고, 설치/업데이트 흐름을 고정해야 합니다.

결론: 서버·CLI는 표준 라이브러리 + 커뮤니티 패키지를 조합하되, 의존성 관리를 함께 고정해야 합니다.