跨平台开发 / 系统课时

完成命令行任务管理器

完成命令行任务管理器

这一节把前面的 Dart 语法收束成一个可运行的小项目:实现支持新增、查看和完成任务的命令行工具,并用 JSON 文件持久化数据。过程中会把类、集合、空安全、异常、异步 I/O、模块拆分、静态分析和自动化测试连成一条完整工程链路。

学习目标

  • 用类与集合建模任务,并通过空安全和异常处理约束输入与数据格式。
  • 用异步文件 I/O 完成持久化,并把模型、仓储、业务服务和命令行入口拆成独立模块。
  • 通过 dart analyze、dart test 和实际命令运行验证项目质量与功能结果。

设计最小可用结构

项目只实现三条命令:add 新增任务、list 查看任务、done 完成任务。任务保存在 data/tasks.json,因此多次启动命令行程序也能读取同一份状态。职责拆分为 Task 模型、TaskRepository 持久化、TaskService 业务规则和 bin/tasker.dart 命令入口。

任务管理器模块与数据流

这种分层不是为了增加文件数量,而是为了让测试可以绕过命令行解析,直接验证业务服务和持久化;同时,文件读写错误也不会混进任务模型。

实现任务模型与持久化

先创建 lib/task.dart。这个模型只保存不可变字段,complete 返回新对象;从 JSON 恢复时主动校验类型,避免损坏的数据静默进入业务层。

dart
class Task {
  final int id;
  final String title;
  final bool done;

  const Task({
    required this.id,
    required this.title,
    required this.done,
  });

  Task complete() => Task(id: id, title: title, done: true);

  factory Task.fromJson(Map json) {
    final id = json['id'];
    final title = json['title'];
    final done = json['done'];

    // 持久化文件属于外部输入,恢复对象前必须检查实际类型。
    if (id is! int || title is! String || done is! bool) {
      throw const FormatException('任务数据格式无效');
    }
    return Task(id: id, title: title, done: done);
  }

  Map toJson() => {
        'id': id,
        'title': title,
        'done': done,
      };
}

接着创建 lib/task_repository.dart。所有文件操作都使用异步 API;文件不存在时返回空列表,内容不是 JSON 数组时抛出 FormatException,由上层决定如何向用户报告。

dart
import 'dart:convert';
import 'dart:io';

import 'task.dart';

class TaskRepository {
  final File file;

  TaskRepository(String path) : file = File(path);

  Future load() async {
    if (!await file.exists()) {
      return [];
    }

    final text = await file.readAsString();
    if (text.trim().isEmpty) {
      return [];
    }

    final decoded = jsonDecode(text);
    if (decoded is! List) {
      throw const FormatException('任务文件必须是 JSON 数组');
    }

    // 每个元素都交给 Task 再做一次字段级校验。
    return decoded.map((item) {
      if (item is! Map) {
        throw const FormatException('任务数据格式无效');
      }
      return Task.fromJson(item);
    }).toList();
  }

  Future save(List tasks) async {
    await file.parent.create(recursive: true);
    final data = tasks.map((task) => task.toJson()).toList();
    await file.writeAsString('${jsonEncode(data)}\n');
  }
}

业务规则放进 lib/task_service.dart。服务层负责标题校验、ID 分配、查找任务和更新状态;找不到任务时抛出明确的领域异常。

dart
import 'task.dart';
import 'task_repository.dart';

class TaskNotFoundException implements Exception {
  final int id;

  TaskNotFoundException(this.id);

  @override
  String toString() => '找不到任务 #$id';
}

class TaskService {
  final TaskRepository repository;

  TaskService(this.repository);

  Future add(String title) async {
    final normalized = title.trim();
    if (normalized.isEmpty) {
      throw const FormatException('任务标题不能为空');
    }

    final tasks = await repository.load();
    final maxId = tasks.fold(
      0,
      (current, task) => task.id > current ? task.id : current,
    );
    final task = Task(id: maxId + 1, title: normalized, done: false);

    tasks.add(task);
    await repository.save(tasks);
    return task;
  }

  Future list() => repository.load();

  Future complete(int id) async {
    final tasks = await repository.load();
    final index = tasks.indexWhere((task) => task.id == id);
    if (index == -1) {
      throw TaskNotFoundException(id);
    }

    final updated = tasks[index].complete();
    tasks[index] = updated;
    await repository.save(tasks);
    return updated;
  }
}

这里的集合是内存中的任务列表,而 JSON 文件是跨进程状态来源。await 保证当前读写完成后再继续修改或输出,避免把尚未落盘的数据当成成功结果。

接入命令行入口

创建 bin/tasker.dart,把参数解析限制在入口层。业务服务不知道命令行参数长什么样,因此未来即使换成 HTTP 或图形界面,也不需要重写核心规则。

dart
import 'dart:io';

import 'package:tasker_cli/task_repository.dart';
import 'package:tasker_cli/task_service.dart';

Future main(List args) async {
  final service = TaskService(TaskRepository('data/tasks.json'));

  try {
    if (args.isEmpty) {
      throw const FormatException('命令不能为空');
    }

    switch (args.first) {
      case 'add':
        if (args.length < 2) {
          throw const FormatException('用法: add 任务标题');
        }
        final task = await service.add(args.sublist(1).join(' '));
        stdout.writeln('已添加 #${task.id} ${task.title}');
        break;

      case 'list':
        final tasks = await service.list();
        if (tasks.isEmpty) {
          stdout.writeln('暂无任务');
          break;
        }
        for (final task in tasks) {
          final mark = task.done ? '[x]' : '[ ]';
          stdout.writeln('$mark #${task.id} ${task.title}');
        }
        break;

      case 'done':
        if (args.length != 2) {
          throw const FormatException('用法: done 任务ID');
        }
        final id = int.tryParse(args[1]);
        if (id == null) {
          throw const FormatException('任务ID必须是整数');
        }
        final task = await service.complete(id);
        stdout.writeln('已完成 #${task.id} ${task.title}');
        break;

      default:
        throw FormatException('未知命令: ${args.first}');
    }
  } on TaskNotFoundException catch (error) {
    stderr.writeln('错误: $error');
    exitCode = 2;
  } on FormatException catch (error) {
    stderr.writeln('错误: ${error.message}');
    exitCode = 64;
  } catch (error) {
    stderr.writeln('错误: $error');
    exitCode = 1;
  }
}

入口只捕获可预期异常并设置非零退出码。这样脚本或 CI 不仅能阅读错误文本,还能根据退出码判断命令是否成功。

补充分析与测试

在项目根目录创建 pubspec.yaml。运行环境只依赖 Dart SDK,测试依赖放在 dev_dependencies,不会进入业务代码。

yaml
name: tasker_cli
environment:
  sdk: ">=3.4.0 <4.0.0"

dev_dependencies:
  test: ^1.25.0

再创建 test/task_service_test.dart。测试使用临时目录,因此不会污染真实的 data/tasks.json;同时重新创建服务实例,确认结果确实来自文件持久化,而不是旧对象仍留在内存。

dart
import 'dart:io';

import 'package:tasker_cli/task_repository.dart';
import 'package:tasker_cli/task_service.dart';
import 'package:test/test.dart';

void main() {
  late Directory tempDir;
  late TaskService service;

  setUp(() async {
    tempDir = await Directory.systemTemp.createTemp('tasker_test_');
    service = TaskService(
      TaskRepository('${tempDir.path}/tasks.json'),
    );
  });

  tearDown(() async {
    if (await tempDir.exists()) {
      await tempDir.delete(recursive: true);
    }
  });

  test('新增、完成并重新加载任务', () async {
    final first = await service.add('补充测试');
    final second = await service.add('运行静态分析');

    expect(first.id, 1);
    expect(second.id, 2);

    final completed = await service.complete(2);
    expect(completed.done, isTrue);

    // 新实例再次读取文件,验证数据已经真正落盘。
    final reloaded = await TaskService(
      TaskRepository('${tempDir.path}/tasks.json'),
    ).list();
    expect(reloaded.length, 2);
    expect(reloaded.last.done, isTrue);
  });

  test('完成不存在的任务时抛出领域异常', () async {
    expect(
      service.complete(99),
      throwsA(
        predicate((error) => error is TaskNotFoundException),
      ),
    );
  });
}

静态分析负责发现类型、导入和代码规范问题;自动化测试负责验证业务行为。两者互补,不能用“程序能跑”替代。

运行并验收

保存上述文件后,在项目根目录执行下面这一组命令。先删除旧数据可以让最终输出从任务 ID 1 开始,便于核对;如果你希望保留已有任务,就不要执行第一行。

bash
rm -f data/tasks.json
dart pub get
dart analyze
dart test
dart run bin/tasker.dart add "完成 Dart 综合练习"
dart run bin/tasker.dart add "检查静态分析"
dart run bin/tasker.dart list
dart run bin/tasker.dart done 1
dart run bin/tasker.dart list

预期输出

text
Resolving dependencies...
Got dependencies!
Analyzing tasker_cli...
No issues found!
All tests passed!
已添加 #1 完成 Dart 综合练习
已添加 #2 检查静态分析
[ ] #1 完成 Dart 综合练习
[ ] #2 检查静态分析
已完成 #1 完成 Dart 综合练习
[x] #1 完成 Dart 综合练习
[ ] #2 检查静态分析

依赖解析与测试框架可能额外打印版本、进度和耗时信息,但验收关键是静态分析无问题、测试全部通过,并且第二次 list 仍能从文件中读出任务 1 的完成状态。到这里,类负责数据形态,集合承载运行时状态,空安全与类型检查守住边界,异常表达失败,异步 I/O 完成持久化,模块拆分则让分析、测试和后续扩展都有清晰落点。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

完成命令行任务管理器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通