如果你的第一次代码作业只是“能跑”那么第二次作业大概率会逼你重新想清楚一件事同一个功能怎么写才不会让两个月后的自己看得一头雾水。我最近刚把第二次作业交上去项目是一个文件归档整理工具——输入一个乱糟糟的下载目录按后缀名和自定义规则把图片、文档、压缩包自动归入对应子目录。第一版大约三百行功能能跑但跑完我出了一身冷汗第二版我拆成了六个模块补了配置、日志和预演模式等于从头重写。这篇不是讲大道理就是把这版代码从设计到踩坑的完整过程摊开给你看。如果你也正在做类似“第二版重构”的练手项目或者想从“能跑就行”过渡到“能维护、能交代”这里面的取舍和问题排查思路应该能帮上忙。1. 第一次作业交上去之后问题清单比代码还长第一次作业的题目其实很简单给定一个源目录递归扫描所有文件按照文件类型移动到目标目录的分类子文件夹中。我用了三天写了个三百行的 Python 脚本跑通测试集的那一刻确实挺爽但交上去之后被批注里那句“你有没有考虑过重名文件”问得哑口无言。冷静下来整理问题发现根本不只重名这一处。我把踩到的问题分了四类列在下面这个表里后面逐个展开说。问题分类具体表现带来的后果逻辑全堆在 main() 里一个函数内嵌套四层循环和条件判断想加一个文件分类要翻几十行代码分类规则写死在代码里扩展名映射表 hardcode 在文件头部新增类别必须改源码非技术用户完全没法用重名文件直接覆盖用 os.replace 处理同名文件差点把一个重要文件覆盖掉没有任何日志和预演跑完无法确认哪些文件被移动了出问题只能全部重新跑一遍1.1 所有逻辑都堆在 main() 里第一处着火点第一次作业的代码结构基本长这样一个 main()从 sys.argv 里读入源目录和目标目录然后 os.walk 遍历再根据扩展名判断分类最后 shutil.move。听着没什么问题但把所有步骤串在一个函数里之后每一层循环之间都夹着两三个 if 判断整段代码就像一团揉在一起的面。真正让我意识到问题的时刻是第二次作业要求加一个“跳过隐藏文件”的功能。按理说只是几行代码的事但我在 main() 里翻了很久才找到遍历逻辑的入口而且改完还要担心会不会影响后面移动文件的代码。那次改动花了将近一个小时而实际新增的逻辑只有三行。1.2 分类规则写死在代码里第二处着火点第一版代码开头长这样ext_to_category { .jpg: images, .jpeg: images, .png: images, .gif: images, .pdf: documents, .doc: documents, .docx: documents, .zip: archives, .tar: archives, }当时觉得挺直观的但一放到真实场景就露馅了。测试集里有一批扫描件是.PDF大写后缀而字典里只有小写.pdf结果这些文件全被丢进了“其他”目录。更麻烦的是我的朋友拿这个脚本去整理他的设计素材目录想加一个svg分类看到代码里那一长串字典之后直接放弃了——他不会改代码这个工具对他来说就是一次性的。这个教训让我后来特别坚持一件事业务规则要外置不能埋在代码里。分类规则应该是配置文件里可以改的内容而不是程序员写死的常量。1.3 覆盖式移动最让我后怕的一个缺陷第一次作业里移动文件用的是shutil.move但遇到目标目录已经存在同名文件的情况时我当时图省事直接加了句os.replace。也就是说新文件会悄悄覆盖掉旧文件。结果在真实测试时目录里有个叫“需求文档.docx”的文件刚好另一个子目录也有一份同名但内容完全不同的草稿版程序跑完之后原来的草稿版就这么没了。虽然那次不是工作文件但那种“数据无声无息消失”的感觉太糟糕了。从那以后我给自己定了个规矩任何覆盖类操作要么预留确认机制要么把旧文件自动改名保留。人眼发现不了的问题程序一旦跑起来就是灾难。1.4 没有日志出了问题只能靠猜第一版跑完我根本不知道哪些文件被移动了哪些被跳过了。如果中间有一半文件处理失败程序会继续往下跑还是直接退出我当时完全靠看文件数去猜。更难受的是如果某个文件因为权限问题移动失败程序抛个异常就停了前面的文件已经移动后面的文件没处理想要重跑还得先把前面的文件手动挪回去。这个场景想必很多人熟悉你愿意写一个月的代码却不愿意花半小时让程序告诉你在干什么。这不是技术问题是意识问题。2. 推倒重写还是打补丁我的判断逻辑按常规思路第二次作业最省力的方式是保留旧脚本在原有代码上加配置、加重名处理、加日志。但我认真评估之后还是决定重写。理由不是“旧代码不够好”而是修修补补的真实成本已经超过了重写的成本而且需求本身已经变了。2.1 先算一笔账修复这些缺陷需要动多少地方我列了一个改动清单逐条估算可能触及的代码路径重名文件要改为“自动改名/跳过/覆盖”三选一策略这会触及移动文件的整个流程。分类规则要外置意味着扩展名映射表要从代码里挪到配置加载层main() 里的分类逻辑几乎全部要改。加日志需要在入口、扫描、分类、移动、冲突处理这五个位置插入打印点。加预演模式需要把“移动文件”这个动作抽象出一个可替换层。隐藏文件和忽略目录选项会影响遍历逻辑本身。算下来旧代码里超过一半的函数体都要动。再加上旧代码没有模块边界改一处就可能影响另一处。这种情况下打补丁的实际工作量其实和重写差不多但代码会变得更拧巴。2.2 需求变了补丁结构撑不起新功能第一次作业的功能定位是“自己跑一遍做个作业交差”。第二次作业的定位变成了“这个工具要能给别人用还要能应对不规则目录”。这两者的差别不只是多几个功能的事。给别人用意味着配置文件友好、错误信息清楚、操作前能预览应对不规则目录意味着要处理特殊文件名、权限异常、符号链接、跨磁盘移动这类边缘情况。这些需求都会触及核心数据流而不是外围功能。老结构里根本没有“配置加载层”也没有“统一冲突处理入口”想打补丁都不知道把补丁缝在哪。业界常说“重写是最后的选项”但对一个单文件小脚本来说重写的成本没那么高风险也完全可控。判断标准很简单如果改动会触及超过一半的代码路径而且旧边界已经被打穿过那重构的收益远大于损失。2.3 重写不是从零开始第一次作业留下的知识地图做决定之前我还有点犹豫觉得重写就是抛弃上一次的经验。但实际上第一次作业已经给了我一张非常宝贵的知识地图我知道测试目录的结构长什么样哪些子目录容易藏大文件。我知道文件类型分布很脏光图片就有 jpg、jpeg、png、webp、gif、svg 好几种还有大写后缀混在里面。我手里有一份边界情况清单权限拒绝、隐藏文件、超长路径、重名文件。这些东西在第一版里是踩坑记录在第二版里就直接变成了需求文档和测试用例。比如“忽略隐藏文件”“自动重命名策略”“大写后缀归一化”这些特性全是从第一版的实际故障里提炼出来的。所以我不觉得重写是在否定第一次作业更像是对那版代码做了一次全面复盘然后把这些经验固化进新设计。3. 第二次作业的骨架从入口到落盘的完整数据流确定重写之后我做的第一件事不是写代码而是画清楚一条数据流用户输入命令之后程序到底按什么顺序处理文件每个环节的输入输出是什么。这条数据流是整个第二版的地基。3.1 从命令行参数到日志落盘一次任务的生命周期第二次作业的完整流程是这样的解析命令行参数拿到源目录、目标目录、配置文件路径、是否预演。加载 YAML 配置文件解析分类规则、冲突策略、忽略项。扫描源目录得到所有待处理文件的路径列表。对每个文件调用分类器算出应该进入哪个分类目录。对每个文件调用冲突检测计算出最终的目标文件名。如果是预演模式只打印计划如果是正式执行先建目录再移动文件。无论预演还是执行每一步都写进日志。流程看起来平平无奇但这条主线保证了每个模块的职责是单一的。扫描器不知道什么叫“分类”分类器不知道什么叫“移动”移动器不知道什么叫“规则”。任何环节出问题我可以单独测它不会牵连其他部分。3.2 模块划分与依赖规则最终代码拆成了六个模块加一个入口文件每个模块大致行数如下模块职责约行数cli.py参数解析、入口调度90config.py读取和校验 YAML 配置130scanner.py递归扫描目录输出文件路径列表110classifier.py根据规则给文件打分类标签100resolver.py冲突检测、目标文件名生成80runner.py执行移动或预演调度前序模块120总的代码量比第一版的 300 行长了不少但每个模块都可以单独写测试。依赖方向也很明确cli 调用 runnerrunner 依赖 scanner、classifier、resolverconfig 只被 cli 和 runner 引用。反向依赖一律不允许这个约束让后续改配置格式或者换日志方案时不会波及核心逻辑。3.3 配置文件的定位把决策权从代码里拿出来第二次最大的变化是加了一个配置文件用的是 YAML。原因很直接Python 的 dict 字面量写进代码里对会用编辑器的人来说还行但任何想调整规则的人都要面对“改代码”的心理门槛。YAML 文件则不同它看起来就是一份配置文档改起来没有心理负担。我的配置长这样source_dir: ./inbox target_root: ./archive fallback_dir: others conflict_policy: rename # rename / skip / overwrite ignore_hidden: true ignore_dirs: - .git - __pycache__ follow_symlinks: false rules: - name: images extensions: [.jpg, .jpeg, .png, .gif, .webp, .svg] - name: documents extensions: [.pdf, .doc, .docx, .txt, .md] - name: spreadsheets extensions: [.xls, .xlsx, .csv] - name: archives extensions: [.zip, .tar, .gz, .7z] - name: backup_files regex: ^backup.*这里有个设计细节想提一下fallback_dir的存在很重要。任何一套分类规则都不可能覆盖全部文件类型与其让未匹配文件乱糟糟留在原目录不如给它们一个明确的归宿这样用户至少知道“没分进去的东西去哪儿了”。3.4 数据结构的三个基石第二版代码里有三个核心数据结构分别是FileRecord、Rule和ConflictPolicy。from dataclasses import dataclass from enum import Enum from pathlib import Path dataclass class FileRecord: source_path: Path # 原始文件完整路径 category: str # 分类名称 target_name: Path # 目标路径已由 resolver 处理过冲突 dataclass class Rule: name: str extensions: list[str] None regex: str None class ConflictPolicy(str, Enum): RENAME rename SKIP skip OVERWRITE overwriteFileRecord像一条流水线上的工件每个环节都往上面挂信息扫描器填source_path分类器填categoryresolver 填target_name。这样到执行阶段runner 只需要遍历List[FileRecord]然后调用移动函数不需要重新访问文件系统。所有决策都在内存里做完执行阶段只是一个落盘动作理解起来非常直观。4. 关键实现细节扫描、分类、预演、落盘这一章挑四个关键点展开扫描器为什么换用 scandir分类引擎怎么从字典升级成规则引擎预演与真实模式如何共用一套核心逻辑以及日志系统怎么设计才不会被忽略。4.1 扫描器为什么我放弃 os.walk 改用 os.scandir第一版用的是os.walk代码短用起来也简单。但第二版我换成了os.scandir加显式栈遍历。原因有两个第一是性能第二是对遍历过程的可控性。os.walk在内部其实也是调用scandir但它会把目录树整个展开对每个目录返回一个列表。对于归档工具这种“只关心文件、不需要目录层级信息”的场景os.walk会额外维护很多用不到的目录结构。显式维护一个栈之后我可以直接在遍历过程中过滤符号链接、隐藏目录和忽略目录不用事后二次筛选。核心扫描代码大致长这样import os from pathlib import Path def scan_files(root: Path, ignore_hidden: bool True, ignore_dirs: set[str] | None None, follow_symlinks: bool False) - list[Path]: ignore_dirs ignore_dirs or set() visited set() stack [root] result [] while stack: current stack.pop() try: real current.resolve() except OSError: continue if real in visited: continue visited.add(real) with os.scandir(current) as it: for entry in it: if ignore_hidden and entry.name.startswith(.): continue if entry.is_dir(follow_symlinksfollow_symlinks): if entry.name not in ignore_dirs: stack.append(Path(entry.path)) elif entry.is_file(): result.append(Path(entry.path)) return result注意这里用了entry.is_dir(follow_symlinksfollow_symlinks)。第一版没有这个参数结果测试时遇到了符号链接导致的死循环这个坑后面会单独讲。在扫描器这一层就把符号链接处理掉后面分类和移动就少了很多麻烦。4.2 分类引擎从扩展名映射到规则匹配分类器的设计目标是让规则完全外置。代码里不出现任何具体扩展名只负责取规则、做匹配、返回结果。import re from pathlib import Path from config import Rule def classify(path: Path, rules: list[Rule], fallback: str) - str: lower_suffix path.suffix.lower() lower_name path.name.lower() # 纯扩展名规则优先属于同一个优先级层级 for rule in rules: if rule.extensions and lower_suffix in rule.extensions: return rule.name # 正则规则次之因为它匹配强度更高、误伤风险也更大 for rule in rules: if rule.regex and re.search(rule.regex, lower_name): return rule.name return fallback这里有一个设计上的取舍为什么扩展名规则优先于正则规则因为扩展名匹配是“确定的”一个文件叫backup.tar它既可能是备份文件也可能是归档文件但.tar后缀是客观事实。正则表达式大多表达的是用户的模糊意图容易出现误命中。所以我把扩展名匹配放在第一轮正则匹配放在第二轮并且在文档里明确写了“扩展名优先级高于正则规则同一类规则内按配置顺序生效”。4.3 预演和真实模式只允许存在一套核心逻辑很多工具做预演的方式很粗暴复制一份代码把移动函数注释掉改个 print 就完事。这种做法最大的问题是预演逻辑和执行逻辑很容易出现分叉——预演里没报冲突正式执行却撞车了。我的做法是把“计划生成”和“计划执行”分离。runner 里只有一份生成计划的代码预演模式只是“执行部分换个落盘函数”。def build_plans(records: list[FileRecord], dry_run: bool False) - None: for record in records: if dry_run: logger.info([DRY RUN] %s - %s, record.source_path, record.target_name) else: plan_and_move(record) def plan_and_move(record: FileRecord) - None: final_path ensure_no_conflict(record.target_name) # 执行前二次检查 if final_path is None: logger.warning(SKIP %s: 目标文件已存在, record.source_path) return record.target_name final_path final_path.parent.mkdir(parentsTrue, exist_okTrue) shutil.move(str(record.source_path), str(final_path)) logger.info(MOVED %s - %s, record.source_path, final_path)这段代码最关键的是ensure_no_conflict在预演和执行时都被调用预演时它只做检测并返回“如果冲突会怎么处理”执行时它做同样的检测并真正生成新路径。两段逻辑是同一份代码不会出现“预演说没问题执行却发现问题”的状态差。当然严格来说预演和执行之间仍存在时间窗口所以执行阶段还会再调一次ensure_no_conflict这就是 5.3 节要讲的坑。4.4 冲突解决三种策略与文件名生成冲突策略是第二次作业里用户最关心的功能因为第一版直接覆盖数据的阴影还在。resolver 里实现了三种策略rename目标已存在时自动生成带时间戳的新文件名。skip目标已存在时跳过该文件并记录警告日志。overwrite覆盖旧文件仅在目标文件属于同一分类时允许。rename 策略的文件名生成逻辑from datetime import datetime def rename_target(target_path: Path) - Path: timestamp datetime.now().strftime(%Y%m%d_%H%M%S) return target_path.with_name(f{target_path.stem}_{timestamp}{target_path.suffix})有个细节是overwrite 策略如果不做约束就是危险的。我加了一条规则覆盖只允许发生在“同分类目录”内如果目标文件所在的目录和当前文件分类不一致则拒绝执行并记录错误。这样就算用户手滑配置了全局覆盖跨分类目录的数据也不会被误伤。4.5 日志设计程序必须能自己说清楚它干了什么第二版日志分了两个通道控制台和文件。控制台只输出进度和警告文件里记录完整细节。初始化的核心代码import logging def setup_logging(log_path: str) - None: file_handler logging.FileHandler(log_path, encodingutf-8, errorsbackslashreplace) console_handler logging.StreamHandler() formatter logging.Formatter(%(asctime)s | %(levelname)s | %(message)s) file_handler.setFormatter(formatter) console_handler.setFormatter(formatter) root logging.getLogger() root.setLevel(logging.INFO) root.addHandler(file_handler) root.addHandler(console_handler)这里errorsbackslashreplace不是随手加的而是踩过坑之后的补丁。日志记录的内容包括每次移动的源路径、目标路径、冲突处理方式、跳过的原因。跑完一次归档任务翻一遍日志就能完整还原程序做了什么不需要人肉去数文件。5. 测试阶段踩过的四个坑以及完整排查链路第二版写完之后我满怀信心地拿测试目录跑了一遍结果一波三折。下面这四个问题每个都是我实际遇到、又花了不少时间排查的每个都有完整的“现象—定位—原因—修复”链路。5.1 日志写入碰上特殊文件名进程直接退出现象程序跑到大约第 137 个文件时日志输出突然中断控制台抛出UnicodeEncodeError进程直接退出。而此时前面的文件已经移动了后面的还没处理整个任务卡在一个很尴尬的中间状态。定位我先在日志 handler 里临时加了一个 try/except把出问题的文件名用repr()打印出来。结果发现触发日志崩溃的文件名里包含\udce6\udcb1这样的代理区字符。原因在 Windows 上当某个文件的文件名无法用当前代码页解码时Python 的os.scandir会借用surrogateescape机制把无法解码的字节映射到 Unicode 的保留代理区。这些字符在内存里是“合法”的字符串但一尝试按默认编码比如 GBK 或者 UTF-8写入文件解码就炸了。修复给FileHandler显式指定encodingutf-8和errorsbackslashreplace。这样即使遇到代理区字符也只是把无法表示的字节转成\udce6这类字面量写进日志不会中断进程。验证重新跑完整测试集日志完整落盘文本内容也仍然可读。这个修复只改了一行代码但如果不知道surrogateescape这个机制估计得排查到怀疑人生。5.2 符号链接把扫描带进死循环现象扫描一个包含软链接的目录时程序运行时间异常久进程占满了一个 CPU 核心像陷入死循环一样。定位我在scandir循环里临时加了当前路径打印肉眼看到同一个目录的 real path 反复出现尤其是符号链接指回父目录的情况。检查visited集合之后发现压栈时用的是Path(entry.path)路径本身带着符号链接前缀而visited里存的是real路径。符号链接路径每次都能通过visited检查导致它反复被入栈。原因entry.is_dir()默认会跟随符号链接所以一个指向父目录的链接会被当成“新目录”继续遍历。理论上visited能在第二次遇到时拦住它但因为入栈路径和判定路径不一致这个拦截完全失效了。修复扫描时对目录项显式传入follow_symlinksFalse更关键的是统一使用resolve()之后的路径作为遍历依据并且每次入栈前先检查visited。同时我还在配置里加了follow_symlinks选项默认 False因为归档工具一旦跟着符号链接跑很容易把同一份数据当作多份文件处理。验证构造一个“目录 A 里放了指向 A 自身的符号链接”的测试用例扫描正常结束无重复文件记录。5.3 预演一切正常正式执行却触发冲突现象我先用--dry-run跑了一遍所有文件都计划好了没有一条冲突警告。紧接着正式执行日志里却连续出现“目标文件已存在自动重命名”的提示。定位一开始我怀疑是dry_run的逻辑分叉了导致预演和执行走了不同的冲突检测路径。仔细对比两段代码才发现它们用的是同一个函数理论上行为应该一致。然后我检查了源目录和目标目录发现目标目录里有一个同名文件是上一次手动测试留下的而预演模式跑的时候它还不存在。原因预演模式不会创建目标目录也不会真正移动文件所以它检测到的文件系统状态是“预演那一刻”的状态。正式执行时目录状态可能已经因为外部操作发生了变化甚至只是另一个用户手动放了一个同名文件进来。预演和执行之间存在时间窗口任何状态都可能变。修复把冲突检测拆成两层——预演时做一次“计划展示”执行时再做一次“安全闸门”。plan_and_move里的ensure_no_conflict就是安全闸门不管预演时怎么判断真到移动之前都必须再查一次。这两层共用同一个检测函数只是调用时机不同。验证故意在预演之后往目标目录放一个同名文件再次执行程序正确触发冲突处理不会再盲目标覆盖。这条经验也告诉我要把“预演”的宣传文案从“与真实执行完全一致”改成“仅作为预览参考执行阶段仍会二次校验”。5.4 规则重叠导致文件进错目录现象某次归档之后一个叫backup_projects.tar.gz的文件没有进入 archives 目录而是被放进了 backup_files 目录。用户看到之后很困惑这明明是个压缩包为什么不是归档定位测试配置里 backup_files 规则用的是正则^backup.*而 archives 规则用的是扩展名列表。分类器里正则规则排在扩展名规则之前所以文件名里的backup前缀命中正则规则并返回了 backup_files。原因规则匹配顺序设计有误。正则规则表达的是“名字里带什么”扩展名规则表达的是“客观文件类型”。“名字里带 backup”的误伤概率远高于“后缀是 .tar.gz”所以后者应当拥有更高优先级。修复把分类器改成两轮匹配——第一轮只跑纯扩展名规则第二轮跑正则规则。并在配置文档里写明“扩展名规则优先于正则规则同类规则内部按配置文件顺序生效”。另外我在日志里加了一个字段每次分类时把匹配到的所有规则名都记录下来便于发现规则重叠。验证构造一个文件名同时满足“某扩展名规则”和“某正则规则”的测试用例断言它归入扩展名规则对应的分类。同时把日志里的命中规则列表打印出来变成配置调优的依据。6. 两版代码的量化对比数字不会说谎写完第二版之后我拿着同一批测试集分别跑了一遍两版代码做了一次量化对比。数据本身不惊艳但差距背后的原因值得说清楚。6.1 核心指标对照表指标第一次作业第二次作业总代码行数约 300 行约 570 行模块数16可配置项015重名文件策略直接覆盖rename / skip / overwrite预演模式无有日志无文件控制台双通道测试用例017全量处理耗时约 2 万文件约 210 秒约 40 秒人工确认重名文件耗时手动改了 4 个文件名0代码行数增多这件事我完全预料到了模块化本来就会带来一些额外的边界代码。但 2 万文件的处理耗时从 210 秒降到 40 秒确实超出预期。6.2 性能提升的主要原因第一版慢在几个地方os.walk之后每拿到一个文件路径就用os.path.join拼接然后反复调用os.path.exists检查目标路径每次判断分类时还硬编码一串字典查找。第二版改用os.scandir之后目录项信息一次取回不需要为每个文件重复发起系统调用。另一个优化点是 mkdir 的时机第一版每移动一个文件就os.makedirs一次第二版提前把所有分类目录建好执行阶段省掉了大量重复的目录创建与 stat 检查。另外由于分类规则从代码挪到了配置程序不再需要为每个文件做一次字典遍历和手工判断规则匹配逻辑本身也精简了不少。6.3 除了代码行数和耗时我更看重的三个隐性收益第一项是“可测试性”。第二版我能针对扫描器、分类器、resolver 分别写测试第一版完全没有这个可能。第二项是“可配置性”。现在换个文件类型规则、改个冲突策略只需要动配置文件不需要重跑部署流程。第三项是“可解释性”。看日志就能还原一次归档任务的全部过程排障不再靠猜。这三个收益在指标表里没有直接体现但对我来说比性能数字更重要。6.4 后续可以继续扩展的方向这版做完之后我心里还有几个很自然的扩展方向列在这里作为后续参考配置文件的 schema 校验。现在配置写错了只会运行时报错想做成启动时预检。增量归档。给文件算 hash 并记录已处理集合下次只扫描新增文件。规则优先级可视化。在预演日志里输出每个文件命中的全部规则帮助调优配置文件。跨磁盘移动的安全校验。shutil.move在不同盘之间会退化成复制删除这时需要考虑磁盘空间和中断恢复的问题。这些方向都是在第二版基础上自然而然长出来的不是空想的功能列表。最后说点个人体会。我在写第二次作业的过程中最大的转变不是学会了 scandir 还是 YAML而是开始把“程序跑通”和“程序可用”分开看。跑通只需要对测试集负责可用则要对自己的使用场景、对可能的误操作、对未来的维护者负责。第一版的每一处跳过的异常处理、每个写死的映射表都像是给自己挖的坑第二版把这些坑填上之后整个工具才真正变成一个“可以交给别人用”的东西。如果你也在写自己的第二次作业我的建议很简单先花一小时把第一版的问题列成清单再决定哪里补、哪里重写比一头扎进代码里更值得。工具不会自己说出它哪里疼但你会从每一次“程序让你失望”的时刻里找到答案。