プロジェクト設計と開発 — DataPipeline CLI ツール
真のエンジニアはコードを書くだけでなく、コードが成長できるアーキテクチャを設計する。— Bob
1. 学べること
- プロジェクトアーキテクチャ設計:層化 / モジュール分割 / 依存性注入
- CLI 引数解析(args パッケージ)とサブコマンド設計
- データソース抽象化(シールクラス)+ マルチフォーマットパーサー
- 非同期パイプライン設計(Stream + Isolate 並列処理)
- Charlie のコードレビュー:コード品質とパターンマッチングの実践
2. 開発者のリアルな物語
(1) 課題:スクリプトからツールへの成長痛
Bob は当初、EC データを処理するために複数の独立した Dart スクリプトを書いた:parse_csv.dart、calc_stats.dart、gen_report.dart。要件が増えるにつれ、スクリプト間のコピー&ペーストがますます増えた。たった 1 つのフィールド名を変更するために 5 つのファイルを変更する必要があった。Alice が「JSON データソースを追加できる?」と尋ねたとき、Bob はすべてのパースロジックが CSV と密結合しており変更が難しいことに気づいた。
(2) 再設計の解決策
Bob は DataPipeline をゼロから設計することを決定し、層化アーキテクチャを採用し、シールクラスでデータソースを抽象化し、Stream パイプラインで非同期処理を行うことを決めた。Charlie がコードレビューを実施し、品質を保証した。
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"]
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。
(3) 効果
- 新しい JSON データソースの追加はサブクラスを追加するだけで、既存コードの変更は不要
- Stream パイプラインが百万件のデータレコードを 1 つずつ処理し、メモリ使用量を制御下に保つ
- Isolate 並列処理が 4 コア CPU を完全に活用
- CLI サブコマンドによりユーザーが分析/エクスポート/検証を必要に応じて呼び出せる
3. プロジェクトアーキテクチャ設計
(1) 層化アーキテクチャ
| 層 | ディレクトリ | 責任 | 依存関係 |
|---|---|---|---|
| CLI 層 | bin/ |
引数解析、コマンドルーティング | サービス層 |
| サービス層 | lib/src/services/ |
パイプラインスケジューリング、Isolate 管理 | データ + コア層 |
| データ層 | lib/src/data/ |
データソース抽象化、パーサー | コア層 |
| コア層 | lib/src/core/ |
モデル、ユーティリティ、定数 | 外部依存なし |
▶ サンプル:プロジェクトディレクトリ構造
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
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。
4. CLI 引数解析とサブコマンド
(1) args パッケージサブコマンド設計
▶ サンプル:CLI エントリーポイントとサブコマンド
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);
}
}
> 出力: ローカルの DartPad または `dart run` で実行してください。この Dart コースの全例は Dart 3.x / Flutter 3.x ベースです。SDK バージョンにより結果が多少異なる場合があります。
| サブコマンド | 機能 | 主要パラメータ |
|---|---|---|
analyze |
データ分析と統計 | --source、--input、--parallel |
export |
レポートエクスポート | --format、--input、--output |
validate |
データ検証 | --input、--strict |
5. データソース抽象化 — シールクラス
▶ サンプル:シール DataSource
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 を消費するためのパターンマッチング
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. マルチフォーマットパーサー
▶ サンプル:注文パーサー
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 処理
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 プール
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. 依存性注入
▶ サンプル:サービスロケータパターン
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 ツール
// ============================================
// 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. 一時ファイルをクリーンアップしました。');
}
> 出力: ローカルの 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 の統合テスト例を参照してください。
📖 まとめ
- 層化アーキテクチャにより CLI/サービス/データ/コア層の責任が明確になり、依存関係が一方向になる
- シールクラスがデータソースを抽象化し、パターンマッチングがそれを消費し、コンパイラが見落としを保証する
- Stream パイプラインが百万件のデータレコードを 1 つずつフロー処理し、メモリを制御下に保つ
- Isolate プールの並列シャーディングが複数コアを完全に活用
- 依存性注入によりコアロジックがテスト可能で交換可能になる
📝 練習問題
- 基礎(難易度 ⭐):DataPipeline に
validateサブコマンドを追加し、--inputパラメータを受け取り、CSV ファイル内の不正な形式の行数をカウントして報告してください。 - 上級(難易度 ⭐⭐):
JsonSource+JsonOrderParserを実装してください。JSON 配列を入力として使用し、Pipeline を実行して分析結果を出力します。シールクラスの網羅的 switch がすべてのサブクラスをカバーしているかを検証してください。 - 挑戦(難易度 ⭐⭐⭐):
IsolatePoolを実装してください。1000 件のデモデータレコードを 4 シャードに分割し、4 つの Isolate を使用して並列分析し、最後に 4 つのAnalysisResultオブジェクトをマージします(売上と注文数を別々に合計)。並列実行とシーケンシャル実行の時間差を測定してください。