凌晨三点半手机在床头柜上震得跟台豆浆机似的。我爬起来瞄了一眼钉钉群炸了锅结算系统挂了一夜财务对不上账前端在群里我说接口明明返回200但数据就是不对。我打开IDEA翻到那个三千行接口的主方法目光越过三层try-catch落在最深处那个catch块——它把所有异常都吞了最后返回了一个假得不能再假的“success”。那一刻我明白了这个系统烂不是烂在代码而是烂在每一个接口设计的起点。后来那个系统被推倒重写但我在之后换过的三家公司里同样的故事换了张脸继续上演数据库被脱裤是因为接口信任了任意字符串下游开发炸毛是因为没人通知字段类型从int变成了string线上告警响彻是因为一个接口把熔断和重试全写进了同一个catch块。三年了我从一个只关心“能不能跑”的后端开发慢慢变成每天琢磨“接口该怎么设计”的人。这份思考沉淀出五个经验每一个都是用事故换来的。接口是一份契约不是一段代码很多后端新人对接口的理解是错的——他们以为接口就是“把参数传进来、把结果算出来”。但真正的接口设计是在定义一份契约。契约的一方是你另一方是所有可能调用你的人。这份契约一旦建立就自动获得了合法性下游基于它做开发基于它做测试甚至基于它做商业决策与对账。所以接口设计的第一原则是不要轻易违反契约。具体来说这意味着三件事一个接口尽量只表达一个业务动作把“创建用户发验证码初始化邀请码”揉进一个接口里不叫优化叫给联调埋雷接口的语义要稳定字段名宁可长一点也不要为了省事用data、info这种万能词接口的响应结构应当与业务模型对齐而不是与数据库表对齐。我在第二家公司接手过一个“万能接口”前端叫它“上帝接口”一个POST /api/v2/query入参是一个宽容到没有边际的JSON没有任何强约束后端根据“猜到”的操作类型决定查库还是调下游高峰期只能靠盯日志来猜它在干什么。后来我们把它拆成十二个语义明确的端点性能没有变好——但所有人都松了一口气。记住一句话接口设计的本质是定义一场谁都无法轻易反悔的承诺。每一次对已有接口语义的偷偷篡改都是给未来埋下的一颗定时炸弹。参数校验的位置就是信任的边界我见过太多后端同学把参数校验当作“胶水代码”随便写几行if然后让前端注意一下。但真正的接口设计把参数校验当作系统的第一道护城河。一个接口暴露在公网它的入参校验就是你的主机防火墙——永远不要信任入参就像永远不要信任一个刚刚认识的人。参数校验有三层讲究语法层管类型对不对、必填有没有、长度超没超业务层管状态是否合法、角色有没有权限、上下文匹不匹配安全层管SQL注入、SSRF和批量抓取企图。这三层缺一不可而且应该在Controller入口处就全部拦截不要让脏数据渗透到Service和DAO层。我自己有个习惯入参一律用DTO而不是Map。DTO的好处是类型安全、字段明确、校验注解能直接挂在字段上。我曾经在一个项目里把校验全部下沉到数据库层结果就是接口拿着空指针到处碰壁数据库被无效请求打得雪上加霜。更细一层校验错误要返回得精准。一个清晰的field: xxx, reason: too_long, allowed_max: 50比一套{code: -1, msg: 参数错误}要动人得多。校验信息的颗粒度反映着你的接口对下游到底有多尊重。状态码乱用是接口灾难的源头我永远忘不了那个凌晨三点爬起来修bug的夜晚——不是因为修不好而是因为我发现那个接口压根没报错。它返回了200把数据库连接超时的异常吞进一个空壳JSON里。前端写了“如果status不为200就走兜底”的逻辑结果一个200砸过来前端直接渲染一个空白页面用户还以为系统在正常上班只是暂时没有数据。一个接口的HTTP状态码应该精确表达这次请求的结果2xx是成功4xx是你在说客户端有问题5xx是你在承认自己有问题。这不仅是规范更是合作者之间的暗号。那些把所有业务失败都塞进200的接口是把让下游批判你的机会一并吞掉了。正确做法是把业务状态码和HTTP状态码分开HTTP状态码负责“这趟请求到底成没成”业务码负责“如果没成到底为什么”。两者合起来配上一个统一结构的错误响应——包含code、message和traceId前端拿到就知道该弹什么提示告警系统拿到就知道该通知谁你自己拿到traceId就能二十分钟追上根因。我见过一个最让我无语的接口出错时返回200响应体里塞了一个success: false然后在message里用中文写了一段模糊的说明。前端想做任何自动化错误处理都不可能只能靠手写正则去匹配那段中文。永远返回200的接口是后端写给前端的棺材板。演进只做加法接口发布的那一天它就开始衰老。因为下游每有一行代码基于它编译它就被固化了一份。这是我在第三家公司做支付网关时的切肤之痛——一个叫payOrder的接口上线半年后产品经理提了一个看似合理的需求“给订单加一个paid_type字段区分支付方式。”如果我不坚持保留旧字段、新增一个payment_method_v2而是直接把已有的paid_type从“1微信2支付宝”改成“1微信2支付宝3线下”那么所有没有适配“3”的下游系统都会把线下支付当成未知异常处理。接口演进的最佳姿势是加法而不是减法。新增字段时给默认值扩展枚举时不要删掉旧值废弃接口不要直接下线先标记Deprecated给足六个月的过渡期统计访问量确认归零后再移除。URL版本号还是请求头版本号其实只是形式问题真正重要的是你必须在物理上隔离两套语义。更深一层的纪律是永远不要去修改一个既有接口的既有行为除非你准备同时承担所有下游的愤怒。想要改接口就做一个新版本。让接口像洋葱一样生长而不是像楼房一样重建。洋葱的每一层都是独立的剥掉任何一层都能看到完整的核心而楼房一旦推到失去的不只是代码还有整个业务信任度。幂等、限流与兜底是接口的保命设计接口设计不止关于“正常情况下怎么工作”更关于“异常情况下怎么不炸”。三年里我处理过的最惨的一次线上事故是订单系统因为一个重试机制设计错误的接口导致用户重复支付库存被扣了两次最后靠财务手工退款才平账。幂等设计是接口的保命符。对任何可能被重复提交的接口——创建订单、支付回调、消息通知——后端必须设计一个幂等键。同一个幂等键进来返回同一个结果。Redis里用幂等键加结果缓存是最简单可靠的做法。一个没有幂等的接口在重试窗口里就是一台无差别伤人机器。限流是接口的保底底线。无论你的机器扩容到多大总有一个上游会比你先疯狂。令牌桶、滑动窗口、漏桶——不管你选哪种算法都必须保证当流量超过接口承载能力时返回429 Too Many Requests而不是让系统挂掉。因为挂掉的系统连返回错误的能力都没有了。兜底的意思是接口的异常处理要以“不扩大伤害”为第一优先级。重试要有退避熔断要有半开状态超时时间要有上限。我在代码评审里最常问的一句话是“如果这个接口最慢的场景是十秒你愿意等吗”如果答案是不愿意那你的接口就该设计成异步的。我把这些都归结为一句话接口设计的天花板不是你能承受多少并发而是你能扛住多少错误。并发高只是热闹错误可控才是体面。结语好的接口是让未来的自己少一点恐惧回到最开始那个凌晨。如果那个接口在设计之初就做到了这五件事那次事故根本不会发生。三年过去我逐渐意识到接口设计其实是一场“反人性”的修炼它教的不是怎么把代码写得更炫而是怎么让代码变得无趣、稳定、可预期。好的接口看起来平平无奇但它在暴雨天不会漏水在潮水般涌来的请求前不会崩塌。现在我每写完一个接口都会问自己两个问题如果两年后的我接手这个接口他会觉得它清晰、聪明、敢想敢做还是觉得它像一个没盖好的筒子楼里面堆满了意图不明的胶带如果这个接口的下游是个比我还精明、还挑剔的同事他会不会一眼看穿我偷懒的地方接口设计不是写给人看的而是写给未来说“这代码还能怎么改”的人看的。三年了我最大的成果大概不是完成了多少功能而是尽量少地伤害了那些将来要维护这套代码的人。这五个经验就是我的全部家底。