接口联调总是炸？这3个规范90%的团队没做到

上周三晚上11点，我收到一条消息：接口又又又又炸了。

同事在群里崩溃地发了一连串截图，前端说后端返回的字段对不上，后端说前端传的参数缺了关键信息。两边都在加班，都在改代码，可问题就是解决不了。这种场景，干过开发的都懂，太痛了。

说白了，接口设计不是技术问题，是沟通问题。一个团队几十号人，前端用Vue，后端用Java，测试用Postman，每个人对接口的理解都不一样，联调成本自然高得吓人。有数据说，好的接口设计能让联调时间减少60%以上，真不是吹牛。

咱们今天不聊虚的，直接说干货。从多个团队踩过的坑里，我整理了三套落地就能用的规范，帮你把接口从“能跑”变成“好用”。

第一，资源命名别用动词，用名词。

很多新手最容易犯的错，就是把接口写成RPC风格。比如`/getUser`、`/deleteOrder`，一看就知道是操作，但系统一复杂，接口数量爆炸，管理起来就乱套了。

正确的做法是RESTful风格，用URL表示资源，用HTTP方法表示操作。比如获取用户信息，就是`GET /users/{userId}`，创建用户就是`POST /users`，更新是全量更新用`PUT`，部分更新用`PATCH`，删除就是`DELETE /users/{userId}`。

这样设计的好处是，接口的语义是自描述的。前端拿到URL，就知道代表什么资源，看到HTTP方法，就知道要做什么操作。不用再翻文档，联调效率直接翻倍。

有一家公司，他们的订单接口本来叫`/order/create`，后来改成`POST /orders`，团队磨合一周后，联调时间从两天缩短到半天。效果立竿见影。

第二，响应结构要统一，别让前端猜。

我现在最怕看到的就是，每个接口返回的字段结构都不一样。有的接口返回`{code: 0, data: {}}`，有的返回`{success: true, result: {}}`，前端拿到数据，还得先判断是什么格式，写一堆兼容代码。

更离谱的是，有些接口字段直接不写，比如用户权限如果是`null`，前端判断时就得写`if (user.role === null || user.role === undefined)`，隐患很大。

说白了，统一响应结构是基本功。我建议团队用这个模板：`{"code": "SUCCESS", "message": "操作成功", "data": {...}}`。code用语义化字符串，比如`PARAMETER.ILLEGAL`，比纯数字好理解。分页请求时，返回`list`和`total`，前端直接判断是否还有更多数据。

还有个细节，空值按类型返回默认值，整型返回0，字符串返回空串，对象返回null，别返回不存在的字段。这样前端处理逻辑就简单了，写代码也舒服。

第三，安全机制别等上线再补，要前置。

很多团队做接口，先跑通功能再说，安全机制后面加。结果上线后，被人刷接口，或者数据被篡改，才想起来补。这就像房子盖好了再装防盗门，成本高还效果差。

正确的做法是，从设计阶段就把安全机制写进去。比如认证用JWT，包含用户身份和权限，设置两小时过期。防篡改用签名机制，把所有参数按升序排序，拼接`app_key`、`timestamp`、`request_id`，然后算MD5或SHA256。服务端收到后，重新算一遍，对得上就是没被篡改。

防重放用请求ID，客户端生成全局唯一ID，服务端根据ID去重。比如支付场景，用户点了两次提交，请求ID一样，服务端直接返回已处理结果，就不会重复扣款。这个机制，能救很多命。

说到这，你可能觉得这不就是设计规范吗？但你真去调接口的时候，痛苦远不止这些。比如幂等性，非幂等操作必须用请求ID保证，否则重复提交导致数据错误，只能回滚。还有接口文档，千万别手写，用OpenAPI（Swagger）自动生成，在线测试，减少人工失误。

从个人的成长来看，懂点设计规范，是向高级工程师迈进的必经之路。你写的接口，不只是给机器看的，更是给团队看的。好的接口，让人舒服；差的接口，让人崩溃。

最后，我想说，规范是工具，不是教条。在特定场景下，比如内部微服务，RPC可能比RESTful更高效。但不管用什么方式，核心是让团队协作顺畅，让系统稳定运行。

你们团队接口联调踩过最大的坑是什么？评论区聊聊呗。