很多人是在两种时候卡住的：写需求文档时把「做个 HTTP 接口」和「做个 API」混着说，结果约定不了返回体；或者对接第三方时对方只给了一份 HTTP 文档，自己却按完整 API 的思路去设计错误码和版本。这篇只讲一个角度：这两个词是什么包含关系、混淆点在哪、动手时按什么顺序判断，帮你在设计和对接前把话说清楚。
很多人卡住是在两个具体场景：写需求文档时把「做个 HTTP 接口」和「做个 API」混着说，评审时才发现没人写清返回体长什么样；对接第三方时对方只甩来一份 HTTP 文档，自己却按完整 API 的思路去设计错误码和版本策略，上线后一改字段就全断。这两件事的根子是同一个：没分清能力约定和传输方式。
这篇只讲一个角度：这两个词是什么包含关系、混淆点在哪、动手时按什么顺序判断。不谈协议原理，也不谈框架选型，目标是让你在设计和对接开工前，能把话说清楚、把表定下来。
先分清：一个是能力约定，一个是传输方式
API 接口说的是「谁能调、传什么、返回什么」这层约定，它关心的是字段、鉴权、错误码和版本；HTTP 接口只是这层约定最常见的一种承载方式，回答的是路径、方法、状态码怎么走。所以两者不是并列的两个选项，而是包含关系。
- 能力约定
- 字段名、类型、必填与否、错误表达、鉴权方式、版本策略，脱离协议也能写清楚
- 承载方式
- 用哪个协议、路径怎么排、方法用哪个、超时和重试怎么配
- 常见问法的问题
- 问「用 API 还是用 HTTP」等价于问「用汽车还是用汽油」，问题本身就把两层混了
判断口径很简单：先定能力约定，再定承载方式。顺序反过来往往要返工——先挑协议再想字段，容易出现「这个状态码顺手就拿来当业务结果了」的将就设计，后面加业务分支时无处安放。
四个最容易吵起来的混淆点
下面四个点几乎每次接口评审都会遇到。逐个对上，能省掉大半来回。
| 混淆点 | 表现 | 怎么改口 |
|---|---|---|
| 只给 URL 不给字段说明 | 对方给了一串地址，返回体结构没写，字段一变调用方就断 | 先要一份字段表：名称、类型、必填、空值表示，再谈联调 |
| 把状态码当业务结果 | HTTP 层成功就直接判定业务成功，失败信息塞在响应体里没人看 | 把两类成败分开表达：请求本身的问题和业务失败各给稳定标识 |
| 把内部函数调用说成 API | 同一团队里这个词指函数调用，另一个团队以为是网络接口 | 先对齐本团队语境，文档里写清是进程内调用还是跨网络调用 |
| 把第三方 HTTP 文档当万能 | 文档没写的限流口径、字段含义、版本策略默认自己猜 | 单独列一份待确认清单，联调前逐条问回来 |
其中第二点危害最大。请求合法但业务失败时，如果只靠 HTTP 状态码表达，调用方就无法区分「重试有用」和「重试没用」两种情况，重试策略会写歪。
按什么顺序做：从约定到承载
顺序定下来之后，具体动作可以拆成四步。每一步都有可验证的产出，不是写完就算。
- 先把输入输出写成表字段名、类型、必填与否、空值怎么表示，一行一个字段。验证方式：找个没参与设计的同事只看这张表，能说出调用步骤就算过关。
- 再选承载方式多数业务走 HTTP 就够；需要长连接、服务端推送或流式返回时再单独评估。验证方式：写下选它的理由，以及不选另一种的原因。
- 定错误表达区分「请求本身有问题」和「请求合法但业务失败」两类，各自给稳定、可枚举的标识。验证方式：列五个典型失败场景，看能不能各自对应到一个标识。
- 留版本位在路径或请求头里预留版本信息，后续加字段不至于打断老调用方。验证方式：假设下个月要加一个必填字段，推演老调用方会不会挂。
第三步的枚举值建议单独维护一份清单，新增失败场景先加清单再改代码，避免同一个含义在不同接口里用了不同的标识。
什么情况下这套判断不适用
上面这套流程不是所有场合都值得走一遍。以下三种情况硬套反而拖慢进度，判断标准是：改动成本落在谁身上、有没有跨团队协作。
- 纯内部函数互调，不跨进程也不跨团队：不必套完整接口约定，写好函数签名和注释就够，过度设计反而拖慢
- 对接的是别人已经定死的接口：约定部分你改不了，能做的只有调用侧的超时、重试、容错和字段兜底，把精力放在适配层
- 对实时性要求极高的长连接场景：请求响应模型本身不合适，先换承载方式，再回头谈约定；此时先定协议反而是对的
还有一种边界情况：团队规模很小、接口只服务自家一个前端，此时字段表可以简化成一段说明，但错误表达的区分建议保留，它是后期排查的主要线索。
如果你正在做选型，涉及具体工具的耗时和稳定性表现，别拍脑袋，去站内 /tools/speed-test 实测一下再下结论；不同网络环境差异不小，别人给的结论不一定适用于你。
下一步把你这边的接口按「约定层」和「承载层」各列一张表，缺哪张补哪张；顺带看看站内指南中心里关于对接排查的整理，能少踩几个常见的坑。→常见问题
是不是所有 HTTP 接口都算 API 接口？
大体算，但不等于完整。一个只暴露 URL、字段和返回结构都没约定的 HTTP 端点，只是「能通的地址」，对调用方来说还不构成可依赖的约定。反过来，API 也不一定非走 HTTP。判断时看有没有稳定的输入输出约定，而不是看用了什么协议。
团队里有人把这两词混用，怎么统一？
最简单的做法是在文档模板里固定两栏：一栏写「接口约定」，只放字段、错误码、鉴权与版本；另一栏写「访问方式」，放协议、路径、方法、超时。开会时先问清对方指的是哪一栏，多数争论当场就消了。
选 HTTP 还是别的承载方式，看什么？
看交互形态：一问一答、调用方主动发起，HTTP 就够；需要服务端持续推送、或者连接要长期保持，就该考虑别的通道。另外看团队现有基建，已有的网关、监控、鉴权能不能复用，往往比协议本身的技术优劣更影响决策。
