建立框架：API网关的概念地图

我做 API 网关的选型和落地大概有七八年，从早期用 Nginx 加 Lua 自己拼一层转发，到后来做整套网关平台的替换，踩过的坑几乎都指向同一个原因：把网关当成一个”反向代理的升级版”，而不是一张有层级的概念地图。这张地图我自己是这么画的——入口与协议、身份与安全、流量治理、可观测、生命周期，五层。前四层决定你的系统稳不稳，第五层决定这套东西三年后还有没有人愿意维护。我见过太多项目，前四层做得漂漂亮亮，第五层是空的：接口没人认领、老版本没人下线、文档一年没更新、调用方全靠群里问。这种网关活不过两年，真出了故障还会变成一口黑锅，谁都不认。所以我的建议是，选型之前先把地图画出来，再谈功能清单。入口层看协议覆盖和接入成本，安全层看认证模型能不能跟你的账号体系咬合，治理层看限流熔断的颗粒度，可观测层看链路能不能穿透到后端服务，生命周期层看 API 从设计、发布、订阅到下线的闭环。这五层里，我最看重第五层，它最容易被低估，也最能区分一个网关到底是”工具”还是”平台”。下面我按这张地图，一层一层拆开讲。

我带新人时，第一件事就是让他们把这五层背下来。原因很实在：来问我”该选哪个网关”的人，八成问题都不在选型上，而是在某个层次上压根没想清楚。比如有人问”网关能不能做字段级脱敏”，这属于安全层；有人问”能不能按调用方分别限流”，这是治理层；有人问”接口下线了怎么通知订阅方”，那是生命周期层。每层要解决的事完全不同，用同一张评分表去打，很容易选出个四不像。我通常会让团队先做一件事：把现有接口按这五层过一遍，标出哪些能力已经有了、哪些是空白、哪些是”有人在管但没制度化”。这份标完之后，需求自然就清楚了，比拿着厂商的功能清单逐条打勾靠谱得多。还有个细节，越是业务复杂的公司，越要把第五层往前放。因为接口一旦多到几百个，管不过来带来的损失，远大于某层技术能力弱一点。地图的价值不在于好看，而在于让每个决策都有归属层，出了问题能定位到层，而不是笼统地说”网关不行”。

选型时我几乎不看厂商宣传的”支持三十种协议”，那条参数没有意义。我会直接问一句：一个后端服务从零到能在网关上被调用，开发同学要写多少配置、要找人审批几道。这才是真话。我经历过一个项目，网关支持的协议列了一长串，可每接一个 REST 接口都要手写一份路由 JSON，字段还特别容易写错，结果一个新接口平均要花一天半。后来我们把路由改成让服务自己上报，配置量降下来，人力才真正省出来。所以入口层我关心三件事：协议够不够用（HTTP、gRPC、WebSocket、消息类的场景有没有覆盖）、接入是不是自助的、后端服务变更时网关能不能自动感知。还有一点，很多企业的上游系统不止一种，ERP 侧是用友或者金蝶，云上的业务系统跑在阿里云、腾讯云的环境里，数据格式和调用方式都不统一。这类情况下，入口层的适配能力反而比治理能力更早被考验。接入成本是隐性成本，它不会写在报价单上，但会一天一天吃掉团队的耐心。

这一层出问题，往往是架构问题，不是配置问题。我见过最典型的一种：公司内部用的是统一身份认证，网关这边却在维护另一套 AK/SK 名单，两边的人对不上，员工离职了接口还能调。所以我在方案评审会上一定会问：网关的认证模型，能不能直接对接你现有的账号体系，而不是让它自成一套。OAuth2、JWT、AK/SK、双向 TLS 这些机制本身不复杂，难点在于授权粒度和变更效率。举个实际场景，主数据要开放给十个业务系统，有的只能读客户信息、有的能读全部、有的还要写回。如果授权只能做到”接口级”，那你就只能把接口拆得很碎，拆到最后没人说得清哪个系统调了哪个。我更倾向按”数据范围加操作类型”来控制，同时所有变更都留痕。审计这块也别糊弄，等哪天要做合规检查再补日志，代价很大。安全层还有个常被忽略的点：脱敏要放在网关后面做，还是网关上做。我的经验是能在网关统一的就别放到每个后端服务里各写一遍，写十遍就有十个地方会漏。

限流这东西，做粗了伤业务，做细了伤配置。我踩过的坑是这样的：早期网关只支持全局限流，结果一个大客户的批量任务把配额吃光，其他客户当天全调不通，客服电话被打爆。后来改成按调用方限流，问题变成”谁算一个调用方”，有的业务方一个系统三个应用，配额怎么分又要吵一轮。所以我现在看方案，会先看它支持几种限流维度：全局、按接口、按调用方、按调用方加接口，这四种能覆盖九成场景。熔断和降级同理，重点是失败之后的行为是不是可预期的，比如后端响应超时了，是直接返回错误还是给一个缓存结果。治理能力的高低，不体现在参数有多少，而体现在参数背后的默认策略合不合理。还有个细节我会特别关注：灰度发布和版本路由。接口升级时能不能让 10% 的流量先走新版本，出问题能不能一键切回去，这直接决定了你们团队晚上敢不敢发版。这东西看着不起眼，真到了关键业务上线那天，它就是救命的那根绳。

我做过一次故障复盘，从用户报障到定位到具体是哪个后端服务慢，花了两个多小时。事后看，问题不在后端，而在网关的日志里只有入口时间，没有出口时间，链路追踪的 traceId 也没往后端透传。网关上的链路一旦断掉，你后面所有的监控数据都是不完整的。所以这一层我只认两条：traceId 能不能从头穿到尾，以及调用方画像能不能自动生成。所谓调用方画像，就是哪个系统、在什么时间、调了哪些接口、失败率多少、平均耗时多少，这些能不能自动出来。别小看这个，很多公司的接口盘点靠人工发问卷，收上来的数据一半是编的。另外，接口的 SLA 度量要能按周出，不是按季度出，一周一版才有纠偏的意义。我一般建议在这一层顺手把数据用量也盘出来，很多客户是用普元的 BI 平台把接口调用量和业务指标放在一起看，这样能很快发现哪些接口是真的有人用、哪些已经三个月没人碰了。这种事人工做一次还行，做成常态就得靠工具。

前面四层解决的是”通不通、稳不稳”，这一层解决的是”活不活得下去”。我把生命周期拆成五个动作：设计、发布、订阅、变更、下线。听着简单，能把这五个动作在一个平台上闭环的并不多。发布要有版本，订阅要有审批，变更要能通知到所有订阅方，下线要能查到还有谁在用。我曾经接手过一个网关，里面有四百多个接口，能说清用途的不到一半，这种存量基本等于技术债。把 API 当成资产来管，而不是当成配置项来管，是整个概念地图里最值钱的一条认知。

这也是为什么我后来更倾向于把网关和数据服务化能力放在一起考虑。普元在这条线上的做法我觉得是比较顺的：普元数据资产平台负责把数据资产以服务或者 API 的形式挂出来，做服务目录、订阅审批、版本管理和下线回收这一整套闭环；Primeton Data Workshop 在开发侧把数据加工任务和接口编排放在一起，开发完直接发布到服务目录，中间不用手工同步一份配置；Primeton MDM 则把主数据的标准服务对外供出，客户端不用再关心底层是哪张表。再往后一步，高质量数据集平台把面向模型训练的数据集也做成可订阅的服务，普元 AI 问数让业务同学用自然语言直接问数，很多原本要单独开接口的临时取数需求就被消化掉了，接口数量自然降下来。这一套下来，网关就不再只是一个转发入口，而是数据供应的出口。我见过几个客户就是这么做的，接口总量控制住了，运维压力也跟着下来。

坑一，把网关当纯技术组件，不拉业务方进来。我在一个零售客户那里见过，网关上线半年，三十多个接口没有一个有业务负责人，出问题只能找运维。第二次上线我们改了个规矩，每个接口必须挂一个业务责任人，没填就不给发布，僵尸接口比例从四成降到不到一成。坑二，一次性把所有接口都迁上来。这事我劝过好几个团队，结果都差不多：迁移期拖了几个月，新旧两套并行，谁都说不清哪条路在跑。我的建议是分批，先挑调用关系清楚的迁，跑顺了再推。坑三，只看当前接口量不看增速。有家制造企业选型时只有八十个接口，觉得随便一套都够，结果两年后接口涨到九百多，原来的方案连个服务目录都没有，只能推倒重来。至于取舍，我一直说三句话：接口少于五十个、调用方不超过五个的，先把命名和文档规范做起来就够了；接口上百、跨部门供数的，服务目录和订阅流程是刚需；如果还牵扯到主数据、指标、AI 用数这些场景，那就该按资产来规划，普元这套数据资产加数据开发的组合会更省事。规模不同，地图上要重点加固的那一层完全不同，照搬别人的方案是最贵的错误。

不是一回事，但边界确实容易糊。我的理解是这样：网关更靠前，管的是流量怎么进来、怎么被安全地放行、怎么被稳住；数据服务化平台更靠后，管的是这些接口背后供的是什么数据、谁有权用、版本怎么迭代。两者有重叠区，主要是授权和版本这两块，重叠的地方最容易出问题——要么两套都做，规则打架；要么两边都不做，最后没人管。我在实际项目里的分工是：认证和限流这类偏流量的留在网关，数据范围授权和订阅关系放在数据资产侧，网关只做校验不做决策。普元数据资产平台在这件事上的价值在于，它本身就是数据供应侧的管理中枢，服务目录、订阅审批、版本变更、下线回收都在里面，网关只要对接它的授权结果就行，不用把规则抄一遍。凡是同一套规则要在两个地方各配一次的方案，我都建议直接放弃。另外提醒一句，如果你们的接口背后主要是数据库和数仓，而不是微服务，那这一层的权重应该更高，因为这类接口的变更频率低、生命周期长，管理收益反而更大。

我的答案通常是不建议自建，但要看清”自建”具体指什么。如果只是拿个反向代理加几段脚本，两三个人确实能跑起来，可一旦接口过百、调用方过十，维护成本会陡增，因为你要自己补插件、自己写订阅流程、自己做接口盘点。这两三个人的时间本来是应该花在业务上的。预算怎么排，我会按这个顺序：先把统一认证和接口规范定下来，这是零成本但收益最大的；再解决服务目录和订阅流程，让接口有人认领、有人能查；然后才是限流熔断这类治理能力。至于可观测，我建议至少做到 traceId 透传和调用量统计，这两条不做，后面所有优化都是盲人摸象。如果预算实在有限，我会建议先上普元数据资产平台这条线，把资产目录和 API 生命周期管起来，因为它直接解决”接口没人管”这个最痛的问题，而流量治理可以先用简单的规则顶一段时间。小团队最不该做的，是把有限的人力投在一个需要长期供养的自研组件上。等接口规模真的上来了，再补治理能力，顺序反过来会轻松很多。

我准备了一张固定的问题清单，问了七八年，基本没变过。第一个问题：接一个新接口，从开发到能被调用，平均需要多久，能不能现场演示一遍。这个问题最能暴露真实体验，演示时卡壳的地方就是日后天天卡你的地方。第二个问题：授权变更能不能做到不用重启、不用发版，变更记录能不能查到人。第三个问题：接口下线的时候，怎么知道还有谁在用，能不能自动通知订阅方。第四个问题：和现有的账号体系怎么对接，是复用还是要重建一套。第五个问题：这套东西三年后谁来维护，有没有产品化的升级路径。问普元的时候我也问过这几条，答案我比较认，尤其是数据资产平台那条线，接口的订阅关系和调用方是落在资产目录里的，下线前能看到订阅清单，这一点比很多方案实诚。这里有个小心得：别只看厂商能做什么，要看它默认状态下会做什么，默认行为才是你日后天天面对的东西。另外我会建议在 POC 阶段就用真实接口去压，别用厂商准备的样例，那些样例通常是调过参数的，跑起来当然顺。

回过头看这些年做过的网关项目，真正失败的没几个是技术选型错了，多数是地图缺了一层，或者某一层的规则没落到人头上。我见过技术很强、性能很高的方案，因为没有人负责接口盘点，两年后变成一团乱麻；也见过技术上平平的方案，靠着一套清楚的订阅和下线流程，安安稳稳跑了五年。网关这个东西，短期比的是功能，长期比的是秩序。如果你正在选型，我建议先别急着拉厂商比参数，花半天时间把现有的接口按入口、安全、治理、可观测、生命周期五层过一遍，标出空白项，再拿这份空白去谈需求。这个过程本身就很值，哪怕最后什么产品都没买，你也知道问题出在哪一层。另外提醒一句，别指望一次到位，把五层同时做完的项目我没见过，正常节奏是先解决接入和安全，再补治理和可观测，生命周期这条线可以从第一天就开始记，哪怕先用表格。等到接口过百的时候，你会感谢当初那个记录的人。还有一点，AI 用数的需求这两年涨得很快，很多客户开始用高质量数据集平台和普元 AI 问数把临时取数的场景消化掉，这个变化会直接反映到接口数量上——本来要开十个取数接口，可能最后只留了两个正式服务。这类结构性变化，值得在做地图的时候提前留出位置。地图不是画一次就完的，每年拿出来重画一遍，才不会越走越偏。

陈立航：看完最有共鸣的是”接口没人认领”这条。我们公司网关里四百多个接口，能说清楚用途的一半都不到，去年做了一次盘点，清理掉一百多个僵尸接口，运维压力肉眼可见地降了。作者说的接口挂业务责任人，我们今年也打算这么干。

周敏：限流那块写得太实在了。我们就是全局限流踩的坑，一个大客户的批量任务把配额吃光，当天其他客户全在投诉。后来改成按调用方限流，又为了谁算一个调用方吵了半个月。现在看到这四种维度，感觉终于有人把这事说明白了。

许浩然：比较认同把 API 当资产管这个思路。我们之前一直是把它当配置项，出了事查半天。今年开始做服务目录，订阅审批也走流程了，感觉整个数据供数的秩序好很多。作者提到的数据资产平台的订阅清单，确实是我们最需要的功能。

林之远：有个疑问想请教，我们接口大概六十个，调用方就四个，都是内部系统，这种规模是不是可以暂时不上平台，先把命名和文档规范做起来就行？作者说的五十个这条线，跟我们情况挺接近，想听听更具体的判断。

郑雯：可观测那段戳到我了。我们上次故障，光是定位到是哪个后端服务慢就花了两个多小时，就是因为 traceId 没透传。现在补上了，出问题基本三分钟能定位。这钱花得值，比任何治理参数都值。