简介API 接口设计规范是一份面向后端开发者、前端联调人员及接口负责人的标准化文档用于统一接口路径、参数、返回结构和错误码约定减少前后端联调过程中的返工与歧义。内容覆盖接口设计原则、JSON/日期/金额/时间格式、路径设计、请求与响应参数、错误处理及安全性要求明确 /版本/业务功能/表名/行为 的路径规则给出 limit、offset、page、per_page、sort_by、order 等通用参数以及 code、success、message、data、list、total 等响应字段并包含 token 鉴权、HTTPS 加密、签名校验、敏感字段加*等安全约束。包内含 1 个 docx 文件压缩包大小仅 20KB轻量便于团队内部直接分发与参照执行。目前已有 3578 人学习下载可用于接口设计评审、编码检查及新成员规范培训。1. 接口设计规范不是文档是团队的契约先搞清它到底解决什么很多人第一次接触「API接口设计规范」这六个字以为它就是一份写满了「接口要优雅」的文档谁有空了就翻一眼。真实情况是后端七八个服务各自为政URL 命名有的用驼峰有的用下划线分页参数三种写法并存错误码靠猜联调会开成吵架会。把这份规范立起来本质不是约束风格而是把散落在每个开发者脑子里的接口隐性知识变成团队都能读、都能改、都遵守的契约。它解决的是「新人不敢改接口、老手不愿解释接口、测试无法断言接口」这三件事。这篇文章写给前端对接方、后端工程师和负责接口质量的技术负责人不讲空话讲怎么起草、怎么落地、哪些坑我替你踩过。2. 规范管哪些事从 URL、命名到错误码的五个组成模块接口设计规范的第一件事不是写条款而是划边界。规范只能管「接口长什么样、怎么被调用、调错了怎么告诉别人」不该管每个服务的业务逻辑。边界清楚了才不会被塞进一堆与接口无关的内容也不会在评审时被追问「这条跟接口有什么关系」。2.1 风格基线先定死REST 与 RPC 的取舍不是技术选型是协作成本接口风格在动笔之前就要定死。相比内部服务用的 RPC选 REST 作为对外的基线是性价比最高的选择前端用 HTTP 直连调试工具、网关、文档生成器都伺候得妥妥当当配合 OpenAPI 描述文件文档、Mock、客户端代码都能自动生成省掉大量手工同步的时间。下面这张对比表可以贴进评审文档里维度REST (HTTPJSON)RPC (gRPC 这类方案)对外友好度前端直连、curl 可调试需要生成客户端桩调试门槛高工具链网关、文档、监控全生态强类型契约好但文档展示弱适用场景Web/移动端/开放接口内部高频调用、低延迟场景协作成本跨语言低成本每次协议升级都要同步所以规范里要写清楚对外统一走 REST内部服务如果已有成熟的 RPC 体系可以保留但新接口不许混着来。这条边界比争论「谁更好」重要得多。再补一句「复杂动作不要硬拗资源语义」的免责条款批量操作、结算这类动词型场景用 POST 动作名比如/orders/batch-cancel完全没问题。这条能救回很多较真的人。2.2 URL 与命名一份正反例对照表解决「动词派」与「驼峰派」之争URL 命名是接口规范里最容易吵架、也最容易照抄的部分。基线规则就四条用小写 kebab-case「order-detail」而不是「orderDetail」资源用名词复数/orders而不用/getOrder层级不超过三层路径里只放资源标识不放动词和请求参数。这个原则确定之后整个团队的接口样式就有了统一的骨架。反例写出来触目惊心/api/order/getOrderByUserId?userId1这种写法既有驼峰又有动词看着短实际是后面所有调用方的噩梦。规范化的写法是GET /users/{userId}/orders语义清楚还能复用通用鉴权。把一张正反例对照表放进规范比任何解释都有用反例问题正例/api/getUser动词 单数GET /users/{id}/OrderDetail驼峰命名/order-details/orders/1/items/2/status层级超过三层提取独立子资源或操作资源/orders?userId1statusPAID过滤条件全堆在 querystatus 用枚举约束按用户查走 /users/{id}/orders命名规则要一竿子插到底字段名用驼峰还是下划线不要两个都留。各家生态习惯不同选哪种我无所谓但规范里只能选一种对外报文必须统一。写清楚这条前端和后端就不用反复对字段名了。2.3 版本、日期与数据格式把最容易起争议的传输细节写进条款版本策略多数团队用 URL 路径版本/v1/orders、/v2/orders理由是对调用方最友好网关也好做路由。Header 里传版本号也能实现但调用方看不见摸不着出了问题不好排查所以我建议新团队直接用路径版本。规范里写明主版本不兼容更新时 URL 版本号必须递增小版本变更允许向后兼容不升版本。日期时间格式是典型的「小规则省大麻烦」全网统一 ISO 8601 带时区例如2025-06-01T10:30:0008:00传输一律 UTC展示层再转本地。禁止让前后端各自格式化禁止传时间戳让前端猜单位。这条不写迟早会出现「这个到底是毫秒还是秒」的血泪故事。还有三件小事别忘了ID 统一用字符串型别让大整数在 JS 端丢精度金额用整数分不用浮点元枚举值如果会变传输层传稳定标识码不传中文或序号。2.4 错误码和 HTTP 状态码分工一个描述传输一个描述业务这一节是整个接口设计规范最容易翻车的部分也是联调时吵得最凶的。我的结论HTTP 状态码只管「请求有没有被正常处理」业务失败原因全部交给应用层错误码。用户下单失败返回200 code30001完全合法返回 404 表示资源不存在而不是业务不存在谁也不用夹带私货。错误码分段要有可读性权限类 10000 段、资源类 20000 段、参数类 30000 段、依赖服务类 40000 段、系统异常 50000 段。段位定了调用方看错误码第一眼就大概知道问题出在哪层。每加一个新错误码必须走登记禁止业务方自己发明随意数字。配套规则是响应体必须带开发者可读的 message但不能指望前端直接展示后端原生文案。规范里写一句「message 面向开发者展示文案由客户端根据错误码映射」前后端边界就清楚了。2.5 安全、限流与审计条款接口规范里的安全底线鉴权方式必须统一Token 放Authorization: Bearer token禁止放 query 参数——token 一进 query 就会跟着 URL 进网关日志和浏览器历史等于裸奔。对外开放接口如果走签名字段排序、加签算法、失效时间要写清楚否则合作方便一头雾水。限流不只在网关做协议上也要有约定触发限流返回 429并带Retry-After头告诉调用方多久后重试而不是静静超时。审计方面每个写操作都要有traceId贯穿调用链日志里脱敏手机号、身份证、支付账号等字段。接口规范里带上这三条等于是给后续的安全审查提前打好了底。3. 从零起草一份可落地的接口设计规范盘点、定稿与发布路径起草规范不是搜一份模板改个标题就发群里那是「写了没人看」的高发源头。我见过太多团队拿到现成模板就复制粘贴结果条款和自家技术栈对不上最后成一纸空文。这一章按我自己习惯的步骤拆解照着走不会跑偏。3.1 第一步先盘点存量建一张接口资产表而非直接开写规范动笔前先盘家底。把现有服务的接口列个清单统计风格、鉴权方式、错误码规范程度这张资产表能告诉你「最该约束什么」和「存量改造要花多大代价」。没有这份数据规范就是拍脑袋定的。统计项统计方式用途接口总数按服务/网关路由统计定改造优先级URL 命名风格占比抽查 正则统计确定命名条款鉴权方式检查是否有统一策略划定安全条款范围错误码规范程度看返回结构是否统一决定错误码工作深度分页/日期格式抽查典型接口找高频痛点统计完你会发现存量接口没必要一次性全改。规范先覆盖新增接口存量按风险分级逐步改造这条原则能帮你在第一个月就避免「规范要求与线上现实互相打架」的尴尬。资产表本身也是向团队要改造资源的最好材料。3.2 第一版只做「止血」五条必约束项拒绝完美主义第一版规范千万别追求全面追求「止血」。被广泛遵循的接口规范通常只约束五件高频摩擦的事鉴权放哪、成功和失败响应长什么样、日期和金额格式、分页参数、URL 命名。这五件事覆盖联调中 80% 的争论也最容易在代码评审里核对。其他内容比如幂等、限流、版本下线可以放进第二版但规范里留「计划中」的占位段落。这样团队知道规范会持续演进不会因为第一版没有幂等条款就质疑它不完整。我惯用的写法是每条条款后标「强制」还是「建议」新人一眼分清底线和锦上添花。3.3 评审与发布机制让规范从 draft 变成团队共识规范草稿写完后要走过评审不能写作者一个人拍板。评审建议开一次集中会议逐条过关键条款再留三天异步审阅时间收集书面意见。书面意见里至少要有「反对什么、替代方案是什么」的字段否则提意见就变成纯打嘴仗。发布时有三个动作缺一不可规范进团队文档库并存档带修订记录在周会上花十分钟把关键条款过一遍别默认大家都看过给前端、后端、测试各一份简版速查卡。很多人抱怨规范没人看真正原因往往是「发了」和「教会了」之间隔了十次同步。评审记录里被否掉的提案也值得留着它们能回答未来无数次「为什么不这样设计」的疑问。3.4 把规范绑进代码流程PR 自检、同步文档、契约测试规范真正开始生效是在代码评审里被引用的时候而不是文档共享出来的那刻。常见做法是在 PR 模板里加「接口变更自检清单」是否遵循 URL 命名、响应是否用了统一结构、错误码是否登记、是否更新了接口文档。每条打勾评审人照着核规范就嵌进了日常工作流。同步维护接口文档是最容易被忽视的一环。用 OpenAPI 描述接口后文档、Mock、测试可以直接从描述文件生成这是规范能活下来的必要条件之一。契约测试也要跟上前后端各按契约文件开发联调时以契约为准而不是以「后端实际返回为准」能省下大量无效沟通。这一套流程走下来规范才真正从纸面变成了开发习惯。4. 可以直接抄的条款与参数表分页、错误码、幂等与鉴权清单这一章给出的都是可以抄进自家规范的参数表和条款不需要再讨论为什么直接对照改改就能用。抄的时候注意把数值改成和团队实际容量匹配的值其余保持原样没有什么大问题。4.1 响应体统一结构code、message、data 之外还要有什么推荐一个通用响应结构codemessagedatatraceId。code 是应用层业务错误码message 是给开发者看的简短提示data 是业务载荷traceId 贯穿调用链。字段定义如下字段类型必填说明codeint是0 表示成功非 0 为业务错误码按段位分配messagestring是开发者可读的提示不直接展示给终端用户dataobject/null否业务数据失败时通常为 nulltraceIdstring是由入口服务生成用 UUID 或雪花 ID注意两个细节data 里不要塞「请求是否成功」这类和 code 重复的信息分页数据建议统一data.list和data.total不要再出现rows、records、pageData三种叫法。响应结构一致后前端封装请求拦截器和后端统一异常处理就有了共同基础这比任何规范的收益都直接。4.2 分页参数与默认值页码、游标和排序白名单的具体设置分页约定二选一页码分页适合后台管理、数据量可控的场景游标分页适合 App 信息流、数据量持续增长的场景。混用也不要紧但每个接口必须声明自己是哪种禁止同一个接口今天返回页码结构明天返回游标结构。页码分页参数名统一page和page_size默认page1、page_size20上限 100超过上限服务端按 100 截断而不是报错。游标分页参数名统一cursor和limitlimit默认 20、上限 100。响应里返回值has_more避免调用方靠「返回数是否等于请求数」猜还有没有下一页。排序字段必须白名单化。客户端传sortcreated_at、orderdesc服务端只接受白名单里的字段名避免直接拼接 SQL 造成注入风险。过滤条件统一走 query 参数枚举值用规范定义好的标识码数组参数用逗号分隔别让调用方猜拼接方式。4.3 幂等键、超时与重试写接口的防雪崩条款一笔订单被重复提交、一次支付通知被消费两次这类事故都是缺少幂等条款导致的。规范里约定所有写操作必须支持幂等键调用方在请求头带Idempotency-Key服务端同键自动去重键的保存时间建议 24 小时。新增用幂等键比用业务参数做唯一性校验要通用得多一套机制覆盖所有写接口。超时设置建议写入规范而不是留到联调才发现连接超时建议 5 秒读超时建议 10 秒可在网关侧按业务调整。重试用指数退避配合随机抖动退避起点 1 秒、最大 30 秒重试次数上限 3 次。没有抖动的重试在故障恢复时会变成「惊群」这一条在账单和消息场景里特别容易踩。4.4 鉴权与密钥的最小安全条款Token 放哪、多久过期、日志怎么脱敏鉴权条目越简单越容易执行Token 固定放Authorization: Bearer token头Access Token 有效期建议 24 小时Refresh Token 7 天过期后客户端静默刷新。Token 禁止出现在 URL 和日志里网关日志要注意把 Authorization 头自动打码。业务密钥方面对外回调解密的 AES Key 和签名私钥不能写入代码仓库走密钥管理系统下发并且要有轮换机制。日志脱敏要写明字段清单手机号保留前 3 后 4证件号和银行卡号全隐藏支付账号只留尾号。这些条款看起来琐碎但安全评审时是硬指标早写进规范比事后补审计强得多。4.5 一份可直接打勾的条款检查表评审时逐条过把上面的所有内容汇总成一张检查表评审接口时逐条打勾做到「有就是有、没有就是没有」检查项级别通过标准URL 遵循命名规范强制无驼峰/无动词/层级≤3响应体结构统一强制含 code/message/data/traceId错误码已登记强制段位正确且查得到释义分页参数合规建议默认值/上限/游标字段符合约定写操作支持幂等强制接收并校验 Idempotency-Key鉴权字段位置正确强制Token 在 Header 且不进日志敏感字段已脱敏强制按字段清单执行这张表可以做成 PR 模板的一部分也可以让测试在接口用例评审时直接引用。有了它规范能不能被执行就有了客观判据而不是靠评审人某个下午的心情。5. 接口规范落地避坑五个最容易翻车的真实场景规范写得再好落地时总有让人抓狂的时刻。这五条是我和不少团队交流后的高发坑按「现象、原因、解法」写清楚希望你们不用重新走一遍。5.1 规范发了没人看文件入不了开发流程等于白写现象规范文档躺在知识库里阅读量停留在发布那一周新接口照样用旧风格评审没人提这回事。原因规范从起草到发布都是一个人的事没有绑定任何流程节点开发者不看文档也不影响干活。解决把自检清单塞进 PR 模板评审人必须过一遍接口变更项同时借助 OpenAPI 生成文档让「写规范」变成写接口描述的一部分否则规范永远是离线文档。5.2 错误码越改越乱状态码和业务码语义互相污染现象有的接口失败返回200 code有的直接返回 500 加一段业务文案调用方为了兼容各种写法写了十几层判断。原因条款只写了「要有错误码」没写段位分配和登记流程业务方随手拍一个数字就上线。解决规范里明确状态码只管传输、错误码只管业务段位占用表由技术负责人维护新增错误码必须走变更评审。另外把错误码字典做成服务让调用方直接查省得每次都在群里问。5.3 分页参数三种写法并存给了选项就等于没给现象有些接口用page/pageSize有些用offset/limit游标分页字段名也各不相同。原因规范里写了「支持 offset/limit也可用游标」没有给默认实现每个接口作者都挑了自己顺手的写法。解决参数收敛到一个明确方案规范里必须写「无特殊情况一律page/page_size上限 100」不允许再出现第二套写法游标分页只在信息流接口用且字段固定为cursor/limit。存量接口清理要排期但新增接口必须零容忍。5.4 老接口下不了线版本条款没有配套生命周期现象v1 接口上线三年没人用但谁也不敢删最后还有调用方发来集成测试失败的单子。原因规范只讲了怎么加版本没讲怎么下线存量接口的生命周期管理完全缺失。解决为每个大版本设定维护窗口和下线日期下线前至少提前两个版本周期通知调用方通过Deprecation响应头标记警告。版本升级路径要写明从旧版本到新版本的映射关系和改造指引不然调用方拿到新版本号也不知道怎么迁。5.5 条款太多把团队压垮规范失去解释就是负担现象规范三百多条新接口开发要先查半天规范评审会变成「找茬会」团队开始私下吐槽。原因追求面面俱到把架构偏好、性能调优甚至编辑器配置都塞进了接口规范而且关键条款没写为什么。解决条款分「强制、建议、参考」三档建议和参考条目不允许出现在 PR 检查里每条强制条款写一句 rationale说明是为了避免什么事故。定期修剪规范半年一次删掉实际没拦住任何问题的条款规范越短越有人看。6. 进阶把规范变成可校验的规则集而不是一纸文件规范真正值钱的地方在于它能不能从「人读」变成「机器校」。最后聊聊怎么做以及怎么判断这个方向值不值得投入。6.1 用 OpenAPI 描述让规范能被机器读把所有接口统一用 OpenAPI 描述这是让规范长出牙齿的第一步。URL、参数、响应结构、鉴权方式全部写进描述文件文档、Mock、客户端代码都从它生成。团队里讨论接口先改描述文件再改代码规范就从后台文件变成了开发流程的输入。6.2 用 CI 拦截不合规接口把「自觉」交给自动检查有了 OpenAPI 描述文件就能在 CI 里挂一层接口 lint 检查。URL 是否符合命名、参数是否有默认值、响应是否包含必填字段这些规则都能被自动执行。再有大意的开发者最终拦在合并前的标准是一致的比评审人的记忆力可靠得多。6.3 用「拦截率」判断规范是否还活着判断规范有没有起作用的指标不是有多少人读过而是「接口不规范率」在下降新合并的接口中不合规数量占总量的比例以及错误码未登记的次数。我自己的习惯是每季度统计一次这两个数。低了说明流程在起作用不降反升就该回头检查是不是条款太复杂、检查点被绕过、或者团队根本不知道有规范。每年删掉没有拦截效果的条款留下的都是经过验证的规则。这大概是我做了这些年接口治理后最愿意分享的一条接口设计规范不是用来框死人的它是团队在联调血泪里提炼出来的后悔药写的时候多用点心思上线之后能少开无数场扯皮会。希望帮到你。本文还有配套的精品资源点击获取