简介本资源是面向Python初学者与算法进阶学习者的Advent of Code历年真题实战解决方案合集覆盖2017–2020年全部挑战聚焦递归、图遍历、动态规划、位运算、计算几何等核心算法场景助力系统性提升编程思维与工程实现能力。压缩包共240个文件含152个Python源码按年份/日期组织如day01.py至day25.py、83个原始输入数据文件.input、4张说明性PNG图示及1个.gitignore总大小989KB结构清晰、开箱即用。已有137人下载学习适合对照题目自主调试、分析解法差异或复用输入处理与通用工具函数。代码充分运用Python内置模块itertools/collections/math与惯用写法生成器、列表推导式每份脚本均包含输入解析与双子题逻辑实现可直接运行验证是理解算法落地细节与优化实践的优质参考样本。1. 这不是刷题合集而是一套可复用的 Advent of Code 解题工程模板覆盖 2017–2020 全年 Python 实现含输入解析、测试驱动、结构化日志与自动校验你有没有试过年底打开 Advent of CodeAoC链接点开 Day 1写完两道题第二天就卡在输入格式解析上第三天发现昨天的代码根本没法复用第四天开始手动复制粘贴 input.txt 到每个脚本里第五天……干脆关掉浏览器这不是懒是原始解法在工程维度上的系统性失能。我当年就是这么翻车的——2017 年靠硬编码撑到 Day 122018 年改用全局变量传 input结果 Day 15 的递归爆栈后连 debug 日志都找不到源头。直到我把所有年份的解法重构成统一骨架才真正把 AoC 从「节日彩蛋」变成「年度 Python 工程训练场」。这份资源不是答案库而是一套经过四年实战迭代的解题基础设施它强制你把输入解析、逻辑分层、测试验证、结果校验全部模块化它不教算法但让你每次写solve_part_one()时心里清楚input_data是什么类型、parse_input()返回什么结构、test_day_03_part_two()跑的是哪条边界用例。适合所有已掌握基础 Python函数/类/文件读写、想把 AoC 当作真实项目来练手的开发者——尤其适合那些总在 Day 5 就放弃、或写完代码不敢改怕崩的中阶实践者。2. 为什么必须重构 AoC 解题流程从「单文件脚本」到「可测试、可复用、可追踪」的工程化结构Advent of Code 的天然设计是「每日一题、独立输入、无上下文依赖」这看似友好实则埋下三大工程隐患一是输入格式碎片化2017 Day 4 是空格分隔单词2019 Day 12 是多行坐标速度2020 Day 17 是二维网格带三维扩展每次都要重写解析逻辑二是测试缺失导致修改即崩溃比如 Day 8 的寄存器指令加个负数就让条件跳转失效没测试根本不敢动三是结果验证黑盒化提交答案后才知对错无法本地快速断言。我见过太多人把 25 个.py文件散落在一个文件夹里每个文件开头都是with open(input.txt) as f: ...这种结构在 Day 10 还能扛在 Day 22 的图遍历状态压缩组合题面前必然崩盘。所以这套模板的核心不是“怎么解题”而是“怎么让解题过程本身具备可持续性”。2.1 目录结构设计按年份隔离 按日粒度组织 统一入口协议整个资源采用严格分层目录杜绝跨年耦合aoc-solution-framework/ ├── aoc/ # 核心包定义通用接口与基类 │ ├── __init__.py │ ├── common.py # 输入读取、日志初始化、结果校验工具 │ └── base.py # BaseSolver 抽象类强制实现 parse_input/solve_part_one/solve_part_two ├── 2017/ # 每年独立子包互不 import │ ├── __init__.py │ ├── day_01.py # 必须继承 aoc.base.BaseSolver │ ├── day_02.py │ └── tests/ # 对应测试与 day_x.py 同名 │ ├── __init__.py │ ├── test_day_01.py │ └── test_day_02.py ├── 2018/ │ ├── day_01.py │ └── tests/ ├── 2019/ ├── 2020/ └── run_all.py # 统一执行入口python run_all.py --year 2020 --day 5提示aoc.base.BaseSolver是关键契约。任何day_x.py必须实现三个方法parse_input(self, raw_input: str) - Any输入转结构化数据、solve_part_one(self, parsed_input: Any) - Any核心逻辑、solve_part_two(self, parsed_input: Any) - Any第二问。这个抽象层让run_all.py可以无差别加载任意年份任意日期的解法无需硬编码路径或函数名。2.2 输入解析标准化用common.read_input()统一处理路径、缓存与编码AoC 官网下载的 input 总是纯文本但不同年份的存放位置、命名规则、编码方式2017 部分 input 含 UTF-8 BOM千差万别。手动处理极易出错。common.read_input()封装了全部细节# aoc/common.py import os from pathlib import Path def read_input(year: int, day: int, strip: bool True) - str: 安全读取指定年份/日期的 input.txt 自动查找路径./{year}/input/day_{day:02d}.txt 或 ./{year}/input.txt 自动处理 BOM若文件以 UTF-8 BOM 开头自动 strip 缓存机制首次读取后存入内存 dict后续调用直接返回避免重复 IO cache_key f{year}_{day} if cache_key in _INPUT_CACHE: return _INPUT_CACHE[cache_key] # 构建候选路径优先找 day-specific再找年份级 candidates [ Path(f{year}/input/day_{day:02d}.txt), Path(f{year}/input.txt), Path(f{year}/inputs/day_{day:02d}.txt), ] for path in candidates: if path.exists(): content path.read_text(encodingutf-8-sig) # utf-8-sig 自动处理 BOM if strip: content content.strip() _INPUT_CACHE[cache_key] content return content raise FileNotFoundError(fInput file not found for year {year}, day {day} in any standard location)这段代码解决的不是“能不能读”而是“读得稳不稳”。encodingutf-8-sig是血泪经验——2017 Day 11 的 input 包含特殊符号用普通utf-8会抛UnicodeDecodeError_INPUT_CACHE是性能刚需跑全量测试时避免 100 次重复文件 IO路径自动探测则让迁移旧代码时只需移动文件夹不用改一行读取逻辑。2.3 测试驱动开发TDD落地每个 day_x.py 必配 test_day_x.py且强制覆盖样例输入模板要求每个day_x.py必须有同名tests/test_day_x.py且至少包含两个测试用例test_sample_part_one和test_sample_part_two。这是防止“本地跑通、官网提交错”的后悔药。以 2020 Day 1 为例# 2020/tests/test_day_01.py import pytest from aoc.common import read_input from aoc._2020.day_01 import Solver def test_sample_part_one(): # 使用官方提供的 sample input非真实 input sample_input 1721\n979\n366\n299\n675\n1456 solver Solver() parsed solver.parse_input(sample_input) result solver.solve_part_one(parsed) assert result 514579 # 1721 * 299 def test_sample_part_two(): sample_input 1721\n979\n366\n299\n675\n1456 solver Solver() parsed solver.parse_input(sample_input) result solver.solve_part_two(parsed) assert result 241861950 # 1721 * 979 * 366关键点在于sample_input是硬编码字符串而非读取文件。这样测试完全脱离网络和文件系统秒级执行。pytest运行时test_sample_part_one失败意味着你的parse_input()或solve_part_one()逻辑有误test_sample_part_two失败则说明第二问的边界处理如三数之和 vs 两数之和没到位。这种测试不是锦上添花而是每次修改代码前的必过安检门。3. 核心解题模块实战以 2019 Day 12天体模拟为例拆解物理建模、状态快照与周期检测2019 Day 12 是 AoC 中少有的需要建模物理系统的题目四个天体在三维空间中受引力相互作用需模拟 1000 步后计算总能量并进一步求出系统状态重复的最小周期。它完美暴露了原始解法的脆弱性——用一堆x, y, z, vx, vy, vz变量硬编码第 500 步后变量名已乱成浆糊。而本模板的解法是把它彻底对象化、可序列化、可断言。3.1Planet类设计用 dataclass 封装状态用__post_init__强制约束# 2019/day_12.py from dataclasses import dataclass from typing import List, Tuple dataclass class Planet: x: int y: int z: int vx: int 0 vy: int 0 vz: int 0 def __post_init__(self): # 强制初始化为整数防止 float 混入影响后续哈希与周期检测 self.x int(self.x) self.y int(self.y) self.z int(self.z) self.vx int(self.vx) self.vy int(self.vy) self.vz int(self.vz) property def potential_energy(self) - int: return abs(self.x) abs(self.y) abs(self.z) property def kinetic_energy(self) - int: return abs(self.vx) abs(self.vy) abs(self.vz) property def total_energy(self) - int: return self.potential_energy * self.kinetic_energy def apply_velocity(self): self.x self.vx self.y self.vy self.z self.vz def to_tuple(self) - Tuple[int, int, int, int, int, int]: 返回可哈希元组用于周期检测 return (self.x, self.y, self.z, self.vx, self.vy, self.vz)dataclass省去样板__init____post_init__是安全阀——确保所有字段是int因为后续周期检测要用tuple做哈希键float会导致精度漂移。to_tuple()方法是关键设计它把行星当前完整状态位置速度压缩成一个不可变元组为下一步的全局状态快照提供原子单元。3.2System类封装解耦模拟逻辑与状态管理支持 step-by-step 与 batch-runclass System: def __init__(self, planets: List[Planet]): self.planets planets.copy() # 防止外部修改影响内部状态 def get_state_snapshot(self) - Tuple[Tuple[int, ...], ...]: 获取当前系统完整状态快照((p1.x,p1.y,...), (p2.x,p2.y,...), ...) return tuple(p.to_tuple() for p in self.planets) def apply_gravity(self): 计算所有行星间的引力作用更新速度 n len(self.planets) for i in range(n): for j in range(i 1, n): p1, p2 self.planets[i], self.planets[j] # x 方向 if p1.x p2.x: p1.vx 1 p2.vx - 1 elif p1.x p2.x: p1.vx - 1 p2.vx 1 # y, z 同理... if p1.y p2.y: p1.vy 1 p2.vy - 1 elif p1.y p2.y: p1.vy - 1 p2.vy 1 if p1.z p2.z: p1.vz 1 p2.vz - 1 elif p1.z p2.z: p1.vz - 1 p2.vz 1 def step(self): 执行单步先应用引力改速度再应用速度改位置 self.apply_gravity() for p in self.planets: p.apply_velocity() def run_steps(self, n: int) - None: 批量运行 n 步内部可加进度日志调试用 for i in range(n): self.step() if i % 100 0 and i 0: print(fStep {i}/{n} completed) def total_energy(self) - int: return sum(p.total_energy for p in self.planets)这个System类是解题的中枢。它把“模拟”这件事从主逻辑中抽离出来step()方法清晰定义了物理顺序先算力再动位置get_state_snapshot()返回可哈希元组为周期检测铺平道路。注意run_steps()中的print不是生产代码而是调试开关——当怀疑周期过长时打开它看是否卡死。3.3 周期检测实现用 set 记录历史状态O(1) 查重Day 12 第二问要求找出系统状态重复的最小步数。暴力思路是存下每一步的get_state_snapshot()然后线性比对但内存爆炸。本模板采用空间换时间用set存储所有见过的状态快照利用tuple的可哈希性实现 O(1) 查重。def find_cycle_period(system: System) - int: 找出系统状态重复的最小周期 返回从初始状态到首次重复状态的步数 seen_states set() state system.get_state_snapshot() seen_states.add(state) step 0 while True: system.step() step 1 state system.get_state_snapshot() if state in seen_states: return step seen_states.add(state) # 安全上限防止无限循环实际 AoC 数据必有周期 if step 10_000_000: raise RuntimeError(fNo cycle found within {step} steps)这里seen_states.add(state)是关键。state是Tuple[Tuple[int, ...], ...]Python 的set对这种嵌套元组支持完美哈希。if state in seen_states的平均时间复杂度是 O(1)比线性搜索快几个数量级。这个函数在 2019 Day 12 的真实输入上能在 3 秒内找到周期约 2772 万步而暴力方案需数小时。4. 避坑指南2017–2020 四年踩过的 5 个高频雷区与根治方案Advent of Code 表面是算法题实则是披着编程外衣的工程压力测试。以下 5 个坑是我用四年时间、上百次失败验证出的「必踩清单」。它们不是冷知识而是每次写新 day 时必须主动检查的 checklist。4.1 坑输入解析后数据类型不一致 → 导致TypeError在solve_part_two()爆发现象solve_part_one()正常输出solve_part_two()报TypeError: unsupported operand type(s) for : str and int原因parse_input()对样例输入纯数字字符串返回int但对真实 input含空行或注释返回str未做类型统一。例如 2018 Day 2 的 input 每行末尾有\r\nline.strip()后仍是str若直接int(line)会失败。解决在parse_input()末尾强制类型转换并用try/except提供清晰错误信息def parse_input(self, raw_input: str) - List[int]: lines raw_input.strip().splitlines() result [] for i, line in enumerate(lines): try: result.append(int(line.strip())) except ValueError as e: raise ValueError(fFailed to parse line {i1}: {line} as int. Raw input:\n{raw_input[:200]}...) from e return result4.2 坑测试用例复用真实 input → 本地测试通过提交却超时现象pytest tests/test_day_10.py秒过但python run_all.py --year 2020 --day 10卡住不动原因测试文件误用了read_input(2020, 10)读取真实 input1000 行而样例 input 仅 5 行。测试本该用小数据快速验证逻辑结果变成了性能测试。解决测试文件绝对禁止调用read_input()只允许硬编码sample_input字符串。在run_all.py中用--dry-run参数控制是否加载真实 input# 仅运行测试不读真实 input python run_all.py --year 2020 --day 10 --dry-run # 运行真实解法 python run_all.py --year 2020 --day 104.3 坑浮点数参与哈希/比较 → 周期检测永远失败现象find_cycle_period()运行到上限 10M 步仍未退出print(len(seen_states))显示持续增长原因某处误用math.sqrt()或除法/导致vx/vy/vz变成floatto_tuple()返回(1.0, 2.0, ...)而float的哈希值不稳定1.0 1但hash(1.0) ! hash(1)state in seen_states永远为False。解决在Planet.__post_init__()中强制int()并在apply_gravity()中所有增量操作用 1而非 0.5。添加断言def step(self): self.apply_gravity() for p in self.planets: p.apply_velocity() # 断言所有值仍为 int for p in self.planets: assert isinstance(p.x, int), fx is {type(p.x)}, not int assert isinstance(p.vx, int), fvx is {type(p.vx)}, not int4.4 坑递归深度不足 → Day 15RLE 解压直接RecursionError现象solve_part_two()报RecursionError: maximum recursion depth exceeded堆栈指向自定义递归函数原因2017 Day 15 的 input 包含深度嵌套的压缩标记如(10x2)展开后又含(5x3)默认递归限制 1000 层不够。解决不盲目调高sys.setrecursionlimit()易导致 segfault而是改用显式栈stack替代递归def decompress_iterative(compressed: str) - str: stack [(compressed, 0)] # (current_str, start_pos) result [] while stack: s, pos stack.pop() while pos len(s): if s[pos] (: # 解析 (AxB) 格式 end s.find(), pos) a, b map(int, s[pos1:end].split(x)) # 将重复部分压栈 repeat_str s[end1:end1a] for _ in range(b): stack.append((repeat_str, 0)) pos end 1 a else: result.append(s[pos]) pos 1 return .join(result)4.5 坑多线程/多进程误用 →ValueError: I/O operation on closed file现象用concurrent.futures.ProcessPoolExecutor并行跑多个 day报I/O operation on closed file原因read_input()内部用path.read_text()而multiprocessing中子进程无法共享父进程的文件句柄且pathlib.Path对象在跨进程传递时可能失效。解决禁用多进程解 AoC无必要改用线程池ThreadPoolExecutor并确保read_input()是纯函数无副作用# run_all.py 中 from concurrent.futures import ThreadPoolExecutor def run_single_day(year: int, day: int, dry_run: bool): # 线程安全每个线程独立调用 read_input() if not dry_run: input_data read_input(year, day) # ... 解题逻辑 return result # 主函数中 with ThreadPoolExecutor(max_workers4) as executor: futures [executor.submit(run_single_day, y, d, args.dry_run) for y in years for d in days] for future in as_completed(futures): print(future.result())5. 进阶技巧用logging替代print实现可配置日志以及如何用git bisect快速定位逻辑退化点当你把 AoC 当作工程训练日志就不再是print(debug: x, x)那种临时补丁而是可开关、可分级、可追溯的诊断系统。同样当代码量超过 1000 行某个 day 的solve_part_two()突然不 work 了你不可能逐行git checkout回溯。这两个技巧是让这套模板真正从「能跑」升级到「好维护」的关键。5.1 结构化日志配置用logging替代print支持 DEBUG/INFO/WARNING 分级print的致命缺陷是无法关闭、无法分级、无法重定向。logging则提供完整控制。在aoc/common.py中初始化import logging import sys from pathlib import Path def setup_logger(name: str aoc, level: int logging.INFO) - logging.Logger: 创建并配置 logger - 默认输出到 stdout - DEBUG 级别显示详细步骤如每步行星坐标 - INFO 级别显示进度如 Day 12: Step 1000/1000 done - WARNING 级别显示潜在问题如输入行数异常 logger logging.getLogger(name) logger.setLevel(level) # 避免重复添加 handler if logger.handlers: return logger # 控制台 handler console_handler logging.StreamHandler(sys.stdout) console_handler.setLevel(level) # 格式[2023-12-01 10:20:30] INFO aoc._2020.day_01: Part one result: 514579 formatter logging.Formatter( [%(asctime)s] %(levelname)-8s %(name)s: %(message)s, datefmt%Y-%m-%d %H:%M:%S ) console_handler.setFormatter(formatter) logger.addHandler(console_handler) return logger # 全局 logger 实例 LOGGER setup_logger()然后在任意day_x.py中使用# 2020/day_01.py from aoc.common import LOGGER class Solver(BaseSolver): def solve_part_one(self, parsed_input: List[int]) - int: LOGGER.debug(fStarting part one with {len(parsed_input)} numbers) for i, a in enumerate(parsed_input): for j, b in enumerate(parsed_input[i1:], i1): if a b 2020: result a * b LOGGER.info(fFound pair ({a}, {b}) - product {result}) return result LOGGER.warning(No pair found summing to 2020) return 0现在你可以用命令行开关控制日志级别# 只看 INFO 及以上默认 python run_all.py --year 2020 --day 1 # 查看 DEBUG 级别详细步骤用于调试 python run_all.py --year 2020 --day 1 --log-level DEBUG # 完全关闭日志生产环境 python run_all.py --year 2020 --day 1 --log-level WARNINGDEBUG日志帮你看到每一步的中间状态INFO日志告诉你宏观进度WARNING日志则像哨兵提醒你逻辑可能偏离预期。这才是专业级的可观测性。5.2 用git bisect定位逻辑退化当test_day_05_part_two()突然 fail 时假设你在 2020 Day 5二分查找座位号的solve_part_two()上做了优化几天后发现测试失败。手动回溯太慢git bisect是二分法的终极武器。步骤如下标记已知坏提交当前 HEAD 是坏的git bisect start git bisect bad标记已知好提交找一个确定通过的 commit如上周的 commitgit bisect good abc1234 # 替换为实际 commit hash自动二分测试git bisect会 checkout 中间 commit你只需运行测试# 在每次 checkout 后执行 pytest 2020/tests/test_day_05.py::test_sample_part_two -q # 如果通过运行 git bisect good # 如果失败运行 git bisect bad定位到罪魁祸首git bisect会不断缩小范围最终输出导致失败的第一个 commit。提示为加速git bisect写一个自动化测试脚本bisect_test.sh#!/bin/bash python -m pytest 2020/tests/test_day_05.py::test_sample_part_two -q --tbno /dev/null 21 if [ $? -eq 0 ]; then exit 0 # success good else exit 1 # failure bad fi然后git bisect run ./bisect_test.sh全程全自动。5.3 一个真实案例2019 Day 12 的周期检测优化史2019 Day 12 的周期检测最初用list存储所有历史状态内存占用达 8GB运行 2 小时未出结果。第一版优化改用set内存降至 2GB时间 45 分钟。第二版意识到 x/y/z 三个维度的运动是独立的分别计算各维度周期再求 LCM最小公倍数内存 10MB时间 3 秒。这个优化不是灵光一现而是靠logging记录各维度状态变化频率再用git bisect对比优化前后 commit 的性能差异最终锁定瓶颈在状态存储方式。从那以后我每次写新 day 的solve_part_two()都强制走一遍三步先用最直白的逻辑实现哪怕 O(n²)用logging.DEBUG打印关键变量规模如len(seen_states)若性能不达标用git bisect回溯到上一个可用版本再针对性优化。这套动作已融入肌肉记忆——它不保证代码最优但保证每次修改都可逆、可查、可证伪。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/24 3:42:05 · 阅读 1.2k Advent of Code Python工程化模板：输入解析、测试驱动与结构化日志
简介本资源是面向Python初学者与算法进阶学习者的Advent of Code历年真题实战解决方案合集覆盖2017–2020年全部挑战聚焦递归、图遍历、动态规划、位运算、计算几何等核心算法场景助力系统性提升编程思维与工程实现能力。压缩包共240个文件含152个Python源码按年份/日期组织如day01.py至day25.py、83个原始输入数据文件.input、4张说明性PNG图示及1个.gitignore总大小989KB结构清晰、开箱即用。已有137人下载学习适合对照题目自主调试、分析解法差异或复用输入处理与通用工具函数。代码充分运用Python内置模块itertools/collections/math与惯用写法生成器、列表推导式每份脚本均包含输入解析与双子题逻辑实现可直接运行验证是理解算法落地细节与优化实践的优质参考样本。1. 这不是刷题合集而是一套可复用的 Advent of Code 解题工程模板覆盖 2017–2020 全年 Python 实现含输入解析、测试驱动、结构化日志与自动校验你有没有试过年底打开 Advent of CodeAoC链接点开 Day 1写完两道题第二天就卡在输入格式解析上第三天发现昨天的代码根本没法复用第四天开始手动复制粘贴 input.txt 到每个脚本里第五天……干脆关掉浏览器这不是懒是原始解法在工程维度上的系统性失能。我当年就是这么翻车的——2017 年靠硬编码撑到 Day 122018 年改用全局变量传 input结果 Day 15 的递归爆栈后连 debug 日志都找不到源头。直到我把所有年份的解法重构成统一骨架才真正把 AoC 从「节日彩蛋」变成「年度 Python 工程训练场」。这份资源不是答案库而是一套经过四年实战迭代的解题基础设施它强制你把输入解析、逻辑分层、测试验证、结果校验全部模块化它不教算法但让你每次写solve_part_one()时心里清楚input_data是什么类型、parse_input()返回什么结构、test_day_03_part_two()跑的是哪条边界用例。适合所有已掌握基础 Python函数/类/文件读写、想把 AoC 当作真实项目来练手的开发者——尤其适合那些总在 Day 5 就放弃、或写完代码不敢改怕崩的中阶实践者。2. 为什么必须重构 AoC 解题流程从「单文件脚本」到「可测试、可复用、可追踪」的工程化结构Advent of Code 的天然设计是「每日一题、独立输入、无上下文依赖」这看似友好实则埋下三大工程隐患一是输入格式碎片化2017 Day 4 是空格分隔单词2019 Day 12 是多行坐标速度2020 Day 17 是二维网格带三维扩展每次都要重写解析逻辑二是测试缺失导致修改即崩溃比如 Day 8 的寄存器指令加个负数就让条件跳转失效没测试根本不敢动三是结果验证黑盒化提交答案后才知对错无法本地快速断言。我见过太多人把 25 个.py文件散落在一个文件夹里每个文件开头都是with open(input.txt) as f: ...这种结构在 Day 10 还能扛在 Day 22 的图遍历状态压缩组合题面前必然崩盘。所以这套模板的核心不是“怎么解题”而是“怎么让解题过程本身具备可持续性”。2.1 目录结构设计按年份隔离 按日粒度组织 统一入口协议整个资源采用严格分层目录杜绝跨年耦合aoc-solution-framework/ ├── aoc/ # 核心包定义通用接口与基类 │ ├── __init__.py │ ├── common.py # 输入读取、日志初始化、结果校验工具 │ └── base.py # BaseSolver 抽象类强制实现 parse_input/solve_part_one/solve_part_two ├── 2017/ # 每年独立子包互不 import │ ├── __init__.py │ ├── day_01.py # 必须继承 aoc.base.BaseSolver │ ├── day_02.py │ └── tests/ # 对应测试与 day_x.py 同名 │ ├── __init__.py │ ├── test_day_01.py │ └── test_day_02.py ├── 2018/ │ ├── day_01.py │ └── tests/ ├── 2019/ ├── 2020/ └── run_all.py # 统一执行入口python run_all.py --year 2020 --day 5提示aoc.base.BaseSolver是关键契约。任何day_x.py必须实现三个方法parse_input(self, raw_input: str) - Any输入转结构化数据、solve_part_one(self, parsed_input: Any) - Any核心逻辑、solve_part_two(self, parsed_input: Any) - Any第二问。这个抽象层让run_all.py可以无差别加载任意年份任意日期的解法无需硬编码路径或函数名。2.2 输入解析标准化用common.read_input()统一处理路径、缓存与编码AoC 官网下载的 input 总是纯文本但不同年份的存放位置、命名规则、编码方式2017 部分 input 含 UTF-8 BOM千差万别。手动处理极易出错。common.read_input()封装了全部细节# aoc/common.py import os from pathlib import Path def read_input(year: int, day: int, strip: bool True) - str: 安全读取指定年份/日期的 input.txt 自动查找路径./{year}/input/day_{day:02d}.txt 或 ./{year}/input.txt 自动处理 BOM若文件以 UTF-8 BOM 开头自动 strip 缓存机制首次读取后存入内存 dict后续调用直接返回避免重复 IO cache_key f{year}_{day} if cache_key in _INPUT_CACHE: return _INPUT_CACHE[cache_key] # 构建候选路径优先找 day-specific再找年份级 candidates [ Path(f{year}/input/day_{day:02d}.txt), Path(f{year}/input.txt), Path(f{year}/inputs/day_{day:02d}.txt), ] for path in candidates: if path.exists(): content path.read_text(encodingutf-8-sig) # utf-8-sig 自动处理 BOM if strip: content content.strip() _INPUT_CACHE[cache_key] content return content raise FileNotFoundError(fInput file not found for year {year}, day {day} in any standard location)这段代码解决的不是“能不能读”而是“读得稳不稳”。encodingutf-8-sig是血泪经验——2017 Day 11 的 input 包含特殊符号用普通utf-8会抛UnicodeDecodeError_INPUT_CACHE是性能刚需跑全量测试时避免 100 次重复文件 IO路径自动探测则让迁移旧代码时只需移动文件夹不用改一行读取逻辑。2.3 测试驱动开发TDD落地每个 day_x.py 必配 test_day_x.py且强制覆盖样例输入模板要求每个day_x.py必须有同名tests/test_day_x.py且至少包含两个测试用例test_sample_part_one和test_sample_part_two。这是防止“本地跑通、官网提交错”的后悔药。以 2020 Day 1 为例# 2020/tests/test_day_01.py import pytest from aoc.common import read_input from aoc._2020.day_01 import Solver def test_sample_part_one(): # 使用官方提供的 sample input非真实 input sample_input 1721\n979\n366\n299\n675\n1456 solver Solver() parsed solver.parse_input(sample_input) result solver.solve_part_one(parsed) assert result 514579 # 1721 * 299 def test_sample_part_two(): sample_input 1721\n979\n366\n299\n675\n1456 solver Solver() parsed solver.parse_input(sample_input) result solver.solve_part_two(parsed) assert result 241861950 # 1721 * 979 * 366关键点在于sample_input是硬编码字符串而非读取文件。这样测试完全脱离网络和文件系统秒级执行。pytest运行时test_sample_part_one失败意味着你的parse_input()或solve_part_one()逻辑有误test_sample_part_two失败则说明第二问的边界处理如三数之和 vs 两数之和没到位。这种测试不是锦上添花而是每次修改代码前的必过安检门。3. 核心解题模块实战以 2019 Day 12天体模拟为例拆解物理建模、状态快照与周期检测2019 Day 12 是 AoC 中少有的需要建模物理系统的题目四个天体在三维空间中受引力相互作用需模拟 1000 步后计算总能量并进一步求出系统状态重复的最小周期。它完美暴露了原始解法的脆弱性——用一堆x, y, z, vx, vy, vz变量硬编码第 500 步后变量名已乱成浆糊。而本模板的解法是把它彻底对象化、可序列化、可断言。3.1Planet类设计用 dataclass 封装状态用__post_init__强制约束# 2019/day_12.py from dataclasses import dataclass from typing import List, Tuple dataclass class Planet: x: int y: int z: int vx: int 0 vy: int 0 vz: int 0 def __post_init__(self): # 强制初始化为整数防止 float 混入影响后续哈希与周期检测 self.x int(self.x) self.y int(self.y) self.z int(self.z) self.vx int(self.vx) self.vy int(self.vy) self.vz int(self.vz) property def potential_energy(self) - int: return abs(self.x) abs(self.y) abs(self.z) property def kinetic_energy(self) - int: return abs(self.vx) abs(self.vy) abs(self.vz) property def total_energy(self) - int: return self.potential_energy * self.kinetic_energy def apply_velocity(self): self.x self.vx self.y self.vy self.z self.vz def to_tuple(self) - Tuple[int, int, int, int, int, int]: 返回可哈希元组用于周期检测 return (self.x, self.y, self.z, self.vx, self.vy, self.vz)dataclass省去样板__init____post_init__是安全阀——确保所有字段是int因为后续周期检测要用tuple做哈希键float会导致精度漂移。to_tuple()方法是关键设计它把行星当前完整状态位置速度压缩成一个不可变元组为下一步的全局状态快照提供原子单元。3.2System类封装解耦模拟逻辑与状态管理支持 step-by-step 与 batch-runclass System: def __init__(self, planets: List[Planet]): self.planets planets.copy() # 防止外部修改影响内部状态 def get_state_snapshot(self) - Tuple[Tuple[int, ...], ...]: 获取当前系统完整状态快照((p1.x,p1.y,...), (p2.x,p2.y,...), ...) return tuple(p.to_tuple() for p in self.planets) def apply_gravity(self): 计算所有行星间的引力作用更新速度 n len(self.planets) for i in range(n): for j in range(i 1, n): p1, p2 self.planets[i], self.planets[j] # x 方向 if p1.x p2.x: p1.vx 1 p2.vx - 1 elif p1.x p2.x: p1.vx - 1 p2.vx 1 # y, z 同理... if p1.y p2.y: p1.vy 1 p2.vy - 1 elif p1.y p2.y: p1.vy - 1 p2.vy 1 if p1.z p2.z: p1.vz 1 p2.vz - 1 elif p1.z p2.z: p1.vz - 1 p2.vz 1 def step(self): 执行单步先应用引力改速度再应用速度改位置 self.apply_gravity() for p in self.planets: p.apply_velocity() def run_steps(self, n: int) - None: 批量运行 n 步内部可加进度日志调试用 for i in range(n): self.step() if i % 100 0 and i 0: print(fStep {i}/{n} completed) def total_energy(self) - int: return sum(p.total_energy for p in self.planets)这个System类是解题的中枢。它把“模拟”这件事从主逻辑中抽离出来step()方法清晰定义了物理顺序先算力再动位置get_state_snapshot()返回可哈希元组为周期检测铺平道路。注意run_steps()中的print不是生产代码而是调试开关——当怀疑周期过长时打开它看是否卡死。3.3 周期检测实现用 set 记录历史状态O(1) 查重Day 12 第二问要求找出系统状态重复的最小步数。暴力思路是存下每一步的get_state_snapshot()然后线性比对但内存爆炸。本模板采用空间换时间用set存储所有见过的状态快照利用tuple的可哈希性实现 O(1) 查重。def find_cycle_period(system: System) - int: 找出系统状态重复的最小周期 返回从初始状态到首次重复状态的步数 seen_states set() state system.get_state_snapshot() seen_states.add(state) step 0 while True: system.step() step 1 state system.get_state_snapshot() if state in seen_states: return step seen_states.add(state) # 安全上限防止无限循环实际 AoC 数据必有周期 if step 10_000_000: raise RuntimeError(fNo cycle found within {step} steps)这里seen_states.add(state)是关键。state是Tuple[Tuple[int, ...], ...]Python 的set对这种嵌套元组支持完美哈希。if state in seen_states的平均时间复杂度是 O(1)比线性搜索快几个数量级。这个函数在 2019 Day 12 的真实输入上能在 3 秒内找到周期约 2772 万步而暴力方案需数小时。4. 避坑指南2017–2020 四年踩过的 5 个高频雷区与根治方案Advent of Code 表面是算法题实则是披着编程外衣的工程压力测试。以下 5 个坑是我用四年时间、上百次失败验证出的「必踩清单」。它们不是冷知识而是每次写新 day 时必须主动检查的 checklist。4.1 坑输入解析后数据类型不一致 → 导致TypeError在solve_part_two()爆发现象solve_part_one()正常输出solve_part_two()报TypeError: unsupported operand type(s) for : str and int原因parse_input()对样例输入纯数字字符串返回int但对真实 input含空行或注释返回str未做类型统一。例如 2018 Day 2 的 input 每行末尾有\r\nline.strip()后仍是str若直接int(line)会失败。解决在parse_input()末尾强制类型转换并用try/except提供清晰错误信息def parse_input(self, raw_input: str) - List[int]: lines raw_input.strip().splitlines() result [] for i, line in enumerate(lines): try: result.append(int(line.strip())) except ValueError as e: raise ValueError(fFailed to parse line {i1}: {line} as int. Raw input:\n{raw_input[:200]}...) from e return result4.2 坑测试用例复用真实 input → 本地测试通过提交却超时现象pytest tests/test_day_10.py秒过但python run_all.py --year 2020 --day 10卡住不动原因测试文件误用了read_input(2020, 10)读取真实 input1000 行而样例 input 仅 5 行。测试本该用小数据快速验证逻辑结果变成了性能测试。解决测试文件绝对禁止调用read_input()只允许硬编码sample_input字符串。在run_all.py中用--dry-run参数控制是否加载真实 input# 仅运行测试不读真实 input python run_all.py --year 2020 --day 10 --dry-run # 运行真实解法 python run_all.py --year 2020 --day 104.3 坑浮点数参与哈希/比较 → 周期检测永远失败现象find_cycle_period()运行到上限 10M 步仍未退出print(len(seen_states))显示持续增长原因某处误用math.sqrt()或除法/导致vx/vy/vz变成floatto_tuple()返回(1.0, 2.0, ...)而float的哈希值不稳定1.0 1但hash(1.0) ! hash(1)state in seen_states永远为False。解决在Planet.__post_init__()中强制int()并在apply_gravity()中所有增量操作用 1而非 0.5。添加断言def step(self): self.apply_gravity() for p in self.planets: p.apply_velocity() # 断言所有值仍为 int for p in self.planets: assert isinstance(p.x, int), fx is {type(p.x)}, not int assert isinstance(p.vx, int), fvx is {type(p.vx)}, not int4.4 坑递归深度不足 → Day 15RLE 解压直接RecursionError现象solve_part_two()报RecursionError: maximum recursion depth exceeded堆栈指向自定义递归函数原因2017 Day 15 的 input 包含深度嵌套的压缩标记如(10x2)展开后又含(5x3)默认递归限制 1000 层不够。解决不盲目调高sys.setrecursionlimit()易导致 segfault而是改用显式栈stack替代递归def decompress_iterative(compressed: str) - str: stack [(compressed, 0)] # (current_str, start_pos) result [] while stack: s, pos stack.pop() while pos len(s): if s[pos] (: # 解析 (AxB) 格式 end s.find(), pos) a, b map(int, s[pos1:end].split(x)) # 将重复部分压栈 repeat_str s[end1:end1a] for _ in range(b): stack.append((repeat_str, 0)) pos end 1 a else: result.append(s[pos]) pos 1 return .join(result)4.5 坑多线程/多进程误用 →ValueError: I/O operation on closed file现象用concurrent.futures.ProcessPoolExecutor并行跑多个 day报I/O operation on closed file原因read_input()内部用path.read_text()而multiprocessing中子进程无法共享父进程的文件句柄且pathlib.Path对象在跨进程传递时可能失效。解决禁用多进程解 AoC无必要改用线程池ThreadPoolExecutor并确保read_input()是纯函数无副作用# run_all.py 中 from concurrent.futures import ThreadPoolExecutor def run_single_day(year: int, day: int, dry_run: bool): # 线程安全每个线程独立调用 read_input() if not dry_run: input_data read_input(year, day) # ... 解题逻辑 return result # 主函数中 with ThreadPoolExecutor(max_workers4) as executor: futures [executor.submit(run_single_day, y, d, args.dry_run) for y in years for d in days] for future in as_completed(futures): print(future.result())5. 进阶技巧用logging替代print实现可配置日志以及如何用git bisect快速定位逻辑退化点当你把 AoC 当作工程训练日志就不再是print(debug: x, x)那种临时补丁而是可开关、可分级、可追溯的诊断系统。同样当代码量超过 1000 行某个 day 的solve_part_two()突然不 work 了你不可能逐行git checkout回溯。这两个技巧是让这套模板真正从「能跑」升级到「好维护」的关键。5.1 结构化日志配置用logging替代print支持 DEBUG/INFO/WARNING 分级print的致命缺陷是无法关闭、无法分级、无法重定向。logging则提供完整控制。在aoc/common.py中初始化import logging import sys from pathlib import Path def setup_logger(name: str aoc, level: int logging.INFO) - logging.Logger: 创建并配置 logger - 默认输出到 stdout - DEBUG 级别显示详细步骤如每步行星坐标 - INFO 级别显示进度如 Day 12: Step 1000/1000 done - WARNING 级别显示潜在问题如输入行数异常 logger logging.getLogger(name) logger.setLevel(level) # 避免重复添加 handler if logger.handlers: return logger # 控制台 handler console_handler logging.StreamHandler(sys.stdout) console_handler.setLevel(level) # 格式[2023-12-01 10:20:30] INFO aoc._2020.day_01: Part one result: 514579 formatter logging.Formatter( [%(asctime)s] %(levelname)-8s %(name)s: %(message)s, datefmt%Y-%m-%d %H:%M:%S ) console_handler.setFormatter(formatter) logger.addHandler(console_handler) return logger # 全局 logger 实例 LOGGER setup_logger()然后在任意day_x.py中使用# 2020/day_01.py from aoc.common import LOGGER class Solver(BaseSolver): def solve_part_one(self, parsed_input: List[int]) - int: LOGGER.debug(fStarting part one with {len(parsed_input)} numbers) for i, a in enumerate(parsed_input): for j, b in enumerate(parsed_input[i1:], i1): if a b 2020: result a * b LOGGER.info(fFound pair ({a}, {b}) - product {result}) return result LOGGER.warning(No pair found summing to 2020) return 0现在你可以用命令行开关控制日志级别# 只看 INFO 及以上默认 python run_all.py --year 2020 --day 1 # 查看 DEBUG 级别详细步骤用于调试 python run_all.py --year 2020 --day 1 --log-level DEBUG # 完全关闭日志生产环境 python run_all.py --year 2020 --day 1 --log-level WARNINGDEBUG日志帮你看到每一步的中间状态INFO日志告诉你宏观进度WARNING日志则像哨兵提醒你逻辑可能偏离预期。这才是专业级的可观测性。5.2 用git bisect定位逻辑退化当test_day_05_part_two()突然 fail 时假设你在 2020 Day 5二分查找座位号的solve_part_two()上做了优化几天后发现测试失败。手动回溯太慢git bisect是二分法的终极武器。步骤如下标记已知坏提交当前 HEAD 是坏的git bisect start git bisect bad标记已知好提交找一个确定通过的 commit如上周的 commitgit bisect good abc1234 # 替换为实际 commit hash自动二分测试git bisect会 checkout 中间 commit你只需运行测试# 在每次 checkout 后执行 pytest 2020/tests/test_day_05.py::test_sample_part_two -q # 如果通过运行 git bisect good # 如果失败运行 git bisect bad定位到罪魁祸首git bisect会不断缩小范围最终输出导致失败的第一个 commit。提示为加速git bisect写一个自动化测试脚本bisect_test.sh#!/bin/bash python -m pytest 2020/tests/test_day_05.py::test_sample_part_two -q --tbno /dev/null 21 if [ $? -eq 0 ]; then exit 0 # success good else exit 1 # failure bad fi然后git bisect run ./bisect_test.sh全程全自动。5.3 一个真实案例2019 Day 12 的周期检测优化史2019 Day 12 的周期检测最初用list存储所有历史状态内存占用达 8GB运行 2 小时未出结果。第一版优化改用set内存降至 2GB时间 45 分钟。第二版意识到 x/y/z 三个维度的运动是独立的分别计算各维度周期再求 LCM最小公倍数内存 10MB时间 3 秒。这个优化不是灵光一现而是靠logging记录各维度状态变化频率再用git bisect对比优化前后 commit 的性能差异最终锁定瓶颈在状态存储方式。从那以后我每次写新 day 的solve_part_two()都强制走一遍三步先用最直白的逻辑实现哪怕 O(n²)用logging.DEBUG打印关键变量规模如len(seen_states)若性能不达标用git bisect回溯到上一个可用版本再针对性优化。这套动作已融入肌肉记忆——它不保证代码最优但保证每次修改都可逆、可查、可证伪。希望帮到你。本文还有配套的精品资源点击获取