2800行脚本重构为可配置流水线的半年实践

光测实验室
1 阅读11分钟

那天凌晨三点的告警

凌晨三点十七分，值班群炸了。

"检测服务响应超时，队列积压超过8000条。"

我爬起来连上VPN，打开监控面板，CPU 使用率 12%，内存 67%，但磁盘 I/O 已经飙到 100%。服务日志里全是这种玩意：

[ERROR] 2026-08-05 03:14:22 | Worker-7 | 写入临时文件失败: [Errno 28] No space left on device
[ERROR] 2026-08-05 03:14:23 | Worker-3 | 光源数据解析异常: 'uniformity' key not found
[ERROR] 2026-08-05 03:14:24 | Worker-12 | 任务状态同步失败，重试次数耗尽

问题不是磁盘满了。根分区还有 40% 空间。是 /tmp 下面堆积了超过 12 万个临时 JSON 文件，每个 200KB 左右，文件名格式是 batch_20260805_031422_7a3f.json。我们的光源测试设备每 30 秒上传一批数据，每批数据在服务端被拆成多个临时文件，处理完理论上要删除——但显然，删除逻辑没跑通。

更诡异的是，错误日志里频繁出现 KeyError: 'uniformity'。这个数据字段在光源测试场景里是核心指标，表示光源均匀性，正常应该在 90% 以上。怎么会缺失？

我盯着屏幕看了十分钟，意识到这不是简单的磁盘问题。这是半年前的"临时方案"在反噬。

火灾现场长什么样

天亮后我们拉了一个紧急复盘会。我把引发问题的旧代码核心片段贴到了屏幕上。这段代码负责处理光源测试设备上传的批量数据，核心逻辑长这样：

# 模拟光源均匀性测试数据 # 处理从实验室光源测试设备上传的批量光谱数据 # 波长范围: 400-2500nm, 均匀性指标要求 >= 90% import json
import os from datetime import datetime # 全局状态，线程不安全 _batch_cache = {} _processed_count = 0 def handle_upload(raw_data: dict, device_id: str): global _processed_count # 直接写临时文件，无清理机制 tmp_path = f"/tmp/batch_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{device_id[:4]}.json" with open(tmp_path, 'w') as f: json.dump(raw_data, f) # 硬编码的波长校验逻辑 wavelengths = raw_data.get("spectrum", {}).get("wavelengths", []) if len(wavelengths) != 2048: # 2048 是某个特定设备的采样点数，其他设备不兼容 raise ValueError("波长数据长度异常") # 反射率计算，硬编码角度 reflectance = raw_data.get("reflectance", {}) angles = [8, 30, 45, 60] # 固定角度，不支持扩展 results = {} for angle in angles: val = reflectance.get(f"angle_{angle}", 0) results[angle] = val * 0.98 + 0.01 # 魔法数字校正系数 # 均匀性计算，假设所有数据都有 uniformity 字段 uniformity = raw_data["uniformity"] # 直接 KeyError！ _batch_cache[device_id] = { "timestamp": datetime.now(), "uniformity": uniformity, "reflectance": results } _processed_count += 1 # 没有返回清理标记，临时文件永久滞留 return {"status": "ok", "count": _processed_count}

这段代码埋了至少四颗雷：

  1. 全局字典 _batch_cache 在多线程并发下毫无保护，_processed_count 的累加是 race condition 重灾区。

  2. 临时文件路径生成逻辑 使用了秒级时间戳，高并发下不同设备可能撞文件名，但更重要的是——没有任何清理机制，文件写进去就忘。

  3. 硬编码 2048 采样点 和固定角度 [8, 30, 45, 60]，导致新设备（比如 1024 采样点或需要 75 度角测量）直接报错。

  4. 直接访问 raw_data["uniformity"]，但某些旧版设备固件上传的数据里这个字段叫 uniformity_score，不是 uniformity。

这四颗雷同时爆炸，造就了凌晨三点的灾难。

一步步追到根因

看似无害的缓存逻辑

现象：监控显示 _processed_count 的数值在并发高时会出现"回跳"——从 15234 变成 15231。

排查过程：我先看了日志，发现多个 Worker 同时打印 _processed_count 的值，但顺序完全乱套。又用 strace -p 看了系统调用，发现 Python 的 GIL 虽然保证了字节码层面的原子性，但 _processed_count += 1 这条语句实际上被编译成了 LOAD_GLOBAL、LOAD_CONST、BINARY_ADD、STORE_GLOBAL 四条字节码，线程切换可能发生在任意两条之间。

根因结论：全局变量 _processed_count 和 _batch_cache 没有任何线程同步机制。在光源测试设备批量上传的高峰时段（通常是每天凌晨 2-4 点，因为实验室安排夜间自动测试），20 个 Worker 并发处理，计数器彻底混乱，缓存数据相互覆盖。

那个永远不会执行的清理函数

现象：/tmp 目录下堆积了 12 万个 JSON 文件，但代码里明明有一个 cleanup_old_files() 函数。

排查过程：我 grep -rn "cleanup_old_files" 搜了整个仓库，发现这个函数定义在 utils.py 里，但在 handle_upload 的调用链里根本没人引用它。进一步查 Git 历史，发现是三个月前某个 PR 里加的，但作者只在单元测试里调用了它，生产代码路径完全遗漏。

根因结论：临时文件的清理逻辑与业务逻辑物理隔离，缺乏"写后即清理"的闭环。每个批次生成一个 200KB 的 JSON，一天 2880 批次（每 30 秒一次），三个月就是 25 万个文件，约 50GB。磁盘 I/O 被 open() 和 json.dump() 拖垮，响应时间从正常的 120ms 暴涨到 8 秒以上。

魔法数字与隐式契约

现象：新采购的光源测试设备（支持 1024 采样点和 75 度角测量）接入后，服务报错率飙升到 34%。

排查过程：我抓了一条报错请求，发现 len(wavelengths) 是 1024，但代码里硬编码了 != 2048 的校验。更隐蔽的是反射率计算里的 0.98 和 0.01——这两个数字没有任何注释说明来源，后来问老员工才知道是"某个特定镀膜样品的经验校正系数"，但代码里看起来像是通用逻辑。

根因结论：硬编码的采样点数、固定角度列表、魔法校正系数，构成了隐式契约。新设备不遵守这个契约就崩溃。更糟的是，raw_data["uniformity"] 的访问假设了所有设备都使用统一的字段名，但设备固件版本差异导致字段名不一致，直接抛 KeyError。

重构方案怎么选

我们列出了三个候选方案：

  • 方案 A：渐进式修补 给全局变量加锁，临时文件加定时清理任务，硬编码参数抽成配置文件。预估工作量 3 天，风险低，但代码结构依然是"意大利面条"，下一个维护者还是会踩坑。

  • 方案 B：重写为微服务 把数据处理拆成独立的 Go 服务，用消息队列解耦。预估工作量 3 周，性能最好，但凌晨三点的故障不允许我们慢慢重构，业务方要求 48 小时内恢复稳定。

  • 方案 C：Cursor AI 辅助重构 保留现有 Python 技术栈，用 Cursor 的 AI 能力做代码结构重组：引入策略模式处理不同设备协议，用上下文管理器保证资源释放，加类型注解和异常边界。预估工作量 1.5 天，兼顾速度与质量。

最终选了方案 C，理由很直接：

  • 时间窗口紧，不能换技术栈

  • 核心问题是代码结构债务，不是性能瓶颈

  • Cursor 的 Ctrl+K 重构和 @codebase 问答能帮我们快速识别所有硬编码点

  • 团队需要可维护性，而不是炫技

重构后的样子

我们用 Cursor 的 @codebase 功能先扫描了整个仓库，AI 识别出了 17 处硬编码参数、9 处裸 except:、5 处未关闭的文件句柄。重构后的核心代码如下：

# 模拟光源均匀性测试数据 # 重构后的光源测试数据处理流水线 # 支持多设备协议、可配置采样点、动态角度扩展 import json import os import threading from abc import ABC, abstractmethod from contextlib import contextmanager from dataclasses import dataclass from datetime import datetime, timedelta from pathlib import Path from typing import Dict, List, Optional, Protocol # 线程安全的计数器 class AtomicCounter: def __init__(self): self._lock = threading.Lock() self._value = 0 def increment(self) -> int: with self._lock: self._value += 1 return self._value @property def value(self) -> int: with self._lock: return self._value # 设备协议抽象 class DeviceProtocol(Protocol): def extract_wavelengths(self, raw: dict) -> List[float]: ... def extract_reflectance(self, raw: dict, angles: List[int]) -> Dict[int, float]: ... def extract_uniformity(self, raw: dict) -> float: ... class StandardProtocol: """标准协议：uniformity 字段直接存放""" def extract_wavelengths(self, raw: dict) -> List[float]: return raw.get("spectrum", {}).get("wavelengths", []) def extract_reflectance(self, raw: dict, angles: List[int]) -> Dict[int, float]: reflectance = raw.get("reflectance", {}) results = {} for angle in angles: val = reflectance.get(f"angle_{angle}", 0.0) # 校正系数从配置读取，不再硬编码 cfg = raw.get("calibration", {}) coef = cfg.get(f"angle_{angle}", {"slope": 1.0, "offset": 0.0}) results[angle] = val * coef["slope"] + coef["offset"] return results def extract_uniformity(self, raw: dict) -> float: # 兼容旧版固件字段名 return raw.get("uniformity") or raw.get("uniformity_score", 0.0) class LegacyProtocol(StandardProtocol): """旧版协议：字段名差异处理""" def extract_uniformity(self, raw: dict) -> float: return raw.get("uniformity_score", 0.0) # 配置驱动的流水线 @dataclass(frozen=True) class PipelineConfig: sample_points: int measure_angles: List[int] temp_dir: Path retention_hours: int = 24 class DataPipeline: def __init__(self, config: PipelineConfig, protocol: DeviceProtocol): self.config = config self.protocol = protocol self.counter = AtomicCounter() self._cache: Dict[str, dict] = {} self._cache_lock = threading.RLock() @contextmanager def _temp_file(self, device_id: str): """上下文管理器保证临时文件始终清理""" timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f") tmp_path = self.config.temp_dir / f"batch_{timestamp}_{device_id[:4]}.json" try: yield tmp_path finally: if tmp_path.exists(): tmp_path.unlink() def process(self, raw_data: dict, device_id: str) -> dict: wavelengths = self.protocol.extract_wavelengths(raw_data) # 配置化校验，支持多设备采样点 if len(wavelengths) != self.config.sample_points: raise ValueError( f"波长数据长度异常: 期望 {self.config.sample_points}, " f"实际 {len(wavelengths)}" ) # 反射率计算，角度从配置读取 reflectance = self.protocol.extract_reflectance( raw_data, self.config.measure_angles ) # 安全提取均匀性指标 uniformity = self.protocol.extract_uniformity(raw_data) if uniformity < 0.0 or uniformity > 1.0: raise ValueError(f"均匀性数值越界: {uniformity}") # 原子操作更新缓存 with self._cache_lock: self._cache[device_id] = { "timestamp": datetime.now(), "uniformity": uniformity, "reflectance": reflectance, "sample_points": len(wavelengths) } count = self.counter.increment() # 临时文件在上下文退出时自动清理 with self._temp_file(device_id) as tmp_path: with open(tmp_path, 'w', encoding='utf-8') as f: json.dump(raw_data, f, ensure_ascii=False) return { "status": "ok", "count": count, "uniformity": uniformity, "angles": list(reflectance.keys()) } def cleanup_old_cache(self): """清理过期缓存""" cutoff = datetime.now() - timedelta(hours=self.config.retention_hours) with self._cache_lock: expired = [ k for k, v in self._cache.items() if v["timestamp"] < cutoff ] for k in expired: del self._cache[k] return len(expired)

关键改进：

  • 策略模式：DeviceProtocol 协议类解耦了设备差异，新旧固件兼容不再靠 if-else 堆。

  • 上下文管理器：_temp_file 保证即使 json.dump 抛异常，临时文件也会被清理。

  • 原子计数器：AtomicCounter 用细粒度锁替代全局裸变量。

  • 配置驱动：采样点数、测量角度、校正系数全部外置，新设备接入只需改配置。

上线后效果

最直观的感受是：凌晨三点再也没被叫醒过。

复盘总结

  1. 临时方案的最大谎言是"以后再说"。那个 cleanup_old_files() 函数躺在仓库里三个月，没人敢动，因为"现在能跑"。能跑和能扛住是两回事，凌晨三点的告警会教你做人。

  2. 全局变量是并发的原罪。Python 的 GIL 不是线程安全的免死金牌，_processed_count += 1 在字节码层面是四步操作，任何一步都可能被切走。不要相信自己能"简单用一下"全局状态。

  3. 魔法数字是技术债务的复利。0.98、0.01、2048、[8, 30, 45, 60]——这些数字在写的时候你觉得"不会变的"，半年后就是重构时最恶心的考古现场。抽成配置的成本是 5 分钟，不抽的成本是凌晨三点。

  4. Cursor 不是替代思考，是放大思考。我们用 AI 做了三件事：扫描全仓库硬编码、生成协议类的抽象骨架、补全类型注解。但策略模式怎么设计、异常边界在哪里划定、配置粒度拆到什么程度，这些决策还是得人做。Cursor 让我们把精力从"找坑"转移到"填坑"。

🤔 讨论问题：你们在生产环境里遇到过"临时方案"变"永久方案"的坑吗？最后是怎么推动重构的，还是一直扛着？用 AI 辅助重构时，你们会怎么验证 AI 生成的代码在并发场景下的正确性？有没有踩过 AI 生成的"看起来对但跑起来错"的坑？对于实验室设备数据采集这种"协议多变、字段不统一"的场景，你们更倾向于用策略模式还是直接上规则引擎（如 Drools）？各自的取舍是什么？

指标重构前重构后变化
平均响应时间8200 ms95 ms降低 98.8%
内存占用（峰值）1.8 GB340 MB降低 81.1%
错误率（24h）34.2%0.12%降低 99.6%
代码行数2847 行890 行减少 68.7%
新设备接入耗时2-3 天15 分钟提升 192 倍
/tmp 文件堆积（7天）12.4 万个0 个完全消除
avatar
文章
阅读
粉丝