跨平台开发 / 系统课时
完成命令行任务管理器
完成命令行任务管理器
这一节把前面的 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 恢复时主动校验类型,避免损坏的数据静默进入业务层。
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,由上层决定如何向用户报告。
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 分配、查找任务和更新状态;找不到任务时抛出明确的领域异常。
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 或图形界面,也不需要重写核心规则。
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,不会进入业务代码。
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;同时重新创建服务实例,确认结果确实来自文件持久化,而不是旧对象仍留在内存。
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 开始,便于核对;如果你希望保留已有任务,就不要执行第一行。
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预期输出
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 完成持久化,模块拆分则让分析、测试和后续扩展都有清晰落点。