前后端分离时代，接口规范为何如此重要？

最新推荐文章于 2024-07-24 23:00:08 发布

源码时代网

最新推荐文章于 2024-07-24 23:00:08 发布

阅读量1.4k

点赞数 16

文章标签：接口前端字段

本文链接：https://blog.csdn.net/qq785557022/article/details/139512802

版权

随着前后端分离越来越普遍，后端接口规范变得越来越重要，一套好的接口规范可以提高工作效率，减少沟通障碍。

通常我们使用REST来提供接口，使用JSON来传输数据。

名词含义

前端

Web前端、APP端、桌面端等都属于这一层用户界面

后端

服务器端指的是用户界面以下的一切。

前端和后端接口

前后端数据交互的总称，也叫数据接口，是一种远程调用，一般指前端通过HTTP（ajax）请求获取数据或者执行某个操作。为了保证前后端（工程师）的协同沟通，前后端通常会共同定义接口规范，规范的内容一般包括接口的地址、接口的输入参数以及输出的数据格式（结构）。最终由后端实现这些规范，为前端提供符合规范的接口。

 [前端] 
--------
   ^
   |
   |
前后端接口
   |
   |
--------
 [后端]

前后端接口协作流程

开发之前首先要定义接口规范，这个根据公司具体情况而定，但一定要前后端都确认。

这是为了避免前后端分离后最常见的扯皮现象。特别是遇到后端不主动（没有责任心），什么事都需要前端催。比如某个接口少一个字段，少一个接口等等。后端不熟悉业务，也不看接口原型和需求，就直接把接口做完，任务做完就万事大吉了。每天除了等前端通知需要修改什么，就跟什么事都没发生过一样。

所以跟前后端确认接口很重要，不然会很着急。当然一次性把所有接口定义完美也不现实，调整在所难免，所以我们还是希望后端能够更主动一些，这样前后端沟通起来就会容易很多，大家的效率也会提高。

准备环境接口规范

前端（APP）与后端约定接口规范内容，确定各个接口的地址（URL）、输入（）和输出（），必要时详细注释各个字段的含义、数据类型等。

具体需要定义哪些接口可以按照以下思路来组织

接口协商重点调用接口服务失败常见错误码，如调用需要授权的接口却没有授权返回“”：1接口需要登录时如何处理，特别是同时涉及Web端/微信端/App端时，前端需要根据运行环境判断如何跳转到登录页面返回数据中图片URL是完整的还是部分的返回数据中页面跳转的URL是完整的还是部分的返回数据中日期的格式，是否使用时间戳还是格式化文本对于较大的数字（如Java的long类型），返回给前端时需要设置为类型，否则会出现溢出，导致数值不正确分页参数与分页信息如何避免无限滚动加载中可能出现的重复数据（使用分页可以避免传统分页的弊端）分页信息包含哪些内容（total，page，）分页信息什么时候表示是最后一页接口定义

所有接口均定义在项目前端静态文件目录下的.json文件中，启动puer-mock服务即可使用这些接口获取符合规范的虚假数据，或者查看接口文档。

关于puer-mock的具体使用方法，以及如何在.json中配置接口，请参考puer-mock项目，或者参考项目中已经配置好的其他接口。

接口协作

由于接口规范的定义和接口的实际实现是两个独立的部分，且涉及多人协作，因此在开发过程中可能会出现接口规范与实现不同步的情况，最终导致实际的接口不符合规范的定义，接口规范也会逐渐失去意义。

为了尽可能的避免这个问题，后端在接口实现的时候应该保证与接口规范的一致性，一旦出现分歧，要同步修改接口规范，尽可能的保持沟通。

接口文档（示例）

puer-mock-api-doc-html

后端接口通用规范接口地址及请求方法

接口根路径-推荐：或

接口地址即接口的URL，定义时使用相对路径（即不带域名信息），建议在模块中定义，建议使用REST风格，例如

接口参数

如果参数比较少，可以作为URL查询附加到接口的URL中，或者放在请求体中，如-Type:/x-www-form-（即表单提交方式）

对于复杂的接口参数（例如嵌套的多层数据结构），建议在HTTP请求体中包含JSON字符串作为接口参数，并设置-Type:/json;=utf-8。

例如

查询VIP用户接口

POST /users?limit=10 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
    "name": "hanmeimei",
    "isVip": true
}

接口返回的数据结构

建议的响应体类型为 -Type: /json;=utf-8。返回的数据包含在 HTTP 响应体中，该响应体为 JSON。它可能包含 3 个字段：数据、

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "data": {},
    "status": 0,
    "statusInfo": {
        "message": "给用户的提示信息",
        "detail": "用于排查错误的详细错误信息"
    }
}

字段名称字段描述

数据

业务数据

必须是任何 JSON 数据类型 (数组)。

建议总是返回一个（也就是多包一层），方便字段的扩展。

例如：用户数据应该返回{"user":{"name":"test"}}，而不是直接返回{"name":"test"}

状态代码

必须是 >= 0 的 JSON 整数。

状态信息

必须是任意 JSON 数据类型。

建议始终返回包含和字段

例如

这样我们就可以很容易地通过判断来处理数据

if (!response.status) {
    // status 为 0 或者没有 status 字段时表示接口成功返回了数据
    console.log(response.data);
} else {
    // 失败
    console.error(response.status, response.statusInfo);
    // 统一由服务端返回给用户的提示信息
    alert(response.statusInfo.message);
}

错误码说明：如何获取字段的值

越来越多的项目采用前后端分离开发模式，前端负责调用后端接口进行界面展示，如果界面展示出现异常，需要有一个快速便捷的方式排查线上错误，定位责任范围。

结合经验和行业实践，最简单有效的方法就是制定一套统一的错误码规范，协助多方解决接口错误问题。

例如

因此我们确定提示信息规范为：当后端接口调用失败时，接口提供用户能够理解的错误提示，前端将错误提示及错误码展示给用户，给予用户反馈。

关于错误码的规范，参考业界惯例，大致有两种解决方案

固定数字、设定区间（如手机号、身份证号）划分不同的错误类型

具体做法如下

关于错误分类的原则，我们可以根据发送的请求的最终状态进行分类

最终规范

错误码长度不定，整体格式为：字母+数字，使用字母作为错误类型，扩展性更好，数字建议以区间划分，细分错误。

例如：

统一对用户的错误提示（错误提示见下）

标准实现：weapp--api

接口实现建议：对于资源操作类型，使用HTTP动词来指定，减少接口URL数量。对外ID字段使用字符串类型。接口字段建议同时提供ID字段和展示字段。前端提交数据时，只提交ID字段。图片URL建议返回完整URL。建议同时返回时间戳原始值（或ISO标准格式）和格式化文本，统一展示。统一分页数据格式。注：参考系统设计说明。编码阶段说明。自检阶段说明。联调阶段说明。测试阶段说明。

客户端 API 请求规范

参数名称说明

艾美

国际移动设备识别码

信息管理系统

客户端用户 ID

，请求的时间戳

服务器发出

符号

md5签名字符串，为了缓解非法恶意请求，APP每次发出请求都需要对请求参数进行签名，进行安全认证

液化天然气

手机获取的经度