第 2-9 课：Python 进阶综合项目——多文件任务管理程序
一、本课目标
完成本课后，你将能够把第二阶段所学内容组合成一个可运行的小程序：
- 用多个 Python 文件组织程序；
- 用 JSON 文件保存并恢复任务；
- 用异常处理保护文件读取和用户输入；
- 使用推导式、生成器、装饰器和类型注解；
- 解释每个模块的职责，并完成第二阶段验收。
二、前置知识
需要完成或阅读过第二阶段第 1 至第 8 课。第 8 课虽然已跳过，但本项目不依赖第三方软件包，只使用 Python 标准库。
三、项目要解决什么问题
单个文件中的代码变多后，阅读和修改都会变困难。这个项目把任务管理功能拆分为三部分：
main.py 程序入口：组织执行顺序、显示结果
task_service.py 业务功能：新增、完成、筛选和汇总任务
task_store.py 数据读写：把任务保存到 JSON 文件、再读回来
职责拆分的好处是：保存格式改变时主要修改 task_store.py；新增业务规则时主要修改 task_service.py；入口显示变化时主要修改 main.py。
四、什么是 JSON
JSON（JavaScript Object Notation）是一种常用的文本数据格式。它能保存列表、字典、字符串、数字和布尔值，适合本课保存任务数据。
Python 使用标准库 json：
json.dumps(data) # 把 Python 数据转换成 JSON 文本
json.loads(text) # 把 JSON 文本转换成 Python 数据
本项目保存的单条任务类似：
{
"id": 1,
"title": "整理本课学习笔记",
"priority": "高",
"completed": False,
}
五、完整示例
完整示例由 main.py、task_service.py 和 task_store.py 组成。请先逐个打开文件，再运行入口文件。
六、运行方法
在项目根目录执行：
cd D:\Code\Python
python .\02_python进阶\2_9_python进阶综合项目\main.py
首次运行会自动创建：
02_python进阶/2_9_python进阶综合项目/task_data/tasks.json
这是本地运行数据，已由 .gitignore 忽略。再次运行会继续读取已有任务，所以任务数量会增加，这是正常现象。
七、正常结果示例
第一次运行时，输出格式类似：
读取到 0 条已有任务。
正在执行：add_task
正在执行：add_task
正在执行：complete_task
本次新增的任务：
[1] 整理本课学习笔记｜优先级：高｜状态：已完成
[2] 运行任务管理程序｜优先级：中｜状态：未完成
未完成任务：
[2] 运行任务管理程序｜优先级：中｜状态：未完成
任务汇总：
全部：2 条，已完成：1 条，未完成：1 条。
编号和总数量会因之前运行过的次数而不同。
八、关键代码解析
8.1 文件不存在时返回空列表
if not data_file.exists():
return []
第一次运行还没有任务文件，这不是错误。返回空列表后，程序就可以从第一条任务开始添加。
8.2 装饰器记录调用
@log_call 会在原函数执行前输出函数名，但不会改变原函数的参数和返回值。它适合为多个关键操作增加相同的提示。
8.3 生成器逐条提供未完成任务
for task in tasks:
if not task["completed"]:
yield task
yield 让函数每找到一条未完成任务就交出一条，不需要先创建完整的新列表。
8.4 类型注解
例如 list[dict[str, object]] 表示“由任务字典组成的列表”。任务中的值既可能是编号、文字，也可能是布尔值，所以这里使用 object。
九、常见错误
9.1 直接运行 task_service.py
它是功能模块，不是入口程序。应运行 main.py。
9.2 JSON 文件内容损坏
手工编辑 tasks.json 时漏写逗号或引号，会导致 JSON 格式错误。示例会安全返回空列表；练习中应捕获 json.JSONDecodeError 并给出提示。
9.3 忘记保存
列表只在程序运行期间存在。调用 add_task() 或 complete_task() 后，要调用 save_tasks() 才能写入文件。
9.4 使用 wrapper() 代替 wrapper
装饰器最后应 return wrapper，不是 return wrapper()；后者会在装饰阶段提前执行函数。
十、课堂练习
打开 practice.py，按六部分要求自己创建 practice_store.py、practice_service.py 和 practice_main.py。练习文件保持题面说明形式，不包含预置函数骨架。
十一、参考答案
本课不提前写入参考答案。完成后把三个练习文件保留在本课目录，我会按模块职责、功能正确性、可读性和知识掌握情况进行验证。
十二、本课小结
- 模块让不同职责的代码分开放置；
- JSON 能把 Python 的任务数据保存为文本；
Path让路径处理更安全清晰；try...except让预期的读取问题不至于让程序崩溃；- 推导式适合快速生成汇总数据，生成器适合逐条提供结果；
- 装饰器可为多个函数增加共同功能；
- 类型注解让函数接收什么、返回什么更清楚。
十三、验收标准
- 能独立运行完整示例并说明三个模块的职责；
- 能解释 JSON 保存和读取的方向；
- 能说明本项目中异常处理、推导式、生成器、装饰器和类型注解分别在哪里使用；
- 能按题目完成三个练习模块；
- 再次运行练习程序时，能够读取上次保存的任务；
- 已完成第二阶段的综合项目，具备进入第三阶段“面向对象编程”的基础。