← Back to the notebookVEINSURE / WRITING

Engineering

工程记录示例:实现稳定去重函数

围绕一个小型数据处理需求,记录接口约束、实现选择、边界测试和复杂度,而不虚构项目经历。

目标与需求

一批整数 ID 可能重复出现。需要保留每个 ID 第一次出现的位置,同时删除后续重复项。

例如:

输入:[3, 1, 3, 2, 1]
输出:[3, 1, 2]

接口接受整数可迭代对象,返回一个新的列表。输入顺序、首次出现顺序和返回值顺序必须一致。函数不修改输入,不依赖全局状态。

为什么先写约束

“去重”本身不足以定义结果。把序列转为集合可以移除重复元素,却没有表达本需求要求的首次出现顺序。

还需要说明适用范围:这里处理可哈希的整数,不把任意嵌套列表、复杂对象或模糊相等规则加入同一接口。

实现

用集合记录已经出现的 ID,用列表记录返回顺序。两个数据结构分别负责判断和组织结果:

def stable_unique(values):
    seen = set()
    result = []
    for value in values:
        if value not in seen:
            seen.add(value)
            result.append(value)
    return result

这个函数没有文件读写和网络请求,因此可以独立于调用它的数据流水线进行验证。

用例验证

def verify_stable_unique():
    assert stable_unique([]) == []
    assert stable_unique([4]) == [4]
    assert stable_unique([3, 1, 3, 2, 1]) == [3, 1, 2]
    assert stable_unique([2, 2, 2]) == [2]
    assert stable_unique([-1, 0, -1]) == [-1, 0]

    original = [3, 1, 3]
    assert stable_unique(original) == [3, 1]
    assert original == [3, 1, 3]
    assert stable_unique([3, 1, 2]) == [3, 1, 2]

这些用例分别检查空输入、单个值、顺序、重复值、负数和输入不变性。把它们与上面的实现放在同一个 Python 文件中,调用验证函数即可运行。

技术选择

选择原因
使用局部集合只负责判断是否出现过,不承担输出顺序
单独构建列表显式保留首次出现顺序
不修改输入便于复用和定位调用方问题
不增加第三方依赖标准库已能满足这个接口

在通常的哈希表操作成本假设下,处理 nn 项的期望时间复杂度为 O(n)O(n)。设不同 ID 数量为 kk,集合和结果列表需要 O(k)O(k) 额外空间。这不是对任意输入和哈希冲突情况的最坏耗时承诺。

哪些内容没有被测量

本文不报告吞吐率、生产延迟或内存峰值,因为这些测量并未进行。真正加入项目时,应根据输入规模和调用方式另行测量,并记录运行环境。

目前的函数只负责去重。批量读取、错误恢复和数据持久化属于调用流程,不必为了这个示例提前扩展接口。

复盘

一份有用的工程记录应能回答:需求究竟是什么、为什么选择这种实现、哪些性质已经验证、哪些结论还缺证据。即使实现很短,这些说明也能让后续修改更可靠。

END OF NOTEBack to top ↑

Search the notebook

Search published writing. Use ↑ ↓ to select, Enter to open.