# CSV 夜间任务凌晨两点会挂，先让重跑变得无害

> 用文件内容的哈希做键、记入台账、隔离坏 CSV，重发或只导入一半的文件都不会重复入库。

原文: https://fdetimes.net/zh/guides/idempotent-nightly-sftp-csv-pipeline/

设想部署进入第三个晚上。客户把 `orders_1108.csv` 放到 SFTP 上，任务导入了一半，数据库连接超时。第二天早上重跑任务，文件前半部分又导入了一遍。下一周，客户以 `orders_1108_final.csv` 的名字重新发来同一个文件，整个文件再次入库。

这条链路上没有哪一步的逻辑有错。问题在于任务没有记忆。夜间批处理迟早要重跑，所以安全重跑必须从第一天就设计进去，而不是出了事故再打补丁。

本指南用 Python 写一个小任务，做四件事：计算每个文件的哈希，查台账，校验 CSV 结构，然后处理文件或将其隔离。代码是简化示意，只用标准库和 SQLite。需要准备 Python 3、一个模拟 SFTP 投放位置的 `inbox/` 目录，以及一个 `quarantine/` 目录。

## 什么叫安全重跑？

Powertools for AWS Lambda 文档对幂等性的定义是：用相同的输入参数多次调用某个操作，不会产生额外的副作用。

对夜间批处理来说，“相同的输入”指的是相同的文件内容，文件名不算数。该文档也允许用整个负载的哈希作为幂等键，本文的任务正是这样做的。

### 第 1 步：分块计算 SHA-256

```python
import hashlib

def sha256_of(path):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1 << 20), b""):
            h.update(chunk)
    return h.hexdigest()
```

按 1 MB 分块读取，即使是几 GB 的文件也不会耗尽内存。**验证：**把一个文件复制成另一个名字，分别计算哈希。两个十六进制字符串必须完全相同；只要改动文件中的一个字符，字符串就必须完全不同。

### 第 2 步：所有文件共用一张台账表

Appsilon 介绍过一种事件驱动的临床数据导入设计：每个文件对应一条 JSON 记录，包含 SHA-256 校验和、大小和处理状态，记录以原子方式写入。这里用 SQLite 代替 JSON，原理相同。

```sql
CREATE TABLE IF NOT EXISTS ledger (
  sha256     TEXT PRIMARY KEY,
  filename   TEXT,
  size       INTEGER,
  status     TEXT,   -- 取值：in_progress | done | quarantined
  reason     TEXT,
  updated_at TEXT
);
```

把 `PRIMARY KEY` 放在哈希列上，一次得到两样东西：去重和锁。Powertools 用一条“处理中”记录阻止对同一负载的两次并发调用，被拒绝的 `INSERT` 起的是同样的作用。

```python
import sqlite3

def claim(db, digest, name, size):
    try:
        with db:  # 单个事务
            db.execute(
                "INSERT INTO ledger VALUES (?,?,?,'in_progress',NULL,datetime('now'))",
                (digest, name, size))
        return True
    except sqlite3.IntegrityError:
        return False  # 已经见过：已完成、已隔离或正在运行
```

**验证：**用同一个哈希调用两次 `claim`。第一次必须返回 `True`，第二次返回 `False`。

## 合法的 CSV 文件长什么样？

RFC 4180 给出了最容易检查的结构规则：文件中每一行的字段数应当相同。同一份 RFC 还建议，凡是包含换行符、双引号或逗号的字段，都应该用双引号括起来。

从老旧系统导出的文件恰恰常在这一点上出错，比如地址列里有逗号却没加引号。

### 第 3 步：对照表头检查字段数

```python
import csv

def validate(path):
    try:
        with open(path, newline="", encoding="utf-8") as f:
            rows = csv.reader(f)
            header = next(rows, None)
            if not header:
                return "空文件"
            for n, row in enumerate(rows, start=2):
                if len(row) != len(header):
                    return f"第 {n} 条记录：{len(row)} 个字段，表头有 {len(header)} 个"
    except (csv.Error, UnicodeDecodeError) as e:
        return f"解析错误：{e}"
    return None
```

`csv` 模块能识别带引号的字段，所以写法正确的地址，例如 `"12 Le Loi, District 1"`，仍算作一个字段。

代码统计的是记录而不是物理行，因为含换行符的字段会跨越多行。**验证：**创建一个表头有 8 列、其中一行只有 7 列的文件，函数必须返回包含记录编号的原因。

这只是结构检查。数据类型、日期、客户 ID 是否存在，属于另一层校验；但如果文件结构已经损坏，后面几层就不必再跑。

## 数据错误和基础设施错误必须走不同的路径

这是整个任务中最重要的思路。在 Appsilon 的设计里，失败的文件会被移到隔离路径，并附上一条单独的审计记录说明发生了什么，而不是简单地重试。道理很简单：字段数不对的文件，重跑一百次还是不对。

超时、连接断开这类基础设施错误则正好相反。Powertools 的处理方式是捕获异常，删除幂等记录以避免数据不一致，再重新抛出异常。这样下一次尝试才会真正执行，而不是被当作已经完成。

### 第 4 步：组装起来

```python
import shutil, logging

def handle(db, path, quarantine_dir, load):
    digest = sha256_of(path)
    if not claim(db, digest, path.name, path.stat().st_size):
        logging.info("跳过 %s（sha256 %s 已在台账中）", path.name, digest)
        return "skipped"
    try:
        err = validate(path)
        if err:
            shutil.move(path, quarantine_dir / path.name)
            mark(db, digest, "quarantined", err)
            return "quarantined"
        load(path)                      # 你向客户系统导入数据的逻辑
        mark(db, digest, "done", None)
        return "done"
    except Exception:
        with db:
            db.execute("DELETE FROM ledger WHERE sha256=?", (digest,))
        raise
```

`mark` 函数就是在一个事务里执行 `UPDATE ledger SET status=?, reason=?, updated_at=datetime('now') WHERE sha256=?`。跳过文件时的日志必不可少。Appsilon 用一句话概括审计原则：没有任何东西被悄无声息地丢弃，每个结果，无论成功还是失败，都有记录。

**要点:** 客户发来的每个文件都必须有且只有一个结果，而且这个结果必须记录在案。

## 有了台账，再跑一遍第三晚

回到开头的场景，不过这一晚有三个文件。`a.csv` 干净，完整导入。`b.csv` 有一条记录只有 7 个字段，而表头有 8 个，于是被移到 `quarantine/` 并写明原因。`c.csv` 导入到一半时数据库超时，它的记录被删除。

早上重跑。`a.csv` 的哈希已标记为 `done`，于是被跳过，留下一条日志。`b.csv` 已在隔离区。`c.csv` 不再有记录，于是从头重新导入。

下一周，客户发来 `a_final.csv`，内容与 `a.csv` 相同：哈希相同，跳过。客户发来修正后的 `b.csv`：内容不同，哈希也不同，作为新文件处理。

## 任务上生产环境时常见的四个错误

第一个错误是以为 `except` 块总会执行。如果进程被强行终止，比如内存耗尽、收到 SIGKILL 或机器重启，就不会捕获任何异常。`in_progress` 记录会永远留在那里，文件每晚都被跳过，仿佛另有一个 worker 在处理它。

解决办法是把超过 N 小时的 `in_progress` 记录视为已失效，允许回收。下面的示意代码在每次任务开始时运行：

```python
def reclaim_stale(db, hours=6):
    with db:
        db.execute(
            "DELETE FROM ledger WHERE status='in_progress' "
            "AND updated_at < datetime('now', ?)",
            (f"-{hours} hours",))
```

N 必须大于单个文件实际处理的最长时间，否则会抢走一个仍在被活着的 worker 导入的文件。**验证：**手动插入一条 `in_progress` 记录，把 `updated_at` 设为 7 小时前，运行任务，确认文件被重新处理。

第二个错误是台账过期太早。Powertools 的幂等记录默认在一小时（3,600 秒）后过期。这个默认值适合 API 请求，但不适合客户可能三周后才重发的文件。文件台账的保留时间，至少要覆盖客户仍可能重发旧数据的整个时段。

第三个错误是让 `load` 函数直接往正式表里写行。如果任务在第 5,000 行挂掉，删除台账记录只是让文件可以重跑，已经导入的 5,000 行仍留在原处。应先在事务中导入暂存表，再把数据移到正式表，或者按业务键做 upsert，让导入这一步本身也是幂等的。

第四个错误是在 SFTP 仍在写入时就读取文件。本文的示意代码没有处理这种情况。在真实环境中，要和客户约定一种标记文件已传完的方式，例如先用临时文件名上传再重命名，或者附送一个校验和文件，与自己计算的哈希比对。

## 当客户问“我的文件呢？”

每当客户问出这句话，台账就体现出价值。有了它，一分钟就能答清楚：哪个文件、什么时候到的、哈希是多少、导入成功了还是因为哪条坏记录被隔离。没有它，就只能翻日志、靠猜。

如果你正准备转向前线部署工程师（FDE）岗位，可以把这个任务放到 GitHub 上，并为五种场景写好测试：干净文件、结构损坏的文件、中途超时、进程被杀，以及换了名字的重复文件。简历上不要只写“搭建了 ETL”，要具体写明这条管道重跑不会产生重复，并为每个文件保留审计记录。

读岗位描述时，如果看到工作内容包括定期接收客户投放的数据，就要准备好讲这个任务的故事。值得追问的问题是：任务凌晨两点挂了会怎样？而你的回答应该是“重跑就行”。

**本周动手试试:**

- 找一个你正在运行的文件导入任务，把同一个文件以两个不同的名字各投放一次，统计有多少行被重复导入
- 为这个任务加一张台账表（sha256、filename、size、status、reason、updated_at），再为五种场景写测试：干净文件、结构损坏的文件、任务中途超时、进程被杀后留下 in_progress 记录，以及内容重复但名字不同的文件
- 为客户写一页运行手册：文件被隔离时他们会收到什么通知，以及如何重新发送修正后的版本

## 信源

- [Idempotency - Powertools for AWS Lambda (Python)](https://docs.aws.amazon.com/powertools/python/latest/utilities/idempotency/)

- [RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files](https://www.rfc-editor.org/rfc/rfc4180)

- [From file drop to audit trail: event-driven ingestion for clinical data delivery](https://www.appsilon.com/post/from-file-drop-to-audit-trail-event-driven-ingestion-for-clinical-data-delivery)
