接口规范这件事几乎每个前后端分离的团队都会经历一轮从随便写到痛定思痛的过程。我见过太多项目前端拿到一个字段叫userName另一个接口又叫username还有一个叫user_name同一个用户对象在三个接口里长得像三个不同的人。也见过后端把null、空字符串、字段缺失三种情况混着用前端判断逻辑写了一屏还没写完。这篇内容就是把这些年踩过的坑、谈过的约定、最后沉淀下来的那套接地气的接口规范完整讲一遍——不追求教科书式的完备只讲真正能落地、团队愿意遵守、新人来了能快速上手的那部分。适合正在做前后端分离项目的前端、后端、全栈也适合技术负责人拿去当团队内部约定的底稿。1. 为什么接口规范总是定了等于没定1.1 规范失效的真实原因不是没人写而是没人用大部分团队其实都写过接口文档甚至开过专门的评审会。问题在于规范写完之后就躺在某个文档库里吃灰没人把它变成开发流程里绕不过去的一环。我复盘过几个规范推行失败的案例根因基本集中在三个地方第一规范太重一个接口要求填十几个字段后端嫌麻烦直接跳过第二规范没有和代码绑定文档和实际返回永远对不上前端慢慢就不信文档了第三规范只约束了格式没约束语义字段名统一了但status到底 0 是成功还是 1 是成功每个模块各说各话。真正能落地的规范一定是轻量、可校验、和代码同源的。轻量意味着后端写起来不费劲可校验意味着 CI 能自动拦截不合规的返回同源意味着文档从代码注解里生成而不是手写。这三条缺一条规范就会退化成墙上的标语。1.2 前后端分离后接口就是合同单体应用时代前后端代码在一个工程里字段对不上编译器直接报错。分离之后接口变成了两个团队之间唯一的契约而这个契约偏偏是弱类型的——JSON 里多一个字段少一个字段编译期毫无感知只有运行时才炸。所以接口规范的本质是把编译期能发现的问题尽量前移到设计期和联调期。我常跟团队里新人打的一个比方接口就像餐厅的点菜单。前端是服务员后端是后厨菜单上写微辣后厨就得知道微辣是几勺辣椒。如果菜单上只写辣那每次做出来味道都不一样顾客投诉了服务员还得背锅。接口规范就是那张把微辣2勺写清楚的菜单。1.3 一套规范要覆盖的四个层面很多人以为接口规范就是返回体长什么样其实远不止。一套完整的规范至少要覆盖四个层面缺一个都会在某个阶段出问题层面管什么不管会怎样传输层请求方法、状态码、Content-Type前端不知道 200 里包着的是成功还是业务失败结构层统一返回体的字段与嵌套每个接口解析逻辑都不一样无法封装语义层错误码、分页、时间、空值约定字段名对了但含义对不上联调照样吵命名层字段命名风格、大小写、复数同一个概念三种写法前端映射表越写越长下面几章就按这四个层面逐一拆开讲每一层都给到可以直接抄的约定和背后的取舍理由。2. 统一返回体一个信封解决 80% 的解析混乱2.1 为什么必须有一个信封先说结论所有接口无论成功失败都返回同一个外层结构。这是整套规范里性价比最高的一条没有之一。原因很直接——前端可以写一个统一的响应拦截器在这个拦截器里完成判断业务是否成功、提取数据、统一弹错误提示三件事业务代码里就再也不用关心外层结构了。如果没有统一信封你会遇到这种代码A 接口成功返回{data: {...}}B 接口成功直接返回数组[...]C 接口失败返回{error: xxx}。前端每调一个接口都要单独判断返回类型封装无从谈起新人接手先花两天读各种奇葩返回。我推荐的信封结构长这样字段不多但够用{ code: 0, message: ok, data: {}, traceId: a1b2c3d4e5f6 }四个字段各有分工code是业务状态码message是给人看的提示data是真正的业务数据traceId是链路追踪标识。这里有个关键取舍——HTTP 状态码和业务 code 要分开。HTTP 状态码表达这次请求在传输层面是否成功200 表示服务器收到了并处理了业务 code 表达这次业务操作是否成功比如余额不足、参数校验失败。两者混用是重灾区很多团队用 HTTP 400 表示参数错误、用 200 表示业务失败结果网关、监控、重试机制全部失灵。2.2 code 的取值约定0 还是 200这是团队里吵得最多的问题之一。我的建议是业务 code 用 0 表示成功非 0 表示各类失败并且约定一套分段规则。为什么不用 200因为 200 是 HTTP 的语义业务层再复用容易让人混淆这到底是 HTTP 200 还是业务 200。用 0 表示成功是很多成熟框架的惯例语义干净。分段规则建议这样定让错误码本身携带信息区间含义示例0成功01xxx通用错误参数、鉴权、限流1001 参数校验失败2xxx用户与权限相关2001 登录态失效3xxx业务领域 A 的错误3001 库存不足4xxx业务领域 B 的错误4001 订单状态不允许操作5xxx系统级错误DB、下游超时5001 服务暂时不可用这样前端拿到code就能大致判断该走哪种处理1xxx 提示用户改输入2xxx 跳登录5xxx 提示稍后重试并上报监控。比一堆散落的魔法数字强太多。2.3 data 的三种形态要提前说清楚data字段在不同场景下形态不同必须提前约定否则前端封装会很难受。常见三种对象详情类接口data是一个对象查不到时返回null而不是空对象{}。为什么因为null明确表达没有这条数据而{}会让前端误以为有数据但字段都是空的判断逻辑完全不同。数组列表类接口data直接是数组空列表返回[]而不是null。前端map、length都能直接用不用先判空。分页对象分页接口data是一个包含list、total、page、pageSize的对象见第 4 章。注意data为null和字段缺失是两回事。约定查不到返回 null就不要出现有时候返回 null 有时候干脆不返回这个字段的情况前端没法写。2.4 一个容易忽略的细节message 给谁看message到底是给终端用户看的还是给开发看的这个不约定清楚会出现后端返回一串英文堆栈前端直接弹给用户的尴尬。我的做法是message只作为开发调试和兜底提示面向用户的文案由前端根据code自己维护。原因很简单后端返回的文案没法做国际化也没法适配不同端的语气而且一旦后端改文案前端展示就跟着变不可控。所以约定是后端message写清楚发生了什么比如库存不足当前可售 3 件前端根据code决定展示什么文案message只在没有对应文案时兜底展示。这样既保留了调试信息又保证了用户体验的一致性。3. 命名与字段语义让前端不用写映射表3.1 命名风格只能选一种然后贯彻到底字段命名是接口规范里最琐碎但最容易引发摩擦的部分。userName、user_name、UserName、username四种写法在同一个项目里共存前端就得维护一张映射表改一个字段要全局搜。解决办法只有一个团队内强制统一一种风格。我的建议是 JSON 字段统一用小驼峰camelCase理由是前端 JavaScript/TypeScript 天然用小驼峰后端序列化时做一次转换即可主流框架都支持配置命名策略。数据库列名用下划线没关系那是存储层的事出口统一转成小驼峰。这条约定写进规范后序列化配置一次全项目生效几乎零成本。场景推荐风格说明JSON 字段camelCase前端零转换URL 路径kebab-case如/user-profiles查询参数camelCase与 JSON 保持一致数据库列snake_case存储层自由出口转换3.2 布尔字段的命名陷阱布尔字段是最容易出歧义的地方。isDelete、deleted、enable、status混用前端根本猜不出true到底代表已删除还是可删除。约定两条第一布尔字段统一用is/has/can前缀如isDeleted、hasPermission、canEdit第二禁止用布尔字段表达三态以上比如审核状态有待审/通过/驳回三种就不能用isApproved布尔值必须用枚举auditStatus。我踩过一个坑某接口用isValid表示数据是否有效结果业务上还有待验证这个中间态后端硬塞进布尔值前端只能靠另一个字段组合判断逻辑越写越乱。后来改成枚举validStatus: 0/1/2才清爽。能枚举就别用布尔这是血泪教训。3.3 时间、金额、ID 的表示约定这三类字段几乎每个接口都有但表示方式五花八门必须统一时间统一用ISO 8601 字符串带时区如2024-05-20T13:14:1508:00或者统一用毫秒时间戳数字。二选一全项目一致。我倾向 ISO 字符串可读性好日志里一眼能看懂但如果前端要做大量时间计算时间戳更省事。关键是别一半接口给字符串一半给时间戳。金额永远用最小货币单位的整数比如分。19.99元存成1999。浮点数做金额是经典事故源0.1 0.2 ! 0.3的问题在财务场景会要命。字段名建议带单位如amountInCents或amount并在文档注明单位是分。ID统一用字符串传输哪怕后端是long类型。原因是 JavaScript 的Number精度只有 53 位雪花算法生成的 19 位 ID 传到前端会丢精度变成1234567890123456800这种鬼样子。这个坑我见过至少三个项目踩排查起来极其痛苦。后端序列化时把long转string前端当字符串处理皆大欢喜。3.4 空值与字段缺失的语义区分JSON 里null、空字符串、空数组[]、字段不存在四种情况语义完全不同但很多后端随手返回前端只能全当空处理。约定如下情况语义前端处理字段为null该字段有这个概念但值为空显示占位符字段缺失该场景下不涉及此字段不渲染相关 UI字符串类型的空值同 null 处理[]集合为空显示空状态实操中我建议尽量少用字段缺失因为前端判断field in obj很别扭。更稳妥的做法是所有字段都返回空值用null前端统一判null即可。代价是返回体略大但换来的是可预测性值。4. 分页、排序、筛选列表接口的三件套4.1 分页参数与返回结构必须成对约定列表接口是最高频的接口类型分页规范不统一前端每个列表页都要重写一遍逻辑。约定请求参数用page从 1 开始和pageSize返回结构固定为{ code: 0, message: ok, data: { list: [], total: 128, page: 1, pageSize: 20 } }这里有两个细节值得说。第一page从 1 开始还是从 0 开始我建议从 1 开始因为面向用户展示的页码就是 1、2、3从 0 开始每次都要 1 -1容易出错。第二total是总条数还是总页数约定为总条数因为前端分页组件通常需要总条数自己算页数而且总条数信息量更大。注意pageSize一定要有服务端上限比如最大 100。否则前端传个pageSize100000数据库直接被打挂。这个上限在网关或参数校验层拦截返回明确的错误码。4.2 排序参数的防注入设计排序字段如果直接拼进 SQL是注入重灾区。约定排序参数为sortBy字段名和sortOrderasc/desc并且服务端必须维护一个白名单只允许对白名单内的字段排序。前端传了白名单外的字段直接忽略或返回参数错误绝不能透传到 SQL。// 伪代码示意白名单校验 SetString allowedSortFields Set.of(createTime, updateTime, amount); if (!allowedSortFields.contains(sortBy)) { throw new BizException(ErrorCode.INVALID_PARAM, 不支持的排序字段); }这个白名单机制看起来麻烦但它是把用户可控输入和SQL 结构隔离开的关键。我见过有项目直接ORDER BY ${sortBy}结果被人用排序参数做盲注教训深刻。4.3 筛选条件的表达简单用 query复杂用 body简单筛选一两个等值条件用 query 参数没问题比如?status1keywordabc。但复杂筛选多条件组合、范围查询、数组包含塞进 query 会又长又难读还容易超长。约定复杂筛选走 POST body哪怕它是查询操作。RESTful 纯粹主义者可能不接受但工程上这是务实的选择——GET 的 URL 长度限制、编码问题、日志可读性都是现实约束。复杂筛选的 body 结构建议统一{ filters: { status: [1, 2], createTimeStart: 2024-01-01T00:00:0008:00, createTimeEnd: 2024-12-31T23:59:5908:00, keyword: abc }, page: 1, pageSize: 20, sortBy: createTime, sortOrder: desc }把筛选、分页、排序放在同一层前端封装一个通用的列表请求方法就能覆盖所有列表页这是统一规范带来的复利。5. 错误处理与状态码把出错了讲清楚5.1 HTTP 状态码只用在它该用的地方前面提过 HTTP 状态码和业务 code 要分开这里展开说清楚各自管什么。HTTP 状态码表达传输层结果200 请求成功、401 未认证、403 无权限、404 资源不存在、429 限流、500 服务端异常。业务 code 表达业务结果。两者配合的关系是场景HTTP 状态码业务 code正常成功2000参数校验失败2001001未登录4012001无权限4032002业务规则不满足2003xxx服务端异常5005001关键点业务失败如库存不足HTTP 状态码仍然是 200因为请求本身被正确处理了只是业务结果不成功。这样网关、监控、重试机制看到 200 就不会误判为故障而前端通过业务 code 判断具体结果。401/403 这类认证授权问题才用非 200因为它们确实属于传输/访问层面的失败。5.2 错误响应也要带 traceId线上排查问题时用户截图一个操作失败你根本不知道是哪次请求。所以所有响应包括错误响应都要带traceId前端在错误提示里可以展示一个短码用户报障时提供这个码后端一搜日志就能定位。这个机制成本极低收益极高。实现上网关或过滤器生成traceId放进 MDC日志上下文响应时写回响应体同时日志里每条都带这个 ID。前端拦截器拿到后可以存起来出错时上报。这套链路打通后排查效率提升是数量级的。5.3 前端拦截器的统一处理逻辑规范最终要落到前端的统一拦截器上这里给一个处理逻辑的骨架以常见请求库为例伪代码// 响应拦截器伪代码 function onResponse(response) { const { code, message, data, traceId } response.data; if (code 0) { return data; // 业务成功直接返回 data业务代码无感 } if (code 2000 code 3000) { // 登录态问题跳登录 redirectToLogin(); return Promise.reject({ code, message, traceId }); } // 其他业务错误统一提示 showToast(getMessageByCode(code) || message); return Promise.reject({ code, message, traceId }); }注意这里code 0时直接返回data业务代码里const user await getUser()拿到的就是用户对象不用再.data.data。这个封装是统一返回体带来的最大红利业务代码干净得不像话。6. 版本管理与文档同步规范的生命周期6.1 接口版本号放在哪里接口要演进老版本不能随便删可能还有旧客户端在用所以需要版本管理。常见做法有两种URL 路径带版本/api/v1/users或者请求头带版本Accept-Version: v1。我推荐URL 路径带版本理由是可读性好、调试方便、网关路由好配、日志里一眼能看出调的哪个版本。请求头方案更优雅但排查时经常忘了看头反而添乱。版本升级的原则是新增字段不算破坏性变更不用升版本删除字段、改字段语义、改字段类型才算破坏性变更必须升版本。很多团队一加字段就升版本结果版本号飞涨维护成本爆炸。把这条原则写进规范能省很多事。6.2 文档从代码生成而不是手写手写文档必然和代码脱节这是铁律。解决办法是让文档从代码注解生成主流语言都有成熟方案比如 Java 生态的注解式文档、Node 生态的 schema 注释、Go 生态的注释生成。核心思路是接口定义即文档改代码必须改注解CI 里校验注解完整性文档自动发布。更进一步可以让前端根据文档自动生成 TypeScript 类型定义这样字段改名时前端编译期就能发现把运行时错误前移到编译期。这一步做了之后后端偷偷改字段前端不知道的事故基本绝迹。6.3 用契约测试兜底文档再全也可能和实际返回不一致。契约测试Contract Test就是解决这个的前端定义期望的响应结构CI 里跑一遍真实接口结构对不上就失败。工具层面有很多选择核心是把接口契约变成可执行的断言而不是一段描述文字。实操中不必一上来就全量契约测试可以先从核心接口登录、下单、支付这类开始跑通流程后再逐步覆盖。我一般建议新项目从第一天就把契约测试框架搭起来老项目挑最痛的几个接口补投入产出比最高。7. 落地这套规范时踩过的坑7.1 规范文档太长没人看做成 checklist 才有用第一版规范我写了三十多页结果没人看完。后来改成一张接口自检清单十几条每条一句话贴在 PR 模板里提交前逐条打勾。效果立竿见影。清单大概长这样返回体是否用了统一信封code/message/data/traceId业务 code 是否按分段规则取值布尔字段是否用了 is/has/can 前缀金额是否用了最小单位整数ID 是否用了字符串列表接口是否返回了 list/total/page/pageSize排序字段是否走了白名单校验错误响应是否带了 traceId清单比长文档有效因为它嵌进了工作流绕不过去。7.2 老接口改造要新老划断别一刀切老项目推行规范最忌讳一刀切要求所有接口立刻改造。正确做法是新老划断新接口必须合规老接口在下次改动时顺带改造同时前端拦截器做兼容层能同时处理新旧两种返回。兼容层会丑一点但能保证业务不停摆。等老接口逐步下线兼容层再删掉。我见过团队强行要求一周内全量改造结果改出十几个线上 bug规范反而被抵制。渐进式推进用新接口的清爽体验去诱惑大家比强制命令有效得多。7.3 规范要有 owner否则会腐烂规范不是写完就完事它会随着业务演进出现新问题比如新增了文件上传、流式响应、批量操作需要有人维护和裁决。建议指定一个接口规范的 owner通常是后端负责人或架构角色负责评审新场景的约定、更新文档、解答争议。没有 owner 的规范半年后就会变成历史文档大家各写各的。owner 的职责不是管人而是定标准、解争议、做示范。遇到规范没覆盖的场景owner 拍板定一个约定写进文档下次大家照着来。这个机制让规范保持活着。7.4 一个真实的对齐案例某次跨团队协作A 团队的分页返回是{list, total}B 团队是{records, count, current, size}联调时前端写了两套解析。后来双方坐下来对齐统一成{list, total, page, pageSize}前端删掉一套解析代码bug 少了一半。这件事说明规范的价值在跨团队协作时会被放大单团队内部可能靠默契能撑一旦跨团队没有明文约定就是灾难。对齐的过程也不复杂就是把双方字段列出来逐字段讨论语义能合并的合并不能合并的保留并注明。关键是有人牵头、有结论、写进文档。半天时间换来后续几个月的顺畅非常划算。8. 写在最后的一点个人体会这套规范我在几个项目里推行过最大的感受是规范的价值不在于它多完备而在于它被真正执行。一份只有十条但人人遵守的规范远胜一份一百条但没人看的规范。所以每次推行我都会先问团队哪几条是你们最痛的从最痛的点切入先解决一两个具体问题让大家尝到甜头再逐步扩展。另外规范要允许例外。总有些特殊接口比如第三方回调、文件流下载不完全适用统一信封这时候明确标注例外并说明原因比强行套用导致别扭要好。规范的目的是降低沟通成本不是制造新的教条。把这条想明白推行起来会顺很多。