プロジェクト設計と開発 — DataPipeline CLI ツール

真のエンジニアはコードを書くだけでなく、コードが成長できるアーキテクチャを設計する。— Bob

1. 学べること


2. 開発者のリアルな物語

(1) 課題:スクリプトからツールへの成長痛

Bob は当初、EC データを処理するために複数の独立した Dart スクリプトを書いた:parse_csv.dartcalc_stats.dartgen_report.dart。要件が増えるにつれ、スクリプト間のコピー&ペーストがますます増えた。たった 1 つのフィールド名を変更するために 5 つのファイルを変更する必要があった。Alice が「JSON データソースを追加できる?」と尋ねたとき、Bob はすべてのパースロジックが CSV と密結合しており変更が難しいことに気づいた。

(2) 再設計の解決策

Bob は DataPipeline をゼロから設計することを決定し、層化アーキテクチャを採用し、シールクラスでデータソースを抽象化し、Stream パイプラインで非同期処理を行うことを決めた。Charlie がコードレビューを実施し、品質を保証した。

100%
graph TD
  subgraph アーキテクチャ層
    A[CLI 層<br/>args 解析]
    B[サービス層<br/>パイプラインスケジューリング]
    C[データ層<br/>ソース + パーサー]
    D[コア層<br/>モデル + ユーティリティ]
  end
  A --> B
  B --> C
  C --> D
  B --> E[Isolate プール]
  B --> F[Stream パイプライン]
  C --> G["シール DataSource"]
TEXT
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。

(3) 効果


3. プロジェクトアーキテクチャ設計

(1) 層化アーキテクチャ

ディレクトリ 責任 依存関係
CLI 層 bin/ 引数解析、コマンドルーティング サービス層
サービス層 lib/src/services/ パイプラインスケジューリング、Isolate 管理 データ + コア層
データ層 lib/src/data/ データソース抽象化、パーサー コア層
コア層 lib/src/core/ モデル、ユーティリティ、定数 外部依存なし

▶ サンプル:プロジェクトディレクトリ構造

TEXT
data_pipeline/
  bin/
    data_pipeline.dart        # CLI エントリーポイント
  lib/
    src/
      core/
        models/
          order.dart
          product.dart
          customer.dart
          analysis_result.dart
        utils/
          formatters.dart
          validators.dart
          constants.dart
      data/
        sources/
          data_source.dart     # シールクラス
          csv_source.dart
          json_source.dart
          api_source.dart
        parsers/
          order_parser.dart
          product_parser.dart
      services/
        pipeline.dart
        analyzer.dart
        isolate_pool.dart
        report_generator.dart
    data_pipeline.dart         # バレルエクスポート
  test/
    core/
      models_test.dart
      utils_test.dart
    data/
      parsers_test.dart
    services/
      pipeline_test.dart
      analyzer_test.dart
  pubspec.yaml
TEXT
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。

4. CLI 引数解析とサブコマンド

(1) args パッケージサブコマンド設計

▶ サンプル:CLI エントリーポイントとサブコマンド

DART
import 'package:args/args.dart';
import 'package:args/command_runner.dart';

// サブコマンド: analyze
class AnalyzeCommand extends Command {
  @override
  final name = 'analyze';
  @override
  final description = '注文データを分析して統計を生成';

  AnalyzeCommand() {
    argParser
      ..addOption('source', abbr: 's', defaultsTo: 'csv', allowed: ['csv', 'json', 'api'])
      ..addOption('input', abbr: 'i', mandatory: true)
      ..addOption('output', abbr: 'o', defaultsTo: 'stdout')
      ..addFlag('parallel', abbr: 'p', defaultsTo: false)
      ..addOption('isolate-count', defaultsTo: '4');
  }

  @override
  Future<void> run() async {
    final source = argResults!['source'] as String;
    final input = argResults!['input'] as String;
    final output = argResults!['output'] as String;
    final parallel = argResults!['parallel'] as bool;
    final isolateCount = int.parse(argResults!['isolate-count'] as String);

    print('Source: $source | Input: $input | Parallel: $parallel');
  }
}

// サブコマンド: export
class ExportCommand extends Command {
  @override
  final name = 'export';
  @override
  final description = '分析結果をファイルにエクスポート';

  ExportCommand() {
    argParser
      ..addOption('format', defaultsTo: 'json', allowed: ['json', 'csv', 'markdown'])
      ..addOption('input', abbr: 'i', mandatory: true)
      ..addOption('output', abbr: 'o', mandatory: true);
  }

  @override
  Future<void> run() async {
    final format = argResults!['format'] as String;
    final input = argResults!['input'] as String;
    final output = argResults!['output'] as String;

    print('Export: $format | $input -> $output');
  }
}

void main(List<String> args) async {
  final runner = CommandRunner('data_pipeline', 'DataPipeline - EC データ分析 CLI')
    ..addCommand(AnalyzeCommand())
    ..addCommand(ExportCommand());

  try {
    await runner.run(args);
  } on UsageException catch (e) {
    print(e);
  }
}
TEXT
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。
サブコマンド 機能 主要パラメータ
analyze データ分析と統計 --source、--input、--parallel
export レポートエクスポート --format、--input、--output
validate データ検証 --input、--strict

5. データソース抽象化 — シールクラス

▶ サンプル:シール DataSource

DART
sealed class DataSource {
  const DataSource();

  String get displayName;

  Stream<String> readLines();
}

class CsvSource extends DataSource {
  final String path;
  final String delimiter;

  const CsvSource({required this.path, this.delimiter = ','});

  @override
  String get displayName => 'CSV: $path';

  @override
  Stream<String> readLines() => File(path).openRead().transform(utf8.decoder).transform(const LineSplitter());
}

class JsonSource extends DataSource {
  final String path;

  const JsonSource({required this.path});

  @override
  String get displayName => 'JSON: $path';

  @override
  Stream<String> readLines() async* {
    final content = await File(path).readAsString();
    final jsonList = jsonDecode(content) as List;
    for (final item in jsonList) {
      yield jsonEncode(item);
    }
  }
}

class ApiSource extends DataSource {
  final String endpoint;
  final Map<String, String> headers;

  const ApiSource({required this.endpoint, this.headers = const {}});

  @override
  String get displayName => 'API: $endpoint';

  @override
  Stream<String> readLines() async* {
    final client = Client();
    final response = await client.get(Uri.parse(endpoint), headers: headers);
    final jsonList = jsonDecode(response.body) as List;
    for (final item in jsonList) {
      yield jsonEncode(item);
    }
    client.close();
  }
}

▶ サンプル:DataSource を消費するためのパターンマッチング

DART
DataSource createSource(String type, String input) => switch (type) {
  'csv' => CsvSource(path: input),
  'json' => JsonSource(path: input),
  'api' => ApiSource(endpoint: input),
  _ => throw ArgumentError('Unknown source type: $type'),
};

String sourceIcon(DataSource source) => switch (source) {
  CsvSource() => '📄',
  JsonSource() => '📋',
  ApiSource() => '🌐',
};
パターン 目的 優位性
シールクラス データソース型 網羅的 switch のコンパイル時保証
パターンマッチング データソースの消費 if-else チェーンなし
ファクトリ関数 データソースの作成 統一されたエントリーポイント

6. マルチフォーマットパーサー

▶ サンプル:注文パーサー

DART
abstract class OrderParser {
  const OrderParser();

  Order parse(String raw);
  List<Order> parseBatch(List<String> raws) => raws.map(parse).toList();
}

class CsvOrderParser extends OrderParser {
  final String delimiter;

  const CsvOrderParser({this.delimiter = ','});

  @override
  Order parse(String raw) {
    final parts = raw.split(delimiter);
    if (parts.length < 4) {
      throw FormatException('Invalid CSV row: $raw');
    }
    return Order(
      id: parts[0].trim(),
      amount: double.parse(parts[1].trim()),
      status: parts[2].trim(),
      category: parts[3].trim(),
      region: parts.length > 4 ? parts[4].trim() : 'US',
    );
  }
}

class JsonOrderParser extends OrderParser {
  const JsonOrderParser();

  @override
  Order parse(String raw) {
    final json = jsonDecode(raw) as Map<String, dynamic>;
    return Order(
      id: json['id'] as String,
      amount: (json['amount'] as num).toDouble(),
      status: json['status'] as String,
      category: json['category'] as String,
      region: (json['region'] as String?) ?? 'US',
    );
  }
}

7. Stream 非同期パイプライン

▶ サンプル:パイプライン Stream 処理

DART
import 'dart:async';
import 'dart:convert';
import 'dart:io';

class Pipeline {
  final DataSource _source;
  final OrderParser _parser;
  final int _chunkSize;

  Pipeline({
    required DataSource source,
    required OrderParser parser,
    int chunkSize = 1000,
  })  : _source = source,
        _parser = parser,
        _chunkSize = chunkSize;

  Future<AnalysisResult> execute() async {
    final orders = <Order>[];
    var processed = 0;
    var skipped = 0;

    await for (final line in _source.readLines()) {
      try {
        final order = _parser.parse(line);
        orders.add(order);
        processed++;
      } on FormatException {
        skipped++;
      }

      if (processed % _chunkSize == 0) {
        stdout.writeln('Progress: $processed orders processed, $skipped skipped');
      }
    }

    stdout.writeln('Total: $processed processed, $skipped skipped');

    final analyzer = OrderAnalyzer();
    return analyzer.analyze(orders);
  }

  Stream<Order> streamOrders() async* {
    await for (final line in _source.readLines()) {
      try {
        yield _parser.parse(line);
      } on FormatException {
        continue;
      }
    }
  }

  Stream<AnalysisResult> streamByCategory() {
    final controller = StreamController<AnalysisResult>();

    streamOrders().fold<Map<String, List<Order>>>(
      {},
      (groups, order) {
        groups.update(order.category, (v) => v..add(order), ifAbsent: () => [order]);
        return groups;
      },
    ).then((groups) {
      final analyzer = OrderAnalyzer();
      for (final entry in groups.entries) {
        controller.add(analyzer.analyze(entry.value));
      }
      controller.close();
    });

    return controller.stream;
  }
}

8. Isolate 並列処理

▶ サンプル:Isolate プール

DART
import 'dart:isolate';

class IsolatePool {
  final int _poolSize;
  final List<Isolate> _isolates = [];
  final List<SendPort> _sendPorts = [];

  IsolatePool({int poolSize = 4}) : _poolSize = poolSize;

  Future<void> initialize() async {
    for (var i = 0; i < _poolSize; i++) {
      final receivePort = ReceivePort();
      final isolate = await Isolate.spawn(
        _isolateEntryPoint,
        receivePort.sendPort,
      );
      final sendPort = await receivePort.first as SendPort;
      _isolates.add(isolate);
      _sendPorts.add(sendPort);
    }
  }

  static void _isolateEntryPoint(SendPort mainSendPort) {
    final receivePort = ReceivePort();
    mainSendPort.send(receivePort.sendPort);

    receivePort.listen((message) {
      if (message is _IsolateTask) {
        final result = _processChunk(message.orders, message.taxRate);
        message.responsePort.send(result);
      }
    });
  }

  static AnalysisResult _processChunk(List<Map<String, dynamic>> rawOrders, double taxRate) {
    final orders = rawOrders.map((o) => Order(
      id: o['id'] as String,
      amount: (o['amount'] as num).toDouble(),
      status: o['status'] as String,
      category: o['category'] as String,
      region: (o['region'] as String?) ?? 'US',
    )).toList();

    final analyzer = OrderAnalyzer(taxRate: taxRate);
    return analyzer.analyze(orders);
  }

  Future<List<AnalysisResult>> processInParallel(
    List<Map<String, dynamic>> allOrders,
    double taxRate,
  ) async {
    final chunkSize = (allOrders.length / _poolSize).ceil();
    final results = <AnalysisResult>[];
    final completers = <Completer<AnalysisResult>>[];

    for (var i = 0; i < _poolSize; i++) {
      final start = i * chunkSize;
      final end = (start + chunkSize).clamp(0, allOrders.length);
      if (start >= allOrders.length) break;

      final chunk = allOrders.sublist(start, end);
      final completer = Completer<AnalysisResult>();
      completers.add(completer);

      _sendPorts[i].send(_IsolateTask(
        orders: chunk,
        taxRate: taxRate,
        responsePort: completer.future as dynamic,
      ));
    }

    for (final completer in completers) {
      results.add(await completer.future);
    }

    return results;
  }

  void dispose() {
    for (final isolate in _isolates) {
      isolate.kill(priority: Isolate.immediate);
    }
  }
}

class _IsolateTask {
  final List<Map<String, dynamic>> orders;
  final double taxRate;
  final SendPort responsePort;

  const _IsolateTask({
    required this.orders,
    required this.taxRate,
    required this.responsePort,
  });
}
並列モデル 適切なシナリオ 優位性
Isolate.run ワンタイム計算 シンプルな API
Isolate.spawn 長時間実行ワーカー 再利用可能
Isolate プール 均等シャーディング 複数コアの完全活用
compute(Flutter) UI ジャンクなし Flutter 固有

9. 依存性注入

▶ サンプル:サービスロケータパターン

DART
class ServiceLocator {
  static final _instances = <Type, dynamic>{};

  static void register<T>(T instance) {
    _instances[T] = instance;
  }

  static T get<T>() {
    final instance = _instances[T];
    if (instance == null) {
      throw StateError('Service not registered: $T');
    }
    return instance as T;
  }

  static void reset() {
    _instances.clear();
  }
}

// 起動時の登録
void setupServices({required String sourceType, required String inputPath}) {
  final source = createSource(sourceType, inputPath);

  ServiceLocator.register<DataSource>(source);

  final parser = switch (source) {
    CsvSource() => const CsvOrderParser() as OrderParser,
    JsonSource() => const JsonOrderParser(),
    ApiSource() => const JsonOrderParser(),
  };

  ServiceLocator.register<OrderParser>(parser);
  ServiceLocator.register<OrderAnalyzer>(const OrderAnalyzer());
  ServiceLocator.register<Pipeline>(Pipeline(source: source, parser: parser));
}

10. 完全なサンプル:DataPipeline CLI ツール

DART
// ============================================
// DataPipeline CLI ツール - 完全実装
// Bob の EC データ分析ツール
// ============================================

import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:isolate';

// ---- コアモデル ----

class Order {
  final String id;
  final double amount;
  final String status;
  final String category;
  final String region;

  const Order({
    required this.id,
    required this.amount,
    required this.status,
    required this.category,
    this.region = 'US',
  });

  double get tax => amount * _taxRate(region);
  double get total => amount + tax;

  static double _taxRate(String region) => switch (region) {
    'US' => 0.08,
    'EU' => 0.20,
    'UK' => 0.15,
    'JP' => 0.10,
    _ => 0.10,
  };

  Map<String, dynamic> toJson() => {
    'id': id,
    'amount': amount,
    'status': status,
    'category': category,
    'region': region,
  };
}

class AnalysisResult {
  final int totalOrders;
  final int completedOrders;
  final double revenue;
  final double tax;
  final double total;
  final Map<String, double> revenueByCategory;

  const AnalysisResult({
    required this.totalOrders,
    required this.completedOrders,
    required this.revenue,
    required this.tax,
    required this.total,
    required this.revenueByCategory,
  });

  double get averageOrderValue => completedOrders > 0 ? revenue / completedOrders : 0;

  @override
  String toString() => '''
=== DataPipeline 分析結果 ===
注文:       $completedOrders/$totalOrders 完了
売上:       \$${revenue.toStringAsFixed(2)} USD
税:         \$${tax.toStringAsFixed(2)} USD
合計:       \$${total.toStringAsFixed(2)} USD
平均:       \$${averageOrderValue.toStringAsFixed(2)} USD
カテゴリ:   ${revenueByCategory.keys.join(', ')}
''';
}

// ---- コアサービス ----

class OrderAnalyzer {
  final double taxRate;

  const OrderAnalyzer({this.taxRate = 0.08});

  AnalysisResult analyze(List<Order> orders) {
    final completed = orders.where((o) => o.status == 'completed').toList();
    final revenue = completed.fold<double>(0, (s, o) => s + o.amount);
    final tax = completed.fold<double>(0, (s, o) => s + o.tax);
    final total = revenue + tax;

    final byCategory = <String, double>{};
    for (final o in completed) {
      byCategory.update(o.category, (v) => v + o.amount, ifAbsent: () => o.amount);
    }

    return AnalysisResult(
      totalOrders: orders.length,
      completedOrders: completed.length,
      revenue: revenue,
      tax: tax,
      total: total,
      revenueByCategory: byCategory,
    );
  }
}

// ---- データソース(シール)----

sealed class DataSource {
  const DataSource();
  String get displayName;
  Stream<String> readLines();
}

class CsvSource extends DataSource {
  final String path;
  const CsvSource({required this.path});

  @override
  String get displayName => 'CSV: $path';

  @override
  Stream<String> readLines() =>
    File(path).openRead().transform(utf8.decoder).transform(const LineSplitter());
}

class JsonSource extends DataSource {
  final String path;
  const JsonSource({required this.path});

  @override
  String get displayName => 'JSON: $path';

  @override
  Stream<String> readLines() async* {
    final content = await File(path).readAsString();
    final list = jsonDecode(content) as List;
    for (final item in list) {
      yield jsonEncode(item);
    }
  }
}

// ---- パーサー ----

abstract class OrderParser {
  const OrderParser();
  Order parse(String raw);
}

class CsvOrderParser extends OrderParser {
  const CsvOrderParser();

  @override
  Order parse(String raw) {
    final parts = raw.split(',');
    if (parts.length < 4) throw FormatException('Invalid row: $raw');
    return Order(
      id: parts[0].trim(),
      amount: double.parse(parts[1].trim()),
      status: parts[2].trim(),
      category: parts[3].trim(),
    );
  }
}

class JsonOrderParser extends OrderParser {
  const JsonOrderParser();

  @override
  Order parse(String raw) {
    final json = jsonDecode(raw) as Map<String, dynamic>;
    return Order(
      id: json['id'] as String,
      amount: (json['amount'] as num).toDouble(),
      status: json['status'] as String,
      category: json['category'] as String,
    );
  }
}

// ---- パイプライン ----

class Pipeline {
  final DataSource source;
  final OrderParser parser;

  const Pipeline({required this.source, required this.parser});

  Future<AnalysisResult> execute() async {
    final orders = <Order>[];
    var count = 0;

    await for (final line in source.readLines()) {
      try {
        orders.add(parser.parse(line));
        count++;
        if (count % 100000 == 0) {
          stdout.writeln('Progress: ${(count / 1000).toStringAsFixed(0)}K orders');
        }
      } on FormatException {
        continue;
      }
    }

    stdout.writeln('Loaded: ${(count / 1000).toStringAsFixed(0)}K orders from ${source.displayName}');
    return const OrderAnalyzer().analyze(orders);
  }
}

// ---- デモデータ生成器 ----

List<String> generateDemoOrders(int count) {
  final categories = ['Electronics', 'Clothing', 'Books', 'Home', 'Sports'];
  final statuses = ['completed', 'completed', 'completed', 'pending', 'cancelled'];
  final regions = ['US', 'EU', 'UK', 'JP'];

  return List.generate(count, (i) {
    final category = categories[i % categories.length];
    final status = statuses[i % statuses.length];
    final region = regions[i % regions.length];
    final amount = (100 + (i * 37) % 5000).toDouble();
    return 'ORD-${(i + 1).toString().padLeft(5, '0')},$amount,$status,$category,$region';
  });
}

// ---- メイン ----

void main() async {
  print('=== DataPipeline CLI v1.0 ===\n');

  final demoData = generateDemoOrders(1000);
  final tempFile = File('${Directory.systemTemp.path}/demo_orders.csv');
  await tempFile.writeAsString(demoData.join('\n'));

  final source = CsvSource(path: tempFile.path);
  final parser = const CsvOrderParser();
  final pipeline = Pipeline(source: source, parser: parser);

  print('Source: ${source.displayName}');
  print('Processing...\n');

  final result = await pipeline.execute();
  print(result);

  final sorted = result.revenueByCategory.entries.toList()
    ..sort((a, b) => b.value.compareTo(a.value));

  print('カテゴリ別売上:');
  for (final entry in sorted) {
    print('  ${entry.key.padRight(12)}: \$${entry.value.toStringAsFixed(2)} USD');
  }

  await tempFile.delete();
  print('\nDone. 一時ファイルをクリーンアップしました。');
}
TEXT
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。

11. Charlie のコードレビュー

(1) ▶ レビューポイント

観点 レビュー基準 DataPipeline チェックリスト
型安全性 dynamic なし、網羅的 switch シール DataSource + パターンマッチング
テスト可能性 コアロジックが I/O に依存しない OrderParser は純粋関数、Pipeline はインターフェースを受け入れる
エラー処理 例外を飲み込まない、フォールバックあり FormatException スキップ + カウント
パフォーマンス メモリ制御、ノンブロッキング非同期 Stream 行ごと処理 + Isolate シャーディング
拡張性 新機能が古いコードを変更しない 新しい DataSource サブクラスで既存コードの変更ゼロ

Charlie:「シールクラス + パターンマッチングによりコンパイラが見落としをチェックできる。if-else よりずっと安全だ。OrderParser は純粋関数なので、テストでファイルシステムをモックする必要がない。」


❓ よくある質問

Q: データソースに 列挙型 ではなくシールクラスを使うのはなぜですか? A: 列挙型 はデータ(path、endpoint など)を保持できません。シールクラスはフィールドとメソッドを持ちながら、網羅的 switch のコンパイル時保証を維持できます。

Q: Pipeline では Stream と Future のどちらを使うべきですか? A: データがレコード単位で到着しリアルタイム処理が必要な場合は Stream、すべてを一度にロードして処理する場合は Future を使います。百万件以上のレコードにはメモリオーバーフローを避けるため Stream が推奨されます。

Q: Isolate 通信はプリミティブ型のみ渡せますか? A: SendPort 経由で渡されるデータはシリアライズ可能である必要があります。カスタムクラスは Map に変換するか jsonEncode/Decode を使う必要があります。Dart 3 の Records も渡せます。

Q: args パッケージと dcli パッケージのどちらが優れていますか? A: args は公式パッケージで、標準的なサブコマンドパターンに適しています。dcli はより豊富な CLI ツール(ファイル操作、プロセス管理など)を提供しますが非公式です。このチュートリアルでは args を使用しています。

Q: 依存性注入にフレームワークが必要ですか? A: 必ずしも。小規模プロジェクトには Service Locator やコンストラクタ注入で十分です。flutter_bloc、get_it などのフレームワークは大規模プロジェクト向けです。DataPipeline はシンプルな ServiceLocator を使用しています。

Q: Pipeline のエンドツーエンドフローをテストするには? A: 一時ファイル(Directory.systemTemp)をテストデータソースとして使用し、出力 AnalysisResult の各フィールドの値を検証します。レッスン L20 の統合テスト例を参照してください。


📖 まとめ


📝 練習問題

  1. 基礎(難易度 ⭐):DataPipeline に validate サブコマンドを追加し、--input パラメータを受け取り、CSV ファイル内の不正な形式の行数をカウントして報告してください。
  2. 上級(難易度 ⭐⭐)JsonSource + JsonOrderParser を実装してください。JSON 配列を入力として使用し、Pipeline を実行して分析結果を出力します。シールクラスの網羅的 switch がすべてのサブクラスをカバーしているかを検証してください。
  3. 挑戦(難易度 ⭐⭐⭐)IsolatePool を実装してください。1000 件のデモデータレコードを 4 シャードに分割し、4 つの Isolate を使用して並列分析し、最後に 4 つの AnalysisResult オブジェクトをマージします(売上と注文数を別々に合計)。並列実行とシーケンシャル実行の時間差を測定してください。

← 前のレッスン | 次のレッスン →

Web-Tutorial.com

Web-Tutorial 技術チーム

複数の開発者によって共同維持されているプログラミングチュートリアルプラットフォーム。各チュートリアルは専門分野の開発者が執筆・レビューしています。正確で信頼性の高いコンテンツを目指しています — 問題を見つけた場合はお知らせください。

100%