“某小公司 RESTful、共用接口、前后端分离、接口约定的实践”光看这个标题我就有点感慨。十年前前后端分离还是个“大厂专属”的架构名词现在连三五个人、甚至两三个人的小团队都在搞。但小公司搞前后端分离跟大厂完全是两码事没有专职架构师没有完善的基建更没有充足的排期让你慢慢磨规范。我在这种体量的团队里做过几轮从零到一的接口体系搭建踩过的坑比写过的接口还多这里把整个过程摊开聊一聊。这套实践解决的核心问题其实很朴素怎么让一个后端、两三个前端、一个测试的小团队在不用花太多管理成本的前提下把接口定义清楚、把联调冲突降到最低、把返工率打下来。适合正在做前后端分离但总觉得“哪里不对劲、又说不上来”的中小型技术团队参考也适合刚接手一个半成品接口体系的同学作为自查清单。1. 项目背景与整体设计思路1.1 小公司做前后端分离的真实动机我见过不少小团队是被“大厂都这么干”推着走稀里糊涂就把前后端拆了。人还是那几个人流程还是那套流程只是把原本后端渲染的页面换成了前端框架的页面结果效率不但没提升反而因为联调成本暴增三天两头互相扯皮。真正适合小公司做前后端分离的动机其实只有三个业务确实需要多端复用同一套接口要撑起管理后台、用户端网页甚至未来的小程序前后端排期严重不对等前端要提前开发后端又不想用模板硬套后端不想再被页面交互细节绑架想专注业务逻辑本身如果不是这三个原因老老实实做服务端渲染反而更省事。我们当时就是第一个原因占了主导——老板一句话“后面可能要出小程序”才下决心把所有接口全部RESTful化。1.2 方案选型为什么没有直接上微服务小团队最容易犯的错是照搬大厂技术栈。我就见过5个人的后端团队硬上微服务光注册中心、配置中心、网关就折腾了两个月业务一行没写。我们当时的判断是业务体量根本撑不起微服务的复杂度与其拆服务不如把单体的接口边界划清楚。选型的核心权衡点在于单体应用 模块化分包后端一个工程按业务模块分包接口层统一收口RESTful风格不用RPC、不用GraphQL理由很简单——学习成本低、前端同学天然熟悉、调试工具链成熟共用接口以角色区分接口权限而不是按端拆接口减少重复逻辑这套组合对整个团队的技术栈要求不高后端会Spring Boot我们用的是这个其他语言类似框架同理前端会Vue或React就能跑起来。若依这类开源框架的思路也是这么干的但我们没有直接拿来用因为开源框架自带的权限模型和业务耦合度太高改起来比重写还累。1.3 接口约定的整体框架接口约定不是靠一份文档就完事的它需要形成一套能在日常开发中自然执行的规则。我们的设计分三层层次内容负责角色约定层命名规范、状态码、错误码、分页格式、时间格式后端主导全员确认技术层RESTful风格、共用接口模型、权限校验框架后端实现协作层接口文档、Mock数据、联调流程、变更通知全员参与这个框架看起来很普通但真正难的是让所有人都“认账”。我们用了最土的办法——每次接口评审全员到场白板上把接口一个个过确认没问题才写代码。宁可评审多花一小时也不要接口返工花一天。2. RESTful落到细节那些教科书上没写的取舍2.1 资源命名用名词但别被名词绑架RESTful的核心是用资源视角建模接口。比如用户、订单、商品对应/api/users、/api/orders、/api/products这个所有人都能接受。但一遇到“某个操作不是典型的增删改查”就容易扯皮比如“导出订单”、“批量审核”、“上下架”。我们最终定的规则是标准增删改查用HTTP方法表达GET查、POST增、PUT整体改、DELETE删复杂动作在资源下挂“动作子资源”POST /api/orders/export、POST /api/products/batch-audit不用/api/getOrderList这种把方法写进URL的路由为什么POST /api/orders/export比GET /api/orders/export?formatexcel更合适因为导出通常会带很多查询条件用GET容易超出URL长度限制而且导出行为本身有“创建一份文件”的语义用POST更贴切。这是一次实际踩坑换来的结论——我们最初用的是GET后来查询条件多到URL直接断了。2.2 状态码够用就好别搞几十个网上有很多RESTful状态码大全什么402 Payment Required、405 Method Not Allowed、413 Payload Too Large看得人头大。小团队不需要全套HTTP状态码定得太细大家根本记不住最后只会记住200和500。我们实际只用这些状态码使用场景200查询成功、操作成功201创建成功配合POST使用204删除成功一般不返回body400参数错误、校验失败401未登录或Token失效403已登录但无权限404资源不存在409业务冲突比如重复提交500未捕获的服务器异常注意一个细节业务失败不等于HTTP错误。比如“查了一个不存在的用户的订单列表”资源本身存在订单模块没问题只是查询结果为空这应该返回200加空数组而不是404。如果每个业务上的“没有数据”都映射成HTTP错误码前端要写一堆异常分支接口层也会越来越脏。2.3 路径设计版本、前缀、大小写的习惯RESTful风格下URL是前后端对接的第一印象。我们在路径上做了几个硬性规定全部小写单词间用连字符-连接不用下划线所有接口统一前缀/api第一段是版本号/api/v1即使当前只有一版也先把位置占住资源名一律用复数至于为什么用连字符不用下划线纯粹是为了浏览器和日志系统显示友好。下划线在某些前端框架的路由解析里会有转义问题连字符则完全没有这个烦恼。3. 共用接口设计一套接口如何撑起多个端3.1 共用而不是并行的接口模型很多团队做多端支持时的第一反应是给每个端单独建一套接口比如/admin/orders给管理后台/user/orders给用户端。这样做短期内很直观但长期看是灾难订单模块的逻辑稍微改一下你得同步改两套接口漏改一个就是线上事故。我们用的是共用接口模型也就是同一个资源接口通过不同的权限角色和参数裁剪来适配不同端。核心思路就一句话接口只认角色不认端。比如订单列表接口GET /api/v1/orders?status1pageNum1pageSize10管理端登录后能看到的订单范围是全部用户普通用户登录后同样的接口只能看到自己的订单区别不在URL而在后端根据当前登录用户的数据权限自动拼接查询条件。管理端和用户端看到的字段也不同这个通过返回值裁剪完成。3.2 数据权限共用接口最关键的一层共用接口最怕的是越权。我们把权限模型分成了三档接口权限决定能不能调这个接口粗粒度数据权限决定能看哪些数据细粒度字段权限决定能看哪些字段最细粒度实现上用比较轻的方式// 伪代码示意权限过滤思路 public PageResultOrderVO listOrder(OrderQuery query, LoginUser user) { // 接口权限判断 if (!permissionService.hasPermission(user, order:list)) { throw new ForbiddenException(); } // 数据权限拼接 if (!user.isAdmin()) { query.setUserId(user.getId()); } // 查询后字段裁剪 ListOrderVO data orderService.query(query); if (!user.isAdmin()) { data.forEach(order - order.setCustomerPhone(null)); } return new PageResult(data); }这是共用接口的精华所在。如果前端要把字段逻辑拆开就退化成“一套代码给每个端调不同方法”了。共用接口的底线是同一个资源的同一个操作后端只有一个入口所有端共享但不同角色看到的数据范围不同。3.3 字段裁剪避免把不需要的数据全部糊给前端共用接口必然带来一个问题管理端需要用户手机号用户端自己查自己不需要别人的手机号。我们的做法是定义VOView Object而不是直接把数据库实体类返回。public class OrderVO { private Long id; private String orderNo; private BigDecimal amount; private Integer status; // 管理端可见普通用户不可见 RoleVisible(roles {admin, operator}) private String customerPhone; }这里用了注解标记在序列化时根据当前用户角色动态决定字段是否输出。比起手写一堆if-else这种方案维护成本低很多新加字段时扫一眼注解就知道哪些角色可见。3.4 关于“共用”的两个反例也不是所有接口都适合共用。我们后来复盘发现有两类接口不适合硬凑文件上传接口因为各端的文件使用场景、大小限制都不同报表统计接口因为管理端的分析维度太多强行共用会让查询参数膨胀到十几个可读性和性能都很差遇到这两种情况单独建专用接口反而是更务实的方案。共用接口的目标是减少重复逻辑不是把不相关的场景硬绑在一块。4. 接口约定五个必须提前定死的规范4.1 统一响应体一个壳子包住所有返回前后端分离之后前端同学最怕的就是“这个接口返回的是一个数组那个接口返回的是一个对象还有个接口出错时返回的是字符串”。响应体不统一前期省事后期想死。我们的统一响应体结构非常简单{ code: 0, message: success, data: {} }code为业务错误码0表示成功非0表示具体错误message给前端展示用后端不要把内部异常堆栈往这里塞data是业务数据的载体可以是对象、数组、分页结构等这里有个细节业务错误码和HTTP状态码是两套维度。HTTP状态码只表示“请求链路是否正常”业务错误码表示“业务逻辑是否成功”。比如库存不足HTTP还是200业务码是10086这样前端可以根据业务码做提示而不是HTTP层就报错导致无法区分参数问题和业务问题。4.2 分页约定参数名统一返回结构固定分页是前后端最容易吵架的地方。前端传page后端返totalPage前端传offset后端返count——光分页这一件事就能让联调耗掉半天。我们定的分页约定入参固定pageNum和pageSizepageSize上限100防止有人一次拉全表返回固定结构list当前页数据、total总条数、pageNum、pageSize{ code: 0, message: success, data: { list: [], total: 156, pageNum: 1, pageSize: 10 } }分页排序也听坑我们规定排序字段不能由前端直接传数据库列名因为会有人传orderByid;drop table这种字符串。要么后端白名单校验要么前端只能传固定的枚举值比如createTime对应create_time由后端映射。4.3 时间格式所有时间都是字符串职位上有一个很经典的问题后端返回Date对象Jackson默认序列化成2025-01-15T10:20:30.00000:00这种带时区格式前端直接显示给人看就是乱码。我们还踩过时间戳、字符串、对象三种格式并存的坑前端同事一度崩溃。规定是死的简单明了请求参数中的时间用yyyy-MM-dd HH:mm:ss字符串响应中的时间统一用yyyy-MM-dd HH:mm:ss字符串存库用datetime类型代码里用LocalDateTime这样前端不用解析任何复杂格式后端写个全局的Jackson配置就能搞定所有接口保持一致。4.4 命名和语义别让前端猜你的意思接口字段命名不统一会显著拉高联调成本。比如一个表示状态的字段有人叫status有人叫state还有人叫isActive。这种问题在接口评审时很难发现要到前端写逻辑时才发现同一含义的字段换了三个名。我们规定字段尽量用语义明确的名词比如orderStatus、amount、createdAt布尔类型用is前缀如isDeleted不要混用deleteFlag、deleted、flag列表/分页返回的字段名不要用data这种泛化的词统一用list避免和前端的Axios拦截器里response.data混淆命名这块不涉及技术难度纯粹靠自觉和评审。我后来总结出一个土办法让前端把接到的JSON结构打印出来当作代码注释一样贴在接口文档里后端看一眼就知道自己哪里命名得不合群。4.5 安全约定认证、鉴权、防刷安全约定不在最初的需求里是后来被逼出来的。上了共用接口之后多端复用同一个入口防刷和鉴权就显得尤其重要。认证统一用Token机制前端在请求头带Authorization: Bearer token写操作POST、PUT、DELETE要求做幂等校验用的Idempotent-Token请求头后端用Redis判断是否已处理过对于不需要登录的接口单独配置白名单比如登录接口本身、验证码接口敏感操作记录操作日志包含用户、时间、参数和结果5. 实操过程从接口定义到上线联调的全流程5.1 第一步接口定义先行我们吃过最大的亏就是“边写边定接口”。后端写着自己的想象前端画着自己的页面一到联调发现两边理解的参数类型都对不上。后来强制规定写代码前必须先出接口文档接口评审通过后才允许进入开发。这一步相当于把最终验收标准提前了。我们用的工具是Apifox之前是Postman但国内团队用其团队协作和Mock功能确实香后端在Apifox里定义好接口包括请求路径、方法、请求参数、类型、是否必填、示例值响应体完整结构、字段说明错误码说明角色分工明确后端负责定义接口前端必须在后端确定的接口上进行开发接口有变动必须通知所有受影响的前端并在评审记录里留下变更说明。5.2 第二步Mock先行前后端并行开发接口定义好后最怕的就是前端等后端的开发进度导致项目延期。我们的做法是让Apifox自动生成Mock数据前端在页面开发时直接调Mock服务。Mock不是随便返回几个假数据就完事我们总结了几个技巧Mock数据必须符合接口约定字段类型和长度跟真接口保持一致列表类接口Mock数据量至少造200条让前端能测分页、空态、加载态Mock数据中要特意包含边界情况比如金额为0、状态为异常值、字符串超长等情况前端用Mock数据把页面逻辑写完后端同步按定义开发等两边完了再切换到真实环境联调。这样原本需要串行等待10天的开发周期直接压缩到一周内因为前后端的并行度提上来了。5.3 第三步联调环境的规范切换联调不是把前后端环境拼起来就算完还得考虑环境切换时的配置管理。我们当时的做法是前端本地开发用Vite的代理转发代理目标是后端的dev环境联调阶段统一使用test环境后端部署好全新的测试包前端切代理到test部署工具用的Jenkins后端的dev和test环境用不同目录隔离避免共用一个库一个Redis因为测试数据会污染开发数据这个环节最容易出的问题就是环境串了——前端本地连的数据库和后端本地连的数据库不是一个库查出来的数据对不上排查半天发现是环境变量配错了。5.4 第四步自动化测试守住接口稳定性小公司通常没有专门的测试团队接口质量全靠代码Review和人工点测。我们后来引入了一个很轻量的自动化测试方案在Apifox里写接口测试用例每次后端发版前跑一遍回归。写这些用例的成本不高但收益很大接口路径改了用例挂了能第一时间发现响应字段删了用例的断言失败能提醒后端回归检查状态码或业务码异常用例直接报错配合Jenkins可以做到“后端构建成功后自动触发接口测试测试通过才允许合并发布”。虽然比不上大厂的完整CI/CD流水线但对小团队来说已经能挡住大部分低级回归问题了。5.5 第五步发布后的监控与反馈上线不是终点。我们保留了接口层日志记录每个接口的耗时、状态码和异常信息配套做一个简单的定时任务聚合统计。不用上什么重量级的监控平台因为小团队没人力天天看监控大屏反而是在日志里加几个字段出了问题时能快速定位是前端传参问题还是后端业务异常就够用了。6. 常见问题与排查技巧实录6.1 必填参数校验缺失联调期最多的问题就是必填参数忘了传。后端有时候为了赶进度只写了查询逻辑没加参数校验结果前端传了个null进去数据库查询直接异常。我们的排查技巧很简单后端在所有接口入口统一做参数校验用上Bean Validationpublic class OrderQuery { NotNull(message 用户ID不能为空) private Long userId; Min(value 1, message pageNum最小为1) private Integer pageNum 1; Max(value 100, message pageSize最大为100) private Integer pageSize 10; }任何接口在进入业务逻辑前先过校验层不合格直接返回400加具体错误信息。定这个规范花了半天但省下了无尽的“帮我看看为什么接口报错”的时间。6.2 跨域问题一次搞定别反复配前后端分离绕不开跨域。我们用Spring Boot后端配置CORSConfiguration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOriginPatterns(http://localhost:*, https://*.example.com) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }这里有个经验allowCredentials(true)时前端不能再用*作为allowedOrigins必须明确指定域名否则请求被浏览器拦截。我们还真在这卡过半天最后查阅文档才明白原因。6.3 前后端“接口漂移”问题所谓接口漂移就是后端改了接口但忘了通知前端前端还在按旧文档调。这在多人协作时很常见尤其是后端一个人改了接口名前端不知道。我们后来做了两个约束接口变更必须走钉钉群通知文案需要包含变更点、影响范围、预计改动时间后端修改接口前先确认是否有前端正在依赖这个接口。如果有必须等前端完成改造或至少知道改造时间节点才能切走这套约束听着像管理流程但实际落地成本很低关键是养成习惯。在群里喊一句“下单接口返回值里我加了couponId字段”比事后线上出bug再排查爽多了。6.4 重复提交的坑共用接口上线后我们遇到了一个前端点两次提交按钮导致重复下单的问题。前端做了按钮loading防重复但网络慢的时候请求没有立刻返回按钮没锁住用户又点了一次结果后端收到了两个一模一样的下单请求。解决方式就是前面提到的幂等Token前端在进入下单页时先请求一个idempotentToken存到前端变量提交订单时把Token放进请求头里后端拿Token查Redis如果存在说明已处理过直接返回第一次的结果不再执行下单逻辑如果不存在存Token并执行下单逻辑用了这个方案之后重复下单的问题彻底解决。虽然一个Token机制代码量不多但对下单这类写操作来说是刚需。6.5 问题排查速查表把常见问题整理成一张表联调遇到问题先照表排查能省不少沟通时间现象可能原因排查步骤接口返回401Token失效、过期或未携带检查请求头是否带AuthorizationToken是否过期接口返回403权限不足检查角色配置是否用了错误的账号调接口返回400但消息不明确参数校验没通过查看是哪个参数不合格前端检查传值返回500后端异常让后端看日志重点看NPE或SQL异常返回空数组但应该有数据数据权限过滤掉检查登录用户是否有数据权限返回结果里有null字段裁剪配置错误检查VO注解配置或数据库字段为空前端乱码时间格式不对确认后端全局Jackson配置是否生效接口跨域报错CORS配置不对检查域名白名单确认是否带credentials6.6 一些不那么技术、但更值得提醒的坑技术之外我感觉这套实践中最大的难点是“人心”。共用接口意味着大家不能再各写各的、各自为战。前端和后端必须愿意在日常开发中频繁对齐后端要主动理解前端的消费场景前端要接受后端统一的响应结构而不是“你按我的习惯返一个自定义格式”。我们团队保持了一个习惯每周五下午花一小时做接口Review不是看代码而是把本周新增的接口在浏览器控制台或者Apifox里拉出真实调用记录挨个检查路径、参数、返回体、权限设置。这个习惯坚持了半年发现的潜在问题少说十来个包括一个管理端越权的严重漏洞。别觉得Weekly Review浪费时间比起线上出事故再补救这笔时间投入非常值。6.7 基于经验的实操心得说实话在小公司做前后端分离这套东西真正难的不是技术选型不是RESTful规范也不是共用接口模型而是如何让一套规则在没有强管理手段的前提下被执行到底。我的体会有几个规范一定是从需求里长出来的不是拍脑袋想出来的。不用一步到位搞一个几十页的接口规范文档先定五六个最关键的点跑一个迭代再补。一次定太多大家记不住最后什么都不执行工具比人靠谱。接口文档只要是人记就一定会漂移尽量用Apifox这种定义即文档、文档即Mock的工具后端定义接口、前端用Mock天然同步接口评审要从一开始就坚持。哪怕需求紧也要拉5分钟过一遍路径、参数、返回结构。省下评审的5分钟联调阶段会多花50分钟来填坑共用接口的“共用”是有限度的。硬把所有场景塞进同一个接口最后谁都不爽。边界不清的时候该拆就拆独立接口没那么可耻与业务方确定“先定接口再写代码”的规则后前端后端的协作质量立竿见影。这是整个实践里性价比最高的一步如果让我重新做一次这个小公司前后端分离的改造我还是会选择这套方案一个后端工程以RESTful风格提供共用接口用统一约定把响应体、错误码、分页、时间格式全部锁死通过主动评审和工具链保证接口的生命力。它不炫技但足够扎实足够让一个三五人的技术团队省出时间来做真正有价值的事情——把业务做对把用户体验做好。