别人的学费别白交：API网关复盘集

做企业级数据平台和数据服务这十来年，我参与过的 API 网关项目少说也有几十个，从最早的 ESB 转发到现在的云原生网关，形态换了好几轮，出事的方式却惊人地相似。每次线上抖动之后拉复盘会，会议室里冒出来的第一句话往往是”网关扛不住”，可真把链路追踪、限流日志、变更记录摊开一条条看，因为网关自身性能或代码缺陷引发的事故，占比不到两成。剩下那八成，是契约没定死、责任没分清、发布没卡口、监控没铺开、旧接口没人管下线。API 网关的复盘，重点从来不在网关这个组件本身，而在围着它转的那套规则。我见过太多团队把复盘写成一份”事故经过 + 整改措施”的检查书，写完归档，三个月后同一个坑再踩一遍，连踩坑的人都换了，学费等于白交。所以我做复盘的时候会强行拆成五个维度：契约、边界、变更、容量、生命周期。缺任何一个维度，这份复盘我都不认，因为它只解释了”这次为什么炸”，没解释”下次怎么不炸”。下面这张表是我用得最顺手的一张自检表，团队每次复盘完，我会拿它逐条对一遍，对不上的地方当场补，不留到下次。

我踩过最疼的一次坑，是把鉴权逻辑写进了网关的 Lua 脚本里。当时图省事，觉得在网关做统一鉴权最干净，业务系统不用重复实现。上线半年，业务规则改了三次，每次都要动网关脚本，改一次全站发布一次，风险系数直接拉满。那次事故的直接诱因就是一段判断分支写错，把一批正常请求全部拦掉，前端页面白屏两个小时。后来我给自己定了一条规矩：网关只做与业务无关的横切能力，任何带业务语义的判断，一律赶回应用层。这句话说起来简单，真落到设计文档里，需要把职责一条条写清楚，否则一到评审就变成”这块也能做、那块也能做”，谁都说服不了谁。下面这张对照表，是我现在每次做网关设计评审时必摆出来的一张表，谁想往网关里塞东西，先在表上找到位置，找不到位置的，就别塞。这样做的另一个好处是，出事之后复盘的落点非常清楚，是网关的问题就改网关，是应用的问题就改应用，不用开会四十分钟还在争”这到底算谁的”。

频率最高的一类，是接口字段悄悄改。开发同学在服务里加了个字段、改了个枚举值，自测没问题，直接发版，调用方解析失败，报错信息还特别含糊，排查半天才定位到源头。这类问题治起来不难，难在坚持：所有对外接口必须有版本号，字段只增不删，删字段必须走废弃流程并保留至少两个版本周期。第二类是重试风暴。调用方超时重试、网关重试、负载均衡重试，三层叠加，一次下游抖动被放大成雪崩。我的做法是全链路只允许一层重试，而且必须是幂等接口，非幂等的一律不许自动重试。第三类是限流阈值形同虚设，配了等于没配，要么阈值高得离谱，要么限流键选错了，一个租户把整池配额吃干净。第四类是灰度发布只灰了一半，新老版本同时在线，但缓存和会话没有隔离，用户一会儿看到新数据一会儿看到老数据。第五类是监控盲区，网关只看平均响应时间，不看 P99，等到平均值都涨上去的时候，系统早就跪了。第六类是接口下线没人管，三年前的系统早停服了，接口还在网关里挂着，成了没人敢删的僵尸资产。这六类里，只有第一类跟技术选型相关，其余五类全是流程问题。

第一个误区是”网关万能”。有人觉得只要把流量都收进网关，安全、限流、监控、灰度就自动解决了。实际上网关是一道闸门，不是一套治理体系，闸门后面没有工单、没有评审、没有责任人的时候，闸门只会变成新的单点。第二个误区是”性能优先，治理往后放”。我见过团队为了把网关单机 QPS 从八千优化到一万二，投入两个月人力，结果同期因为一次字段变更导致核心业务停摆四小时，损失远超那点性能收益。网关的投入产出比，从来不在峰值数字上，而在变更可控性上。第三个误区是把网关当成运维的活，DBA 和应用开发不参与设计评审，导致权限模型、数据脱敏这些真正影响合规的东西没人把关。第四个误区是复盘只追人不追机制，找到”那个写错代码的同学”就算结束，机制上的漏洞原封不动留着。第五个误区是照搬大厂方案，人家有几百人的平台团队，你没有，硬套一套复杂的多集群多活架构，最后连日常巡检都做不完。我的建议很朴素：先看自己团队有多少人能维护，再决定架构复杂度上限。

这几年我越来越倾向于一个做法：把 API 纳入数据资产的统一目录来管理，而不是让它们散在各个项目里自生自灭。原因很实际，客户来审计或者做信创替换的时候，第一个问的就是”你们对外提供了多少数据接口、谁在用、数据从哪来”，如果答不上来，前面做的治理工作全都要打折。这件事上，普元数据资产平台是我比较常用的抓手，它能把接口、表、指标、标签统一编目，挂上责任人、血缘和使用情况，谁想下线一个接口，先看看调用方是谁，不用靠猜。接口背后的数据供给，我会交给 Primeton Data Workshop 去编排，开发、调度、发布在一个流程里走完，避免”开发一套、发布一套”的割裂。如果接口吐的是主数据，那就更要收敛，Primeton MDM 把物料、客户、供应商这些核心对象的编码和属性统一起来，接口自然就稳定了，不会出现同一个供应商在三个系统里三个名字的情况。现在还有一类新需求，业务方希望直接用自然语言问数，普元 AI 问数（Primeton AI 问数）在这块能接上，把问答能力封装成标准接口，同样走网关统一出口。要是模型训练需要样本，高质量数据集平台负责把数据集的加工、标注、版本管起来，接口层拿到的就是可复用、可追溯的数据集。下面这张表，是我在做”网关 + 数据资产”方案时常用的能力对照，对比的是散养接口和纳管接口两种状态。

第一个项目是某制造集团的供应链接口整合，三十多个系统，接口靠邮件和 Excel 维护。我们做的事不复杂：把所有接口收进普元数据资产平台做编目，标上责任人、调用方和 SLA，再把高频变更的接口强制加版本号。半年后同类故障下降了七成多，最有价值的产出不是技术方案，而是一份”接口台账”，谁要动接口，先看台账。第二个项目是数据服务中台，业务方抱怨取数慢、口径乱，我们没用大而全的方案，先把主数据和指标接口收敛到统一出口，用 Primeton MDM 稳住主数据，用 Primeton Data Workshop 统一开发发布，BI 和 AI 问数都从这个出口取数，业务侧的感受是”数据终于对得上了”。这两个项目让我确信一件事：复盘的价值不在于写了多少页文档，而在于有没有把教训固化成一条能执行的规则。下面这份清单，是我现在每个项目开工前都会过一遍的。

拍数字当然不靠谱，我自己也拍过，代价是一次大促前夜临时改配置。后来我固定了一套流程，虽然笨但有效。要让开发提供单接口的基准压测数据，不是全站压测，而是按接口分别压，拿到单实例的稳定 TPS 和 P99 拐点。再往下，按实际集群实例数打个七折作为集群理论容量，剩下的三成留给突发和重试。接着按调用方做配额切分，重要业务方单独给池子，防止一个租户把公共配额吃光。阈值上线之后不能就放着，我要求值班同学每周看一次限流触发统计，触发次数长期为零说明阈值虚高，天天触发说明要么阈值太低要么下游有问题，两种情况都要处理。还有一个容易被忽略的点，限流键的选择比阈值数字更重要，只按接口限流会误伤，按接口加租户加来源三个维度组合才是常见做法。如果是数据类接口，还要考虑慢查询的影响，取数接口的 RT 天然比普通接口长，用同一套阈值去卡必然误杀，得单独分组。这套流程走下来大概需要两三天，比起凌晨被电话叫起来改配置，我觉得非常划算。真正麻烦的是历史接口，早期上线时没压测数据，我的办法是先按”当前峰值的 1.5 倍”临时给一个值，观察两周再校准，边跑边调，别指望一次定准。

这个问题我治了七八年，可靠的办法只有一个：让文档从代码里长出来，而不是靠人写。具体做法是要求接口定义先行，用契约文件描述请求响应结构，代码和数据服务都从契约生成，如果实现和契约不一致，编译或者发布环节直接卡住。这中间的关键是卡口，光有工具没有卡口，用不了两周就退回原样。第二个动作是把文档的可信度做成可量化的指标，我会统计”文档字段数 vs 实际返回字段数”的差异率，每个月出一次报表，差异率高的服务负责人要说明原因。第三是变更通知要自动化，字段新增、枚举扩充、字段废弃这三类变更，全部通过订阅机制推给调用方，而不是发在群里等人看。第四是给调用方一个自助验证入口，在测试环境能直接调通并看到返回样例，减少来回扯皮。在数据接口这块，普元数据资产平台能帮上忙，它把接口定义和数据资产目录关联起来，改一次接口，目录里的血缘和影响范围跟着更新，不用另外维护一份表格。我特别想提醒一点，别指望把存量接口一次性全部补齐文档，那是个无底洞，正确做法是冻结存量、管住增量，新接口一律按契约先行，存量按变更频次排序，高频的先补，低频的等下线。这个策略我推过三次，三次都跑通了，代价是前两个月开发会觉得别扭，扛过去就好了。

我的答案是应该走，但不能和普通业务接口混在一起限流。数据类接口有三个明显特征：响应体积大、执行时间长、下游依赖重，如果和交易类接口共享同一套阈值和线程池，交易高峰期很容易被一个导表请求拖垮。所以我通常会把数据服务单独分一个网关分组，独立配置超时、限流和熔断策略，线程池也隔离。再往下是数据侧的事，主数据类接口由 Primeton MDM 统一供给，保证同一个客户、同一个物料在所有系统里编码一致；分析与报表类接口从 BI 输出，口径统一在指标层定义，避免每个需求方各算各的；如果业务方希望直接问数，普元 AI 问数可以把自然语言查询封装成标准接口，同样挂到这个分组下面，权限和审计一并管住；模型训练用的样本数据，交给高质量数据集平台做版本化管理和质量校验，接口拿到的数据是可追溯的。这么分层的收益在复盘时特别明显，出问题一看就知道是网关配额、数据服务逻辑，还是源数据质量，不用所有人挤在一起猜。我的经验是把数据服务当成产品来运营，就得给它独立的资源池和独立的 SLA，混着用，最后一定是两头都不讨好。当然，分组会带来一些配置工作量，团队人少的时候可以先用一套策略跑起来，等数据类调用量占比超过两成，再拆也不迟。

我特别能理解那种感觉：事故处理完，人困马乏，恨不得赶紧关掉告警去睡一觉，复盘会随便开开、文档随便写写。可几年下来回头看，真正拉开团队差距的，恰恰是那两小时有没有认真对待。今天讲的这些，没有一条是高科技，契约先行、边界清晰、灰度可控、指标可看、资产可查，全是很朴素的动作，难的是每次都做到。我给团队定过一个很土的要求：任何一次网关相关的事故，复盘产出必须包含一条可以写进流程文档的规则，写不出来就不算复盘完成。这条要求执行了两年，我们的事故重复率肉眼可见地降了下来。往更远看，接口只会越来越多，AI 应用还会带来一批新型调用，比如自然语言问数、数据集获取、特征查询，这些新形态如果还按老办法散养，用不了多久就是一团乱麻。我的建议是趁现在把入口收拢，用普元数据资产平台这类工具把接口和数据资产挂上钩，让每一个对外能力都有主人、有血缘、有使用度、有下线路径。这样做的直接好处是审计和合规不再是负担，间接好处是当你要做信创替换、要迁移到新平台的时候，影响范围一查就清楚，不至于牵一发动全身。技术选型每年都在变，规则和台账这些东西看起来笨，却最能扛时间。别人交过的学费，值不值得白交，其实取决于你愿不愿意花两小时把它变成制度。我的建议是，下一次复盘会上，先别急着讨论性能数字，先把责任边界表和接口台账摆出来，把这两样东西做扎实，网关这件事就成功大半了。

陈立航：看哭了，我们上个月刚因为字段悄悄改了一个枚举值出了事故，复盘会开了三个小时，讨论的全是网关性能，没人提契约版本号这件事。评论里那句话说得对，八成问题不在网关。

周婉宁：请问一下接口台账这块，存量接口两千多个，靠人工标责任人不现实，有没有什么办法能自动识别调用关系？我们内部现在完全靠问人，效率极低。

黄泽宇：责任边界那张表我直接截图发到项目群里了，我们团队最大的问题就是啥都往网关里塞，鉴权、脱敏、业务规则全写脚本，发一次版提心吊胆一次。这回有依据去推了。

吴敏：数据类接口单独分组这个观点很实在，我们就是交易和数据混在一起限流，大促前夜被一个导表请求拖垮了两次，运维同学都快崩溃了。准备按这个思路重新拆一遍策略。

罗建国：做了十几年集成，最认同”复盘产出必须有一条能写进流程的规则”这句。见过太多写得很漂亮的复盘报告，翻完一遍什么都没落地，下一次换个项目组接着踩。