40｜综合项目：命令行学习记录管理器

这套课程按知识依赖排列。本篇的前置知识是：第 01～39 篇。学完后，你应该能够综合函数、类、JSON、异常和文件路径完成小项目。

本篇要解决的问题

本篇只处理“综合项目：命令行学习记录管理器”这一件事。示例基于 Python 3.14.6，在 macOS 环境核验；除明确标注的终端命令外，代码本身只使用 Python 标准能力。

先看清一个容易误解的细节

一次命令从用户输入开始，先解析和校验，再交给业务对象处理，随后持久化为 JSON，最后向用户显示结果。每一层只承担一种职责。

核心概念

• 输入层负责接收文本，业务层负责校验与状态，存储层负责 JSON 文件。
• 综合项目先完成最小可运行主流程，再增加读取、列表展示和完成状态。
• 实际扩展前先为 add() 和存储边界补充测试。

跟着示例运行

把下面代码保存到本课脚本并运行：

import json
from pathlib import Path

class LearningRecords:
    def __init__(self, file_path):
        self.file_path = Path(file_path)
        self.items = []

    def add(self, title):
        title = title.strip()
        if not title:
            raise ValueError("课程名称不能为空")
        self.items.append({"title": title, "done": False})

    def save(self):
        with self.file_path.open("w", encoding="utf-8") as file:
            json.dump(self.items, file, ensure_ascii=False, indent=2)

records = LearningRecords("learning-records.json")

try:
    title = input("输入已学习课程：")
    records.add(title)
    records.save()
except ValueError as error:
    print("无法保存：", error)
else:
    print("已保存 1 条学习记录")

预期结果：

输入有效课程名后创建 learning-records.json，并显示已保存 1 条记录

输出中包含环境路径、集合元素或日志格式时，具体文字和顺序可能随本机环境变化；判断是否成功应以本篇说明的关键结果为准。

按执行顺序拆开看

1. 输入层取得课程名后，add() 去除两端空白并验证非空，再把基础字典加入内存列表。
2. save() 只负责把当前列表写入 JSON；异常路径显示原因，成功路径确认保存结果。

再看一个具体细节

综合项目先把职责拆开，避免所有代码堆进输入循环。

输入层只接收命令，业务层维护有效状态，存储层读写 JSON；层与层之间通过明确数据交接。

再看一个具体细节

内存列表和 JSON 文件是两个不同时间点的状态。

业务操作先修改内存，保存后文件才同步；程序重新启动时还需要 load() 把文件状态恢复到内存。

初学者容易混淆的地方

• 把输入、校验、业务处理和文件写入全塞进一个长循环，后续难以测试。
• 每次启动都用空列表覆盖旧文件。本示例是最小版本，练习中的 load() 是下一项必要扩展。

练习

1. 增加 load()，文件不存在时从空列表开始。
2. 增加按序号标记完成的功能，并校验序号范围。
3. 把输入循环放进 main()，通过 __name__ 控制程序入口。

练习应先独立完成，再通过增加 print 输出或检查文件内容观察中间状态。当前课程尚未讲到的能力，不要求提前搜索复杂写法。

本篇边界

本篇目标是综合函数、类、JSON、异常和文件路径完成小项目。没有展开的高级机制会放到后续课程；先确保能够解释示例中每一行代码，再进入下一篇。