1. 一个看似简单的排序报障41号旧代码惹出的乱子上周一的告警群里某运营同学丢来一句话“任务看板又乱了。”没有配图没有复现步骤。我回了一句“哪块看板”然后打开代码目录开始排查。最后背锅的是仓库里编号为41的一段旧代码——一段负责列表排序的手写算法。这是几个月来我处理的第几次排序问题说真的已经数不过来了。排序问题看着简单好像就是比较一下、换一下位置的事但它恰恰是我最不想碰的故障类型。原因倒不是因为算法多难而是因为它太“隐形”了系统不会报错接口状态码永远是200数据库连接正常页面也能渲染出来。唯一的异常就是列表里某些行的顺序不符合人的直觉。这种问题一旦出现排查链路往往很长而旧代码里积累下来的隐性约定比任何报错信息都难缠。这次报障的具体现象是任务看板里最近修改过的几个任务没有按预期固定在列表靠前的位置有些“已完成”状态的任务混在待办中间翻到第二页同一个任务在不同页面的先后关系也让人觉得奇怪。运营同学说这个问题出现大概两天了但又补充了一句“不是所有列表都乱有些项目看着是正常的。”就这一句话基本就决定了排查方向一个偶发的、看起来时好时坏的排序问题大概率不是数据库层面的规则错误而是内存里某段排序逻辑在特定输入下才暴露问题。带着这个判断我开始了定位。1.1 报障现象与业务排序规则先把业务侧的真实规则写清楚任务看板的排序要求是三级比较优先级高的靠前优先级相同的按更新时间晚的靠前更新时间也相同的再按任务ID小的靠前。这套规则早在需求文档里写明白了运营同学日常也是按这个预期去核对页面的。对照这个规则线上现象确实是不符合预期的。尤其是“最近修改过的任务”这个维度按规则它们应该明显靠前但实际页面里它们散落在中部甚至尾部。我用几个固定的任务ID反复刷新发现顺序不是每次都乱多刷几遍结果可能变得不一样。这个“不稳定”的细节让我更确信问题不是SQL里写死了一条错误排序而是内存排序中存在某些非确定性因素。记录完现象我先把排查目标定为“找到列表数据从数据库查出来之后到浏览器渲染之前到底经历了哪些排序动作”。这个过程不算复杂但必须一层一层来。1.2 为什么排序问题总是最磨人很多人不理解一个排序问题为什么能让开发排查半天。这里我说点经验排序问题的难点不在排序本身而在“现象”和“原因”之间往往隔着好几层。前端可能重新排序接口可能排序SQL可能排序甚至某个定时任务里可能修改了排序字段的值——只要其中任何一层的行为和你的预期不一致最终页面都会乱。更麻烦的是排序问题的复现成本很高。像这次运营同学刷新几次才能看到错误顺序开发去查的时候数据状态已经变了。你很难用一个稳定的最小复现样例去驱动修复只能靠代码审查和日志推断。另外旧代码里常见的“能跑就行”式写法会把问题藏得更深。比如排序时用了某个字段的默认值或者异常被外层try/except吞掉这些坑不读到源码根本看不出来。这也是为什么我遇到排序类故障从来不敢直接改数据或加补丁而是坚持把整条调用链走完。2. 顺着调用链摸到41号代码前端、接口、SQL三层嫌疑排查的第一步是问一个问题这份列表数据的顺序究竟是在哪一层被决定的我的做法是分层排除前端、接口、SQL一层层看哪一层有排序动作就重点看哪一层。2.1 前端嫌疑的排除先看前端看板页面。打开组件代码发现页面确实接收了一个sort对象里面含有sortField和sortOrder之类的字段——这很容易让人误以为是前端在做排序。但往下读逻辑前端做的是点击表头时切换升序/降序然后把排序参数传给后端重新请求数据拿到新数据后直接渲染并没有在浏览器里对列表做二次排序。这里顺便说一个我踩过的坑很多前端组件库尤其是表格类组件自带客户端排序能力默认开启后会遮蔽后端返回的顺序。如果哪个列表同时让前端排序字段和后端排序逻辑生效就会出现“当前页看起来有序翻页就乱”的诡异现象。但这次不是前端已经把排序参数原样传给接口所以嫌疑排除往下走。2.2 接口层的可疑点接口层是真正有排序动作的地方。在返回任务列表前的数据处理流程里代码调用了一个工具函数函数名叫sort_legacy_41。看到这个名字的时候我心里就咯噔了一下——“legacy”加编号这类函数十有八九是早期项目留下的旧代码复用范围广、维护次数少、没有什么测试覆盖。我先不急着读它的实现而是做了一件事把接口内存排序后的返回值和SQL层查询出来的原始顺序做了一次对比。如果SQL查出来已经有序而接口返回的顺序不符合预期那问题大概率就在这个内存排序函数里如果SQL查出来顺序就乱那就要回看数据库层的查询语句。这一步是关键的诊断实验。通过临时在日志里打印两种顺序我确认了SQL查询出来的顺序完全符合预期而接口返回值与它不同——所以焦点正式落到了这个函数上。2.3 SQL层的最终排除为了确认SQL层没问题我看了一下执行的查询。SQL里确实写了ORDER BY priority ASC, updated_at DESC, id ASC和业务规则完全一致。数据库返回的记录顺序我在本地用同样的数据跑了一遍也确认了是正确的。从三层排查来看前端没有参与排序SQL没有排错唯一的差异点就是接口层调用的sort_legacy_41。我把三层判断整理成了一个对照表方便后续追溯排查层验证方法结论前端阅读传参逻辑确认无二次排序排除接口对比SQL原始顺序与接口返回顺序存在差异重点嫌疑SQL单独执行查询语句验证ORDER BY规则排除到了这一步问题已经缩小到一个非常明确的函数上。接下来要做的就是打开它看看到底哪里写得不对劲。3. 41号旧代码的排序逻辑到底错在哪三处致命细节打开sort_legacy_41之后我看到的是一段非常典型的手写冒泡排序。函数接收一个任务列表然后两层循环遍历、比较相邻元素、必要时交换位置最后返回同一个列表对象。代码本身不长也就二三十行但几乎每一行都写着“这是早期临时需求催出来的代码”。我仔细读了三遍确认了三处致命问题。这三个问题单独看任何一个都不会立刻让排序全错但它们叠加在一起加上内存列表输入顺序的随机性最终导致页面上出现时好时坏的诡异表现。3.1 第一处问题比较逻辑与业务规则脱节这段旧代码里比较两个相邻任务时只判断了一个字段priority。用到的默认值和比较逻辑大概是这样的if items[j].get(priority, 0) items[j 1].get(priority, 0): items[j], items[j 1] items[j 1], items[j]也就是说它完全忽略了一个事实业务规则要求的是优先级、更新时间、任务ID的三级比较。当列表里任务优先级都不相同时这段代码勉强能看但现实中大部分任务优先级是重复的尤其是大量默认优先级任务存在时光靠priority排序根本无法决定正确的先后关系。那为什么以前没有暴露原因很微妙sort_legacy_41的输入列表在绝大多数场景下都来自于SQL查询结果而SQL已经按ORDER BY priority ASC, updated_at DESC, id ASC排好序了。一个已经有序的列表再经过这段冒泡排序不会改变顺序所以看起来代码一直是“正常”的。问题就出在“绝大多数场景”这几个字上。一旦某个模块往列表里插入了自己构建的数据或者上游查询语句因为其他需求改了字段输入的初始顺序不再那么规整旧代码的排序结果就会立刻偏离预期。这种老代码我一般管它叫“依附于巧合才能正常的代码”。3.2 第二处问题手写冒泡排序的不稳定性再看代码里的比较条件用的是而不是。这在冒泡排序里是一个很经典的不稳定写法。所谓稳定排序指的是排序字段相等时两个元素的相对顺序保持原样而不稳定排序则可能把它们交换位置谁先谁后就变成随机行为。旧代码用意味着当两个任务的priority相等时即使它们已经保持原有先后顺序也会被无条件交换一次。这类交换累积起来就会让同优先级任务之间的相对顺序产生漂移。放在当前场景中输入列表恰好来自SQL有序结果时漂移被掩盖了一旦输入顺序不同同优先级内谁在前谁在后就完全失去保障。排序稳定性这件事很多人写业务代码时不在意。但业务排序里它极其重要当主排序字段相同你往往希望保留第二字段的相对顺序而手写排序一旦不稳定等于变相丢弃了第二、第三排序规则。表面上看只是两个相邻元素“换了一下”实际上整个列表的第二排序维度都被破坏了。3.3 第三处问题null值处理缺位第三处问题最隐蔽也最致命。旧代码在读取排序字段时用的是get(priority, 0)它把“字段缺失”的情况兜底成了0。但“字段缺失”和“字段值为None”是两回事如果任务对象里priority键存在但是值为None那么None和整数0比较时Python会直接抛TypeError。如果只有这一处抛异常问题还会更早暴露。最坑的是sort_legacy_41的调用方代码外面包了一个大try/except异常被静默吞掉了排序函数直接返回原列表。于是整个函数“看似执行了其实什么都没做”数据完全保持上游输入时的顺序。这种静默吞异常的做法比排序结果错乱更难发现因为它把问题从“结果不对”变成了“结果时而对、时而不对”排查难度直接上了一个台阶。结合这三处问题我很快确定了一个结论这段代码根本不缺一次修补缺的是按照真实业务规则进行的重构。4. 修复方案选择“最小改动”与“彻底重写”之间拿着三处问题我开始设计修复方案。身边有同事建议既然是旧代码干脆把冒泡排序换成快速排序性能更好。我没有立刻采纳因为排序类问题里“重写一个排序算法”往往比“修一下排序规则”带来更多新隐患。4.1 先明确不做什么快速排序本身不是坏选择但在业务列表排序场景下它有明显短板不稳定。前面已经解释过稳定性的重要性快速排序默认行为不稳定会让同优先级任务再次出现随机相对顺序。要让快速排序稳定需要额外处理相等元素的相对位置复杂度就上去了。另一个不能做的事是乱改函数签名。sort_legacy_41被多个模块复用有的模块可能默认它会修改原列表对象有的模块可能依赖返回值有的模块可能依赖它内部对异常的处理方式。贸然换成新函数或者改变返回值类型调用方会先崩一片。所以我的修复原则是保持函数入口、返回值行为基本不变只替换内部逻辑。4.2 修复后的实现思路修复版的核心思路是不再手写排序主体改用Python内置的sorted函数并把排序规则完整地编码进排序键key中。这样既利用内置排序的稳定性也把业务规则集中在一个函数里后续维护只需要看这一个key函数。我在做具体实现时还额外处理了第3节说的null值问题。排序键的设计如下缺失或非法的priority统一沉底可解析的时间戳换成数值之后取负实现“最新在前”任务ID作为最后的决胜字段。def _parse_ts(value): if isinstance(value, (int, float)): return float(value) from datetime import datetime try: return datetime.fromisoformat(str(value)).timestamp() except (TypeError, ValueError): return float(inf) def sort_legacy_41(items): if not items: return items def sort_key(item): priority item.get(priority) updated_at item.get(updated_at) task_id item.get(id) # 缺失或非法的优先级沉底合法优先级靠前 if priority is None: priority_group 1 priority_val float(inf) else: priority_group 0 priority_val float(priority) # 更新时间最新在前无法解析的时间视为最旧 ts _parse_ts(updated_at) if updated_at else float(inf) return (priority_group, priority_val, -ts, task_id if task_id is not None else 0) return sorted(items, keysort_key)这套实现里最值得说的一点是把null值沉底的逻辑放在了优先级元组的第一个元素priority_group上而不是直接塞一个超大整数。原因是如果只把None映射成float(inf)那么它只会排在同为合法整数优先级的后面但万一别的数据也是inf就会和沉底数据混在一起。用group字段先做分组再接具体数值逻辑更清晰。为什么不直接用Python的functools.cmp_to_key写自定义比较函数我也考虑过但cmp函数容易把比较规则写得隐晦而且自定义cmp出现“a比b大、b又比a大”这类自相矛盾时排出来的结果很难预期。用元组key构造全序代码可读性和可维护性都更好。4.3 修复方案对比我把手写冒泡、直接换快速排序、以及最终采用的sortedkey方案放在一起做了对比方便团队后续决策参考维度手写冒泡旧直接换快速排序sorted key稳定性不稳定不稳定稳定业务规则表达只覆盖priority需要额外处理一个key函数完整表达null值处理无遇None抛异常需自行处理已内建分组逻辑代码可维护性低中高调用方兼容不兼容风险高需验证完全兼容4.4 除了算法还改了什么修复过程中我额外做了两件事一是给函数补了docstring明确写出三级排序规则避免下一个人再看代码猜业务逻辑二是在函数边上留了注释标注“新代码请勿新增调用后续将迁移至新模块”。这两件事都不影响线上行为但对团队协作价值很大。旧代码最怕的其实不是写得差而是没人知道它“应当是什么样”。把规则用文字固定下来后面就算再遇到类似情况也有据可查。5. 回归验证与上线后观察一次修复的真正完成代码改完只是第一步真正让一次修复成立的是回归验证。排序问题尤其怕“只修了眼前的现象没有覆盖隐藏的边界”所以我在测试阶段准备了一批比线上故障更刁钻的样本。5.1 构造测试样本而不是等线上出问题我准备了五组用例覆盖不同场景所有任务没有priority字段只靠更新时间排序若干任务priority相同但更新时间不同若干任务priority和更新时间都相同只有ID不同输入列表已经按SQL期望顺序排好输入列表是彻底乱序的。每组用例我都同时跑了旧代码和修复版代码对比输出顺序。结果很有意思旧代码在第2、3、5组用例上都会产生错误顺序第1组会直接抛异常被外部捕获后返回原列表只有第4组碰巧正确。修复版在全部五组用例上都符合预期。这个结果印证了当初的判断旧代码之所以“平时看着正常”是因为线上输入碰巧落在第4组场景一旦数据形态出现一点变化就立刻原形毕露。5.2 特别注意分页与导出的一致性回归过程中我还特意检查了分页场景。一个排序函数如果只在当前页内排序翻页后顺序就会断裂。修复版的排序发生在接口返回完整数据之前所以第一页、第二页的顺序是连续且一致的不存在分页断裂问题。另外我排查了sort_legacy_41的三个调用方任务看板列表、批量操作的前20条预览、导出报表。前两个调用方直接使用函数返回值导出报表则会沿用排序后的顺序生成文件。修复之后这三个场景的顺序规则实现了统一不会出现页面顺序和导出顺序不一致的尴尬。5.3 灰度观察与性能顺带收益上线前我走的是常规灰度流程先让一小部分流量命中新逻辑观察了两天看板反馈和接口报错率确认没有回归后再全量放量。放量之后我发现一个意外收益旧代码是冒泡排序复杂度O(n^2)在数据量大的列表上会有肉眼可见的延迟换成sorted之后复杂度是O(n log n)接口整体耗时也有了明显改善。这其实说明有些旧代码的问题不只是“逻辑不对”它连性能都是历史包袱只是之前没人注意到罢了。6. 从41号旧代码看开去如何避免排序bug在代码库里埋伏十年修完sort_legacy_41这件事并没有就此结束。我后来在团队内部复盘时专门聊了一个话题像这样的旧代码为什么能在代码库里潜伏这么长时间直到某个偶然的报障才被发现6.1 排序逻辑应该沉淀成公共工具而不是到处手写41号代码之所以烂一个很重要的原因是它最初只服务一个紧急需求贴着具体页面写出来的。后来其他模块看到它能排序就开始复用复用它的人又不敢乱改于是它就在“半废弃”状态里被保留下来。更合理的做法是把所有业务排序规则收敛到一个公共排序函数中函数集中管理排序字段的优先级、null值策略和稳定性要求。新增需求只需要修改公共函数和对应测试而不是在某个模块里再写一套手写循环。6.2 加一条Code Review清单禁用手写排序主体我在复盘会上提议了一条新的Code Review红线代码里出现手写冒泡排序、选择排序等“手动交换相邻元素”的写法时评审人一定要打问号。除非有明确的性能或环境限制否则一律使用内置排序函数并显式注明排序字段和稳定性要求。这条规则看起来严格但实际执行下来团队反馈都不错。因为业务代码里的排序需求绝大多数是简单、稳定的全局排序内置函数完全能覆盖手写排序带来的往往是隐性bug而不是性能优势。6.3 旧代码识别与接替机制处理41号代码时我给它打上了“legacy_entry”的标记并在维护文档里记录了调用方清单。下一步计划是在新模块里提供一个替代函数把三个调用方逐个迁过去最后再彻底删除旧代码。这种小步迁移的方式比某一天“大重构”要安全得多。旧代码不可怕可怕的是没人记录它为什么存在、被谁使用、应该表现为什么行为。把这些信息固定下来才算真正把一个“历史包袱”变成了“可维护资产”。属于41号代码的修复工作到这里就全部完成了。回头再看一个排序故障背后藏着的往往不是算法不会写而是业务规则在漫长迭代中被一点一点稀释掉了。把规则重新固定下来比更换任何一个排序算法都重要。下次再有人跟我说“只是排序有点乱”我知道这往往又是一个深入代码细节的漫长下午。
