168 lines
5.6 KiB
Markdown
168 lines
5.6 KiB
Markdown
# 第 2-9 课：Python 进阶综合项目——多文件任务管理程序
|
||
|
||
## 一、本课目标
|
||
|
||
完成本课后，你将能够把第二阶段所学内容组合成一个可运行的小程序：
|
||
|
||
1. 用多个 Python 文件组织程序；
|
||
2. 用 JSON 文件保存并恢复任务；
|
||
3. 用异常处理保护文件读取和用户输入；
|
||
4. 使用推导式、生成器、装饰器和类型注解；
|
||
5. 解释每个模块的职责，并完成第二阶段验收。
|
||
|
||
## 二、前置知识
|
||
|
||
需要完成或阅读过第二阶段第 1 至第 8 课。第 8 课虽然已跳过，但本项目不依赖第三方软件包，只使用 Python 标准库。
|
||
|
||
## 三、项目要解决什么问题
|
||
|
||
单个文件中的代码变多后，阅读和修改都会变困难。这个项目把任务管理功能拆分为三部分：
|
||
|
||
```text
|
||
main.py 程序入口：组织执行顺序、显示结果
|
||
task_service.py 业务功能：新增、完成、筛选和汇总任务
|
||
task_store.py 数据读写：把任务保存到 JSON 文件、再读回来
|
||
```
|
||
|
||
职责拆分的好处是：保存格式改变时主要修改 `task_store.py`；新增业务规则时主要修改 `task_service.py`；入口显示变化时主要修改 `main.py`。
|
||
|
||
## 四、什么是 JSON
|
||
|
||
JSON（JavaScript Object Notation）是一种常用的文本数据格式。它能保存列表、字典、字符串、数字和布尔值，适合本课保存任务数据。
|
||
|
||
Python 使用标准库 `json`：
|
||
|
||
```python
|
||
json.dumps(data) # 把 Python 数据转换成 JSON 文本
|
||
json.loads(text) # 把 JSON 文本转换成 Python 数据
|
||
```
|
||
|
||
本项目保存的单条任务类似：
|
||
|
||
```python
|
||
{
|
||
"id": 1,
|
||
"title": "整理本课学习笔记",
|
||
"priority": "高",
|
||
"completed": False,
|
||
}
|
||
```
|
||
|
||
## 五、完整示例
|
||
|
||
完整示例由 `main.py`、`task_service.py` 和 `task_store.py` 组成。请先逐个打开文件，再运行入口文件。
|
||
|
||
## 六、运行方法
|
||
|
||
在项目根目录执行：
|
||
|
||
```powershell
|
||
cd D:\Code\Python
|
||
python .\02_python进阶\2_9_python进阶综合项目\main.py
|
||
```
|
||
|
||
首次运行会自动创建：
|
||
|
||
```text
|
||
02_python进阶/2_9_python进阶综合项目/task_data/tasks.json
|
||
```
|
||
|
||
这是本地运行数据，已由 `.gitignore` 忽略。再次运行会继续读取已有任务，所以任务数量会增加，这是正常现象。
|
||
|
||
## 七、正常结果示例
|
||
|
||
第一次运行时，输出格式类似：
|
||
|
||
```text
|
||
读取到 0 条已有任务。
|
||
正在执行：add_task
|
||
正在执行：add_task
|
||
正在执行：complete_task
|
||
|
||
本次新增的任务：
|
||
[1] 整理本课学习笔记｜优先级：高｜状态：已完成
|
||
[2] 运行任务管理程序｜优先级：中｜状态：未完成
|
||
|
||
未完成任务：
|
||
[2] 运行任务管理程序｜优先级：中｜状态：未完成
|
||
|
||
任务汇总：
|
||
全部：2 条，已完成：1 条，未完成：1 条。
|
||
```
|
||
|
||
编号和总数量会因之前运行过的次数而不同。
|
||
|
||
## 八、关键代码解析
|
||
|
||
### 8.1 文件不存在时返回空列表
|
||
|
||
```python
|
||
if not data_file.exists():
|
||
return []
|
||
```
|
||
|
||
第一次运行还没有任务文件，这不是错误。返回空列表后，程序就可以从第一条任务开始添加。
|
||
|
||
### 8.2 装饰器记录调用
|
||
|
||
`@log_call` 会在原函数执行前输出函数名，但不会改变原函数的参数和返回值。它适合为多个关键操作增加相同的提示。
|
||
|
||
### 8.3 生成器逐条提供未完成任务
|
||
|
||
```python
|
||
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 保存和读取的方向；
|
||
- 能说明本项目中异常处理、推导式、生成器、装饰器和类型注解分别在哪里使用；
|
||
- 能按题目完成三个练习模块；
|
||
- 再次运行练习程序时，能够读取上次保存的任务；
|
||
- 已完成第二阶段的综合项目，具备进入第三阶段“面向对象编程”的基础。
|