对内 API 体验日志：对另一个团队来说，到底什么变了
阅读约 1 分钟
这个专题下的其他每一篇文章，都默认调用某个 API 的人身处公司之外：某个客户那边的工程师，一个合作伙伴，或者某个自己找到了文档的人。但很多 API 面对的调用方完全是另一类人，可能就是隔壁办公室、或者两层楼之外的另一个团队，而这彻底改变了体验日志到底该对他们负什么责任这笔账，因为一条 Slack 消息就能触达他们，而客服工单这种东西，通常压根就不会被开出来。大多数团队从这一点得出的结论是，对内的 API 根本不需要体验日志。但他们真正需要的，其实是一份完全不一样的体验日志。
对内 API 的体验日志，到底跟对外的有什么不一样
对内的 API 的读者是可以被直接触达的，这一点恰恰去掉了大多数对外 API 体验日志之所以存在的核心理由：向那些没法逐一联系上的调用方广播消息。拥有一个对内 API 的团队，通常清楚地知道到底是哪些其他团队在调用它，有时甚至精确到具体哪个服务。这让一条有针对性的消息，而不是一份公开的信息流，成了自然而然的默认选择，而这恰恰也是对内 API 最终往往完全没有体验日志的原因：拥有这个 API 的团队通知了自己记得的那两三个团队，然后想当然地以为这样就覆盖了所有人。
| 对外 API 体验日志 | 对内 API 体验日志 | |
|---|---|---|
| 谁会读它 | 任何外部调用方，大多数情况下没法被直接触达 | 一小群通常已知的对内团队 |
| 默认渠道 | 一个页面加一份信息流 | 发给调用方团队的一条消息，理想情况下也配一个页面 |
| 最大的风险 | 某个调用方完全错过了这条记录 | 拥有这个 API 的团队忘记了一个自己都不记得存在的调用方 |
| 用什么取代”我们不知道是谁在调用我们” | 什么都没有；只能广泛发布 | 一份真正存在、并且持续保持更新的调用方登记表 |
为什么”我们直接通知调用我们的那些团队”这套做法会失灵
因为调用方这个集合，从来都不像拥有 API 的团队所记得的那样小、那样固定不变。一个为某一个消费方构建的服务，六个月后会通过一次没人对外宣布过的集成，多出第二个调用方，而拥有这个 API 的团队脑子里”到底是谁在调用我们”这份名单，此刻已经错了，却没有人意识到这一点。这种失败是平常且常见的，是依赖记忆而不是依赖一份记录所必然导致的默认结果，而不是说明谁不够上心。什么是破坏性变更 讲解了该怎样判断一次 API 变更到底算不算破坏性变更；而对内这种情况，还在这个问题之上，叠加了第二个更难的问题：到底该通知谁。
对内 API 到底需不需要一个对外风格的体验日志页面
通常还是需要的，哪怕主要渠道是直接沟通。有了页面，直接发的消息就有了一个可以指向的地方，通知本身可以保持简短（“/v2/accounts 出现了破坏性变更，详情见这里”），而不用硬把整段解释塞进一条很快就会被滚动条冲走的聊天消息里。它同时也成了一个新团队、或者一个错过了那条直接消息的团队，在自己的集成出问题、试图搞清楚到底为什么的时候，可以去查的地方。这个页面不需要打磨得多精致，也不需要完全公开；它只需要能被链接，并且比那条宣布它存在的 Slack 讨论串活得更久就够了。
到底是谁在真正维护那份调用方名单
是拥有这个 API 的团队，而这件事必须被当成一份真正的产出物来对待，而不是靠口口相传的部落知识。最省事的做法，是在 API 自己的仓库里放一个文件，列出一份简短的消费方服务清单，每一条都写明负责人，每次有新的集成被搭建起来时都同步更新，这跟任何一种依赖声明的纪律要求完全一样。另一种做法，也就是每次要做破坏性变更之前都到处去问一圈，能撑到某一次终于有人忘了去问对的那个人为止；而一个对内 API 悄无声息地为某个团队坏掉，虽然是一起比对外事故规模更小的事故，但终究还是一起事故，而且通常是被那个团队自己的值班人员发现的，而不是被这个 API 的拥有者发现的。
# consumers.yml
- service: billing-service
owner: "#team-billing"
since: 2026-03-01
- service: reporting-pipeline
owner: "#team-analytics"
since: 2026-06-14这样一份文件，把”我们到底该通知谁”从一个需要现场回答的问题，变成了一次查表就能搞定的事情。 专门为解决这个问题而生的工具，比如 Backstage 的服务目录， 出于同样的理由，把每个 API 都建模成带有明确声明的消费方的一等实体：一旦一个组织内部服务的数 量多到一定程度，就没有人的记忆能自己一直保持准确，总得有什么东西来替代记忆、承担起记录的责 任。在动手搭建一套专属工具之前，先看看你们内部已经在用的那套工具的文档，往往才是 正确的第一步。
对内体验日志的记录里，需要包含哪些对外体验日志完全用不上的内容
更多运营层面的具体细节，因为读这份记录的人是同一套基础设施里的另一位工程师，她会据此直接采取行动，而不是把它当成一份摘要来读。这个变更到底在哪些环境里已经上线、什么时候上线的，因为对内服务经常要经过一系列外部调用方永远看不到的阶段才能逐步推进。这个变更是否需要消费方那一侧做配置更新，或者更新客户端库，如果存在对应的命令，就直接写出来。还有，因为对内的调用方往往可以直接跟拥有这个 API 的团队协调修复方案，这里应该写一个指名道姓的联系人，而不是一个客服渠道：“如果这东西弄坏了什么，去找 @maria” 这句话放在一条对内记录里完全合情合理，放进一份对外的 API 体验日志里就会显得很奇怪。
这套逻辑放到 monorepo 内部的体验日志上，是不是同样成立
它让同一个问题变得更尖锐，而不是把这个问题替换掉。Monorepo 的体验日志 讲解了一个包到底什么时候需要拥有自己独立的体验日志；而一个作为 monorepo 里众多包之一而存在的对内 API，依然需要把它的消费方明确地追踪下来，因为跟调用方共用同一个仓库，并不意味着他们会自动注意到一次变更，除非有什么东西明确提醒他们该去看一眼了。仓库里的物理距离，跟注意力上的距离，从来都不是一回事。
FAQ
如果一个纯对内的 API 只有一个调用方，它还需要体验日志吗? 几乎不需要，直接给那一个团队发条消息通常就够了。一旦调用方超过一个，或者调用方名单曾经让拥有这个 API 的团队感到意外过哪怕一次，体验日志的价值就体现出来了，因为那正是记忆已经不再可靠的信号。
对内的 API 变更，应该走跟对外变更一样的评审流程吗? 措辞可以更随意一些，因为读者是同事而不是外部调用方，但一次变更到底算不算破坏性变更，这个判断在两种情况下都值得被同样认真地对待。对内的调用方，同样有依赖旧行为的生产代码在跑着。
如果从来没追踪过，该怎么找出到底是谁在调用一个对内 API? 如果消费方登记表从来没维护过，服务器日志或者 service mesh 的流量数据就是最诚实的答案；把这次发现，当成开始维护一份登记表的起点，而不是当成一次性的清理工作来对待。
一条 Slack 消息就够了吗，还是对内的变更依然需要一条正式的体验日志记录? 只要不是纯粹的新增功能，两者都需要。消息是能被及时读到的那一部分；记录则是几周后有团队在排查问题、却从没见过那条消息的情况下，依然能够找到的那一部分。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。