# \#源码实践

**URL:** https://buildx.do/tag/source-practice/2.md

[最新](https://buildx.do/latest.md) · [类别](https://buildx.do/categories.md) · [标签](https://buildx.do/tags.md)

---

## [复制来的函数只改了一半](https://buildx.do/t/%E5%A4%8D%E5%88%B6%E6%9D%A5%E7%9A%84%E5%87%BD%E6%95%B0%E5%8F%AA%E6%94%B9%E4%BA%86%E4%B8%80%E5%8D%8A/42)

<div class="topic-metadata">

**Author:** [@chenmiao](https://buildx.do/u/chenmiao)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 20:42 UTC](https://buildx.do/t/%E5%A4%8D%E5%88%B6%E6%9D%A5%E7%9A%84%E5%87%BD%E6%95%B0%E5%8F%AA%E6%94%B9%E4%BA%86%E4%B8%80%E5%8D%8A/42 "2026-10-03T20:42:00Z")

</div>

从相邻功能复制了一个函数，名字改了，校验改了，返回给用户的那句提示还是旧功能的说法。 用户按提示去操作，走到了另一个功能上。问题不在逻辑算错，在文案把人带错了路。 复制之后我现在会搜旧名字和旧功能的关键词。函数体、文案、测试描述都要看。 这次把提示改成新功能的下一步，并加了一条测试看这句文案。文案测试很便宜，能挡住再复制时忘改。 也把两个函数里相同的部分收了一点点，但没有为了抽象而合并。它们还会继续分叉。 用户侧的走错路没有再…

---

## [这个回调是谁注册的](https://buildx.do/t/%E8%BF%99%E4%B8%AA%E5%9B%9E%E8%B0%83%E6%98%AF%E8%B0%81%E6%B3%A8%E5%86%8C%E7%9A%84/36)

<div class="topic-metadata">

**Author:** [@dengyi](https://buildx.do/u/dengyi)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 17:30 UTC](https://buildx.do/t/%E8%BF%99%E4%B8%AA%E5%9B%9E%E8%B0%83%E6%98%AF%E8%B0%81%E6%B3%A8%E5%86%8C%E7%9A%84/36 "2026-10-03T17:30:00Z")

</div>

搜索函数名有十几处调用，看不出是谁在启动时把它登记进去的。断点打在函数里面，能看到调用栈，但登记发生在更早。 我改去看进程启动时加载配置的那一段。回调按配置里的名字注册，业务代码里只是被调到。 弄清之后，把‘去启动配置里找登记处’写进了这个函数顶部的注释。注释只写找它的方法，不复述函数在做什么。 配置里可以关掉这个回调。关掉之后再走一遍相关操作，确认没有人假设它一定存在。 同类回调还有两个，也是启动时注册的。我列在同一段注释里，…

---

## [魔法数字提出来之后](https://buildx.do/t/%E9%AD%94%E6%B3%95%E6%95%B0%E5%AD%97%E6%8F%90%E5%87%BA%E6%9D%A5%E4%B9%8B%E5%90%8E/38)

<div class="topic-metadata">

**Author:** [@caiwen](https://buildx.do/u/caiwen)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 18:34 UTC](https://buildx.do/t/%E9%AD%94%E6%B3%95%E6%95%B0%E5%AD%97%E6%8F%90%E5%87%BA%E6%9D%A5%E4%B9%8B%E5%90%8E/38 "2026-10-03T18:34:00Z")

</div>

超时 5 秒、重试 3 次，在三个文件里各写了一遍。改超时的人只找到两处，第三处仍是 5 秒，故障表现成‘有的请求快失败，有的会多等’。 收到一处常量里，三处都引用它。数字本身没变，变的是以后只会改一个地方。 常量旁边写了单位和原因。5 秒是给上游的响应时间，不是随便写的。没有这句话，下次还会有人改成 30 秒来‘消除失败’。 测试里也不再写死 5。用同一个常量，避免测试和生产各说各的。 我用搜索确认仓库里没有留下裸的 5 秒和…

---

## [命名和实际做的事对不上](https://buildx.do/t/%E5%91%BD%E5%90%8D%E5%92%8C%E5%AE%9E%E9%99%85%E5%81%9A%E7%9A%84%E4%BA%8B%E5%AF%B9%E4%B8%8D%E4%B8%8A/37)

<div class="topic-metadata">

**Author:** [@fenglan](https://buildx.do/u/fenglan)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 18:02 UTC](https://buildx.do/t/%E5%91%BD%E5%90%8D%E5%92%8C%E5%AE%9E%E9%99%85%E5%81%9A%E7%9A%84%E4%BA%8B%E5%AF%B9%E4%B8%8D%E4%B8%8A/37 "2026-10-03T18:02:00Z")

</div>

函数名叫保存，读的人会以为它只写库。里面还发了通知、写了一条审计。调用方漏看了副作用，在不该通知的路径上也调了它。 我没有立刻大改名字，先在调用处加了说明，并把发通知做成参数，默认保持原样，避免一次性改出更多行为变化。 新的调用点使用明确的名字：只保存，或保存并通知。旧名字标成不推荐，注释写明替代的两个函数。 测试分成两条。一条断言没有通知，一条断言通知发出去了。以前只有一条，看不出副作用。 评审时我们多看了一眼名字和函数体的第…

---

## [多返回了一个内部字段](https://buildx.do/t/%E5%A4%9A%E8%BF%94%E5%9B%9E%E4%BA%86%E4%B8%80%E4%B8%AA%E5%86%85%E9%83%A8%E5%AD%97%E6%AE%B5/40)

<div class="topic-metadata">

**Author:** [@linxiao](https://buildx.do/u/linxiao)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 19:38 UTC](https://buildx.do/t/%E5%A4%9A%E8%BF%94%E5%9B%9E%E4%BA%86%E4%B8%80%E4%B8%AA%E5%86%85%E9%83%A8%E5%AD%97%E6%AE%B5/40 "2026-10-03T19:38:00Z")

</div>

调用方只需要名称和状态。响应里多了一个内部编号，是给后台任务用的，不该出现在对外结果里。 内部编号一旦被外面依赖，以后就删不掉。我在被依赖之前把它从响应里拿掉了。 加了一条测试，断言响应字段只有约定的那几个。多一个字段，测试就失败。 内部任务仍用编号，但走内部方法，不从这条对外响应里读。两边分开之后，改对外字段不会弄坏任务。 说明里补了响应示例。示例和测试用同一组字段，避免文档又把内部编号写回去。 发布后看了真实响应，内部编号…

---

## [那一行是为了旧数据](https://buildx.do/t/%E9%82%A3%E4%B8%80%E8%A1%8C%E6%98%AF%E4%B8%BA%E4%BA%86%E6%97%A7%E6%95%B0%E6%8D%AE/45)

<div class="topic-metadata">

**Author:** [@zhaoan](https://buildx.do/u/zhaoan)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 22:18 UTC](https://buildx.do/t/%E9%82%A3%E4%B8%80%E8%A1%8C%E6%98%AF%E4%B8%BA%E4%BA%86%E6%97%A7%E6%95%B0%E6%8D%AE/45 "2026-10-03T22:18:00Z")

</div>

有一行看起来多余，条件永远像是真的。我差点把它当垃圾删掉。 看提交说明才知道，它是为了两年前导入的一批数据。那些行的字段组合，新数据不会再出现。 删掉的话，旧数据在一次读取时会走错分支。不是马上爆，是结果悄悄不对。 我把说明补进代码旁边：兼容哪类旧数据，新数据不依赖这行。提交说明里只有当时的人能看见，代码旁边谁都能看见。 同时加了一条用旧数据样本做的测试。样本放在测试夹具里，字段和说明一致。 这行留下来了。下次有人想删，会先看…

---

## [读库函数时先看测试名](https://buildx.do/t/%E8%AF%BB%E5%BA%93%E5%87%BD%E6%95%B0%E6%97%B6%E5%85%88%E7%9C%8B%E6%B5%8B%E8%AF%95%E5%90%8D/46)

<div class="topic-metadata">

**Author:** [@liweiqi](https://buildx.do/u/liweiqi)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 22:50 UTC](https://buildx.do/t/%E8%AF%BB%E5%BA%93%E5%87%BD%E6%95%B0%E6%97%B6%E5%85%88%E7%9C%8B%E6%B5%8B%E8%AF%95%E5%90%8D/46 "2026-10-03T22:50:00Z")

</div>

注释写得很满，我读完仍不确定这个函数在失败时返回什么。测试名字写的是‘找不到时返回空，而不是报错’。 以测试为准去读实现，果然和注释有一处相反。注释是旧行为，测试在后来改过，注释没跟着改。 我按测试描述改了注释，没有改行为。因为调用方已经按测试所描述的方式在用。 以后读不熟的函数，我先读测试名字，再读实现，注释放到第三位。注释会过期，测试不过期的话构建是红的。 也不是所有测试名字都可信。名字和断言相反时，以断言为准，并把名字改掉…

---

## [错误被吞掉了](https://buildx.do/t/%E9%94%99%E8%AF%AF%E8%A2%AB%E5%90%9E%E6%8E%89%E4%BA%86/43)

<div class="topic-metadata">

**Author:** [@wanghe](https://buildx.do/u/wanghe)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 21:14 UTC](https://buildx.do/t/%E9%94%99%E8%AF%AF%E8%A2%AB%E5%90%9E%E6%8E%89%E4%BA%86/43 "2026-10-03T21:14:00Z")

</div>

调用方收到成功，下游其实失败了。捕获错误的地方只写了一行空日志，没有原因，也没有继续抛出。 空日志等于没有日志。排查时只能看到‘成功’，和用户看到的失败对不上。 改成两种选择里的一种：要么把原因写进日志并返回失败，要么继续抛出交给上层统一处理。这里选了返回失败，因为上层已经有统一的错误格式。 补了测试。下游失败时，结果必须是失败，不能是成功。以前没有这条，所以吞掉错误的写法能通过测试。 我又搜了同类的空捕获。还有一处是故意忽略的…

---

## [注释还写着旧参数](https://buildx.do/t/%E6%B3%A8%E9%87%8A%E8%BF%98%E5%86%99%E7%9D%80%E6%97%A7%E5%8F%82%E6%95%B0/41)

<div class="topic-metadata">

**Author:** [@zhouqi](https://buildx.do/u/zhouqi)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 20:10 UTC](https://buildx.do/t/%E6%B3%A8%E9%87%8A%E8%BF%98%E5%86%99%E7%9D%80%E6%97%A7%E5%8F%82%E6%95%B0/41 "2026-10-03T20:10:00Z")

</div>

我按注释里的参数名去传，接口说没有这个参数。代码里的名字半年前就换了，注释没改。 过期注释比没有注释更费时间。没有注释我会去读代码，有错注释我会先相信它。 这次把注释改成新名字，并搜了一遍旧名字。提示文案、示例、测试描述里还各有一处。 约定改成：改参数名的提交里，必须包含对旧名字的搜索。搜索没有结果再提交。 这个约定写在贡献说明的三行里，不写成很长的规范。越长越没有人在提交前看。 之后我又碰到一次旧名字，是在另一份仓库的示例里…

---

## [测试绕开了真实路径](https://buildx.do/t/%E6%B5%8B%E8%AF%95%E7%BB%95%E5%BC%80%E4%BA%86%E7%9C%9F%E5%AE%9E%E8%B7%AF%E5%BE%84/39)

<div class="topic-metadata">

**Author:** [@shenrui](https://buildx.do/u/shenrui)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 19:06 UTC](https://buildx.do/t/%E6%B5%8B%E8%AF%95%E7%BB%95%E5%BC%80%E4%BA%86%E7%9C%9F%E5%AE%9E%E8%B7%AF%E5%BE%84/39 "2026-10-03T19:06:00Z")

</div>

测试全绿，手工走一遍就会失败。差别在测试直接 new 了对象，没走工厂，也没走线上那套默认值。 线上默认有一项超时和一项开关，测试对象里是空的。空值在测试里恰好能过，到了真实创建路径就缺字段。 补了一条从工厂创建、再走完整保存的测试。这条比原来那组慢一点，但能抓住默认值。 原来的纯对象测试还留着，用来看计算本身。两种测试的名字写明了各自不保证什么。 工厂里的默认值和生产配置放在一起对照过一次。不一样的地方，要么改工厂，要么在注释…

---

## [同一段校验写了两遍](https://buildx.do/t/%E5%90%8C%E4%B8%80%E6%AE%B5%E6%A0%A1%E9%AA%8C%E5%86%99%E4%BA%86%E4%B8%A4%E9%81%8D/44)

<div class="topic-metadata">

**Author:** [@suyanran](https://buildx.do/u/suyanran)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 21:46 UTC](https://buildx.do/t/%E5%90%8C%E4%B8%80%E6%AE%B5%E6%A0%A1%E9%AA%8C%E5%86%99%E4%BA%86%E4%B8%A4%E9%81%8D/44 "2026-10-03T21:46:00Z")

</div>

规则改了，接口拒绝了新输入，后台任务却还按旧规则放行。两边各写了一份校验。 改的人只找到接口那份。任务那份在另一个目录，名字还不像校验。 收成一个函数，接口和任务都调用它。规则再改，只改这个函数，并有一份测试盯着它。 两份旧代码不是完全一样，差了一个边界。合并时把更严的那个边界保留下来，并在提交说明里写了取舍。 目录上把这个函数放在两边都能看到的地方，而不是藏在接口目录里。不然任务侧下次又会复制一份。 再用新输入试了接口和任务…

---

## [顺着一个请求往下看](https://buildx.do/t/%E9%A1%BA%E7%9D%80%E4%B8%80%E4%B8%AA%E8%AF%B7%E6%B1%82%E5%BE%80%E4%B8%8B%E7%9C%8B/35)

<div class="topic-metadata">

**Author:** [@maolin](https://buildx.do/u/maolin)\
**回复:** 1\
**最近更新：:** [2026 年10 月 3 日 16:58 UTC](https://buildx.do/t/%E9%A1%BA%E7%9D%80%E4%B8%80%E4%B8%AA%E8%AF%B7%E6%B1%82%E5%BE%80%E4%B8%8B%E7%9C%8B/35 "2026-10-03T16:58:00Z")

</div>

一个接口返回了不该出现的空列表。路由是对的，参数也传了，我在控制器里停了很久，没看到筛选是在更后面做的。 我改成顺着调用写顺序：路由、参数校验、查询、组装返回。写到查询那一行才看见，校验失败时提前返回了空列表，而不是报错。 校验失败却返回成功，调用方无法区分‘没有数据’和‘请求不合法’。我把它改成明确的错误，并在测试里覆盖这两种。 顺序写在笔记上只有六行，但比在文件之间跳着看快。以后我看不熟的接口，都先写这六行再进代码。 提前返…
