精华内容
下载资源
问答
  • REST接口规范总结

    万次阅读 2019-06-18 18:30:55
    REST接口规范总结

    1 REST

    REST是一种软件架构风格,如果你的接口是REST接口,那么该接口可被认为是REST风格的。
    REST接口是围绕资源展开的,HTTP 的URL即资源,利用HTTP的协议,其实rest本也可以和HTTP无关,但是现在大家普遍的使用REST都是依托于HTTP协议。

    2 URI语法

    URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]

    scheme: 指底层用的协议,如http、https、ftp
    host: 服务器的IP地址或者域名
    port: 端口,http中默认80
    path: 访问资源的路径,就是咱们各种web 框架中定义的route路由
    query: 为发送给服务器的参数
    fragment: 锚点,定位到页面的资源,锚点为资源id
    

    3 URL路径

    • 3.1 endpoint

    路径又称"终点"(endpoint),表示API的具体网址。
    在RESTful架构中,每个网址代表一种资源,所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。
    一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

    举例来说,有一个API提供学校的信息,包括各个班级,老师,同学的信息,则它的路径应该设计成下面这样:

        https://school/v1/classes
        https://school/v1/teachers
        https://school/v1/students
    
    • 3.1 URL规则
    • 1 名词对应数据库中的表
    • 2 URL中不能有动词
    • 3 URL结尾不应该包含斜杠“/”
    • 4 正斜杠分隔符”/“必须用来指示层级关系
    • 5 使用连字符”-“来提高URL的可读性,而不是使用下划线”_”
    • 6 URL路径中首选小写字母
    • 7 URL路径名词均为复数

    4 HTTP动词

    对于URL资源的具体操作类型,由HTTP动词表示。
    常用的HTTP动词有下面五个(括号里是对应的SQL命令)。

          GET(SELECT):从服务器取出资源(一项或多项)。
          POST(CREATE):在服务器新建一个资源。
          PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
          PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
          DELETE(DELETE):从服务器删除资源。
    

    5 资源过滤

    如果只需要查询某些条件的数据API应该提供参数,过滤返回结果。
    下面是一些常见的参数:

        ?limit=10:指定返回记录的数量
        ?offset=10:指定返回记录的开始位置。
        ?page=2&per_page=100:指定第几页,以及每页的记录数。
        ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
        ?teacher_subject=语文:指定筛选条件
    

    6 返回

    返回状态码推荐标准HTTP状态码

    有很多服务器将返回状态码一直设为200,然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。
    由于REST API是直接使用的HTTP协议,所以它的状态码也要尽量使用HTTP协议的状态码。

    200 OK 服务器返回用户请求的数据,该操作是幂等的
    201 CREATED 新建或者修改数据成功
    204 NOT CONTENT 删除数据成功
    400 BAD REQUEST 用户发出的请求有问题,该操作是幂等的
    401 Unauthoried 表示用户没有认证,无法进行操作
    403 Forbidden 用户访问是被禁止的
    422 Unprocesable Entity 当创建一个对象时,发生一个验证错误
    500 INTERNAL SERVER ERROR 服务器内部错误,用户将无法判断发出的请求是否成功
    503 Service Unavailable 服务不可用状态,多半是因为服务器问题,例如CPU占用率大,等等
    ......
    

    返回结果

    GET 		/teachers 返回资源列表
    GET 		/teachers/:id 返回单独的资源
    POST 		/teachers 返回新生成的资源对象
    PUT 		/teachers/:id 返回完整的资源对象
    PATCH	/teachers/:id 返回被修改的属性
    DELETE 	/teachers/:id 返回一个空文档
    
    展开全文
  • 接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写。 接口规范定义 一、协议规范 为了确保不同系统/模块间的数据交互,需要事先约定好通讯协议,如:TCP、HTTP、...

         无规矩不成方圆,为了开发人员间更好的配合,我特意整理了这么一篇文档供大家参考学习,如有意见、见解,请在评论区留言探讨。

         接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写

     

    接口规范定义

    一、协议规范

        为了确保不同系统/模块间的数据交互,需要事先约定好通讯协议,如:TCP、HTTP、HTTPS协议。为了确保数据交互安全,建议使用HTTPS协议。

     

    二、接口路径规范

        作为接口路径,为了方便清晰的区分来自不同的系统,可以采用不同系统/模块名作为接口路径前缀。

    格式规范如下:

        支付模块   /pay/xx

        订单模块  /order/xx

     

    三、版本控制规范

        为了便于后期接口的升级和维护,建议在接口路径中加入版本号,便于管理,实现接口多版本的可维护性。如果你细心留意过的话,你会发现好多框架对外提供的API接口中(如:Eureka),都带有版本号的。如:接口路径中添加类似"v1"、"v2"等版本号。

    格式规范如下:

          /xx/v1/xx

    更新版本后可以使用v2、v3等、依次递加。

     

    四、接口命名规范

        和Java命名规范一样,好的、统一的接口命名规范,不仅可以增强其可读性,而且还会减少很多不必要的口头/书面上的解释。

        可结合【接口路径规范】、【版本控制规范】,外加具体接口命名(路径中可包含请求数据,如:id等),建议具体接口命名也要规范些,可使用"驼峰命名法"按照实现接口的业务类型、业务场景等命名,有必要时可采取多级目录命名,但目录不宜过长,两级目录较为适宜。

    格式规范如下:

        /user/v1/sys/login     用户服务/模块的系统登录接口

       /zoo/v1/zoos/{ID}        动物园服务/模块中,获取id为ID的动物

     

    具体接口命名,通常有以下两种方式:

    • 接口名称动词前/后缀化

        接口名称以接口数据操作的动词为前/后缀,常见动词有:add、delete、update、query、get、send、save、detail、list等,如:新建用户addUser、查询订单详情queryOrderDetail。

    • 接口名称动词+请求方式

         接口路径中包含具体接口名称的名词,接口数据操作动作以HTTP请求方式来区分。常用的HTTP请求方式有:

        GET:从服务器取出资源(一项或多项)。

        POST:在服务器新建一个资源。

        PUT:在服务器更新资源(客户端提供改变后的完整资源)。

        PATCH:在服务器更新资源(客户端提供改变的属性)。

        DELETE:从服务器删除资源。

    如:

        GET /zoo/v1/zoos:列出所有动物园

        POST /zoo/v1/zoos:新建一个动物园

        GET /zoo/v1/zoos/{ID}:获取某个指定动物园的信息

        PUT /zoo/v1/zoos/{ID}:更新某个指定动物园的信息(提供该动物园的全部信息)

        PATCH /zoo/v1/zoos/{ID}:更新某个指定动物园的信息(提供该动物园的部分信息)

        DELETE /zoo/v1/zoos/{ID}:删除某个动物园

        GET /zoo/v1/zoos/{ID}/animals:列出某个指定动物园的所有动物

        DELETE /zoo/v1/zoos/ID/animals/ID:删除某个指定动物园的指定动物

     

    五、请求参数规范

    • 请求方式:

    按照GET、POST、PUT等含义定义,避免出现不一致现象,对人造成误解、歧义。

    • 请求头:

    请求头根据项目需求添加配置参数。如:请求数据格式,accept=‘application/json’等。如有需要,请求头可根据项目需求要求传入用户token、唯一验签码等加密数据。

    • 请求参数/请求体:

            请求参数字段,尽可能与数据库表字段、对象属性名等保持一致,因为保持一致最省事,最舒服的一件事。

     

    六、返回数据规范

        统一规范返回数据的格式,对己对彼都有好处,此处以json格式为例。返回数据应包含:返回状态码返回状态信息具体数据。

    格式规范如下:

    {
    
        "status":"000000",
    
        "msg":"success",
    
        "data": {
    
            //json格式的具体数据
    
        }
    
    }

            返回数据中的状态码、状态信息,常指具体的业务状态,不建议和HTTP状态码混在一起。HTTP状态,是用来体现 HTTP链路状态情况,如:404-Not Found。HTTP状态码和json结果中的状态码,并存尚可,用于体现不同维度的状态。

     

    接口管理工具推荐

        接口开发完后,最终的目的是提供给其他系统/模块来使用的,因此,接口的管理是必不可少的。

    接口管理的痛点

        接口的管理常常面临很多的痛苦,这里就列举几个常见的,看看你是否也遇到过。

    • 系统/模块太多、接口太多,没有系统统一管理所有接口。
    • 代码修改后,接口文档没有及时更新,造成接口文档和实际接口不一致的现象。
    • 接口管理系统自主研开发成本高。
    • 接口管理缺少接口mock功能。

    接口管理工具推荐

           在日常工作过程中用过、接触过的接口管理工具也是不尽其数,下面介绍你可能使用过、没有使用过的接口管理工具,同时也介绍这些接口管理工具的优缺点。   

    word

          相信大家之前用来管理接口比较多的应该是word吧,开发人员将系统的接口维护在word文档里,不管是组内沟通还是和其他团队的接口沟通都离不开这些接口文档,每次修改文档和代码都要同步修改。相信使用word的缺点大家应该也很清楚,就是维护和管理很麻烦,我们经常会遇到文档和代码不一致的情况,大部分不一致都是因为接口因为种种原因修改了,开发人员大部分都是只改了代码里的接口实现,而没有去修改接口文档。而且word文档搜索接口也很麻烦,没办法建全局索引,只能一个个文档点开查看,想想就很痛苦。但不可否认的是,word对于一些小团队用起来还是挺方便的,不用搭建系统,给谁一看就明白。

    自建接口管理系统

           对于一些有一定规模的企业,在各项工程管理活动上都非常正规,各种ISO标准要遵守,自然对接口管理的要求也非常高,之前在国有银行,我们就是自建了接口管理系统,自建还是很消耗人力成本的,从开发到后续运维,都要消耗人力,但是自建的好处就是,可以根据公司的要求进行各种花样的定制,我们之前在接口管理系统中加入了很多好用的定制功能,例如接口被哪些系统调用、接口是在哪个批次投产又在哪个批次做过变更等等,这对于架构师来说非常好用,用于分析接口影响范围非常方便。目前开源的接口管理系统还没有能做到这些定制化功能的。

    wiki

          之前在小团队的时候还用过一段时间的私有wiki,wiki特别适合于小团队高速线性迭代开发,在wiki上看到的就是最新的接口,团队内所有成员看到的都是一样的,如果接口有变化,相关开发人员修改后立即生效,保证了顺畅的接口沟通。但是wiki的缺点也很多,接口文档只是静态页面,无法实现一些动态效果,无法实现追溯等等缺点。

    RAP

           相信很多互联网公司都在使用RAP,RAP是阿里开源的一套接口管理系统,RAP可以比较方便的管理公司所有系统的接口,同时还有比较完善的权限管理,还可以做接口mock,方便开发人员在接口功能还没有完成的时候能够及时发布出去,给调用方去使用。但是RAP的缺点就是每个接口都需要维护进去,接口修改后也需要及时维护,当时我们在使用的时候遇到的最大的问题也是经常碰到接口没有及时维护的问题。

    swagger

          上面说的那些接口管理工具,其实都有一个很大的问题就是修改代码后需要同步维护接口文档,但是让程序员去修改文档是很难的,大部分程序员都比较讨厌维护各类文档。当我第一次了解到swagger的时候,发现这简直就是为程序员定制的接口管理工具,swagger定义了很多注解,在对接口加上swagger相关的注解,当接口代码修改后,swagger在工程启动后会根据代码自动生成最新的接口html文档,同时swagger提供了mock接口模拟的功能,也能够更加方便的模拟接口,并且还能够在swagger界面上直接发起接口调用,可以方便调用方在还没写代码的时候就能够尝试下接口调用后的结果。

          看了那么多swagger的优点,下面也说说swagger的缺点,那就是swagger是跟随着每个工程一起启动的,这就导致每个工程都有一个swagger的访问地址,如果公司系统很多的话,那就会导致查看不同系统的接口都要到不同的地址去查看,每个开发都要自己收藏好各个系统的swagger地址。有些公司也自己开发了统一网关,将所有swagger的接口地址聚合起来,但是多少还是涉及到一些开发工作的,而且做的还不一定很完善。

    Easy Mock

            官网的这张图基本上介绍清楚了easymock的核心功能,这其中我最看重的功能有两块,一个是能够集成swagger接口并集中管理所有接口,另一个就是响应式数据。

           EasyMock能够根据swagger接口的地址自动导入所有swagger接口,非常方便,对于非swagger的接口也可以手工维护进去,这样可以很方便的做到全公司接口统一维护,而且也有比较完善的接口权限管理,方便分组管理。但缺点就是过于庞大,可能太适合小一点项目或团队。

     

          上面提及到接口管理工具,大家可根据自己项目的规模、需求,进行实际选择,切记生搬硬套。

     

    欢迎微信扫码下面二维码,关注微信公众号【程序猿技术大咖】,进行更多交流学习!

    展开全文
  • Restful API 接口规范

    2020-09-09 22:35:23
    文章目录Restful API 接口规范背景什么是RESTful架构呢?RESTful API 设计 Restful API 接口规范 暑假期间接触到实际开发项目对开发过程中遇到的Restful接口规范存在疑惑,由于当时主要目的是尽快本地运行项目,尝试...

    Restful API 接口规范

    暑假期间接触到实际开发项目对开发过程中遇到的Restful接口规范存在疑惑,由于当时主要目的是尽快本地运行项目,尝试开发,没有对这个接口规范深入了解。趁着最近时间比较轻松,逐步学习Restful规范

    背景

    越来越多的人开始意识到,网站即软件,而且是一种新型的软件。

    这种"互联网软件"采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时(high latency)、高并发等特点。

    网站开发,完全可以采用软件开发的模式。但是传统上,软件和网络是两个不同的领域,很少有交集;软件开发主要针对单机环境,网络则主要研究系统之间的通信。互联网的兴起,使得这两个领域开始融合,现在我们必须考虑,如何开发在互联网环境中使用的软件。
    img

    RESTful架构,就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。

    什么是RESTful架构呢?

    REST(Representational State Transfer)

    REST的名称"表现层状态转化"中,省略了主语。“表现层"其实指的是"资源”(Resources)的"表现层"。

    资源(Resources)

    • 所谓"资源",就是网络上的一个实体,或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务,总之就是一个具体的实在。你可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。

    • 所谓"上网",就是与互联网上一系列的"资源"互动,调用它的URI。

    表现层(Representation)

    "资源"是一种信息实体,它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式,叫做它的"表现层"(Representation)。

    比如,文本可以用txt格式表现,也可以用HTML格式XML格式JSON格式表现,甚至可以采用二进制格式;图片可以用JPG格式表现,也可以用PNG格式表现。

    URL只代表资源的实体,不代表它的形式。严格地说,有些网址最后的".html"后缀名是不必要的,因为这个后缀名表示格式,属于"表现层"范畴,而URI应该只代表"资源"的位置。它的具体表现形式,应该在HTTP请求的头信息中用AcceptContent-Type字段指定,这两个字段才是对"表现层"的描述。

    状态转化(State Transfer)

    访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必涉及到数据和状态的变化。

    互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。而这种转化是建立在表现层之上的,所以就是"表现层状态转化"。

    客户端用到的手段,只能是HTTP协议。具体来说,就是HTTP协议里面,四个表示操作方式的动词:GETPOSTPUTDELETE。四个表示操作方式对应对应四种基本操作

    • GET 获取资源
    • POST 新建资源
    • PUT 更新资源
    • DELETE 删除资源

    在这里插入图片描述

    综合上面,RESTful架构的内容:

    1. 每一个URI代表一种资源;
    2. 客户端和服务器之间,传递这种资源的某种表现层;
    3. 客户端通过四个HTTP动词,对服务器端资源进行操作,实现"表现层状态转化"。

    RESTful API 设计

    1. API与用户的通信协议

      采用HTTPs协议

    2. 域名

      api关键字标识接口url

      示例:

       # 应该尽量将API部署在专用域名之下。
       # 表示前后端数据交互
       https://api.example.com
       
       # 应该尽量将API部署在专用域名之下。
       https://example.org/api/
    
    1. 路径

      路径又称"终点"(endpoint),表示API的具体网址。

      在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。

    2. HTTP动词

      对于资源的具体操作类型,由HTTP动词表示。

       GET(SELECT):从服务器取出资源(一项或多项)。
       POST(CREATE):在服务器新建一个资源。
       PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
       PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
       DELETE(DELETE):从服务器删除资源。
    

    不常用

       HEAD:获取资源的元数据。
       OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
    
    1. 状态码
       200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
       201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
       202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
       204 NO CONTENT - [DELETE]:用户删除数据成功。
       
       
       301:永久重定向
       302:暂时重定向
       
       
       400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
       401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
       403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
       404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
       406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
       410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
       422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
       
       
       500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
    
    1. 错误处理

      状态码是4xx时,应返回错误信息,error当做key。

       {
           error: "Invalid API key"
       }
    
    1. 返回结果格式

      尽量采用json格式避免XML格式

       GET /collection:返回资源对象的列表(数组)
       GET /collection/resource:返回单个资源对象
       POST /collection:返回新生成的资源对象
       PUT /collection/resource:返回完整的资源对象
       PATCH /collection/resource:返回完整的资源对象
       DELETE /collection/resource:返回一个空文档
    
    展开全文
  • 前后端接口规范

    千次阅读 2019-04-01 18:38:16
    随着前后端分离越来越普遍, 后端接口规范也就越来越重要了. 一套良好的接口规范可以提升工作效率, 减少沟通障碍. 通常我们都会采用 REST 方式来提供接口, 使用 JSON 来传输数据. 名词 含义 前端...

    原文地址

    https://github.com/f2e-journey/treasure/blob/master/api.md

    前后端接口规范

    随着前后端分离越来越普遍, 后端接口规范也就越来越重要了. 一套良好的接口规范可以提升工作效率, 减少沟通障碍.

    通常我们都会采用 REST 方式来提供接口, 使用 JSON 来传输数据.

    名词 含义
    前端 Web前端, APP端, 桌面端等一切属于用户界面的这一层
    后端 即服务器端, 指一切属于用户界面之下的这一层
    前后端接口 前端与后端进行数据交互的统称, 也叫做数据接口, 属于一种远程调用, 一般指前端通过HTTP(ajax)请求获取到的数据或者执行的某项操作. 为确保前后端(工程师)的协作沟通, 一般由前端和后端一起来定义接口的规范, 规范的内容一般包含接口的地址, 接口的输入参数和输出的数据格式(结构), 最终由后端来实现这些规范, 为前端提供符合规范的接口
     [前端] 
    --------
       ^
       |
       |
    前后端接口
       |
       |
    --------
     [后端]
    

    前后端接口协作流程

    在开发之前一定要先定义好接口规范, 至于接口应该由前端来定还是后端来定, 这个还得看公司的具体情况, 但一定要让前后端都确认无误, 特别是接口协商要点.

    以免出现前后端分离之后最容易出现的扯皮现象. 特别是当你碰到做事不主动(无责任感)的后端, 什么都要前端来催. 比如什么接口又缺了一个字段没有提供啦, 什么又少了一个接口啦, 等等诸如此类. 后端不去熟悉业务, 也不看界面原型和需求, 只管把接口做完, 任务完成就万事大吉了, 每天除了等前端通知哪里要修改, 自己就像没事人一样.

    所以说定好接口, 前后端一起来确认好接口是多么的重要, 不然你就等着干着急吧. 当然了, 想一次性完美地将所有接口都定义出来, 有点不太现实, 需要调整的情况在所难免, 所以还是希望后端能够主动一点, 前后端沟通的时候就轻松得多, 大家的效率就都提高了.

    准备环境

    接口规范

    由前端(APP端)和后端一起协定接口规范的内容, 确定每一个接口的地址(URL), 输入(request)和输出(response), 必要的时候详细注释每一个字段的含义和数据类型.

    具体需要定义哪些接口, 可以按照下面的思路来整理

    • 资源接口: 系统涉及到哪些资源, 按照 RESTful 方式定义的细粒度接口
    • 操作接口: 页面涉及到哪些操作, 例如修改购物车中商品的数量, 更换优惠券等等, 也可以使用 RESTful 方式来定义
    • 页面接口: 页面涉及到太多接口, 如果是一个个地调用, 会需要很多次请求, 有可以影响到前端的性能和用户感知(特别是首屏的体验), 因此可能需要将这些接口的数据合并到一起, 作成一个聚合型接口提供给前端来使用

    接口协商要点

    • 接口必须返回统一的数据结构, 参考后端接口通用规范中接口返回的数据结构
    • 接口查询不到数据时, 即空数据的情况下返回给前端怎样的数据
      • 建议返回非 null 的对应数据类型初始值, 例如对象类型的返回空对象({}), 数组类型的返回空数组([]), 其他原始数据类型(string/number/boolean…)也使用对应的默认值
      • 这样可以减少前端很多琐碎的非空判断, 直接使用接口中的数据
      • 例如: result.fieldName
      • 如果 resultnull, 可想而知会报错 Uncaught TypeError: Cannot read property 'fieldName' of null
    • 调用接口业务失败的常用错误码, 例如未授权时调用需要授权的接口返回 "status": 1
    • 接口需要登录时如何处理, 特别是同时涉及到 Web 端/微信端/App 端, 需要前端针对运行环境判断如何跳转到登录页面
    • 返回数据中图片 URL 是完整的还是部分的
      • http://a.res.com/path/to/img.png 这就是完整的, 前端直接使用这个 URL
      • /path/to/img.png 这就是部分的, 一般省略域名部分, 前端需要自己拼接后才能使用 'http://a.res.com' + '/path/to/img.png'
    • 返回数据中页面跳转的 URL 是给完整的还是部分的
      • 内部页面返回部分的, 或者只给ID, 由前端自己拼接, 例如只给出商品ID, 让前端自己拼接商品详情页的 URL
      • 外部页面返回完整的, 例如广告位要跳转去谷歌
    • 返回数据中日期的格式, 是使用时间戳还是格式化好的文字
      • 对于需要前端再次处理的日期值(例如根据日期计算倒计时), 可以使用时间戳(简单暴力), 例如: 1458885313711, 或者参考 Date.prototype.toJSON 提供 ISO 标准格式(例如需要考虑时区时)
      • 对于纯展示用的日期值, 推荐返回为格式化好的文字, 例如: 2017年1月1日
    • 对于大数字(例如 Java 的 long 类型), 返回给前端时需要设置为字符串类型, 否则 JavaScript 会发生溢出, 造成得到的数值错误
      • 例如: 返回 JSON 数据 {"id": 362909601374617692} 前端拿到的值却是: 362909601374617660
    • 分页参数和分页信息
      • 如何限制只返回 N 条数据(limit 参数)
      • 如何控制每页的数据条数(pageSize 参数)
      • 如何加载某一页的数据(page 参数)
        • 第一页是从 0 开始还是从 1 开始
      • 如何避免无限滚动加载可能出现的重复数据(采用 lastId 分页方式, 来避免传统分页方式的弊端)
        • 假设数据是按照新增时间倒序排列的
        • 首先加载 2 页的数据
        • 等了很久
        • 期间新增了很多数据
        • 再获取第 3 页数据
        • 此时就可能出现重复数据的情况, 因为新增的数据都排在最前面, 后面会接着已经加载过数据
      • 分页信息包含什么(total, page, pageSize)
      • 分页信息何时表明已经是最后一页了
        • 请求某页数据时返回的数据条数 < pageSize
        • 请求某页数据时返回的数据条数 = 0
        • 如果碰巧最后一页有 pageSize 条数据, 前端无法通过数据条数来判断已经处于最后一页了

    接口定义

    所有的接口定义在项目前端静态文件目录的 _mockserver.json 文件中, 启动 puer-mock 服务, 即可使用这些接口获得符合规范的假数据, 也可以查看接口文档.

    具体 puer-mock 的详细使用手册和 _mockserver.json 如何配置接口请参考 puer-mock 项目, 或者参考项目中已经配置好的其他接口.

    接口协作

    由于接口规范的定义和接口的实际实现是分开的两个部分, 而且涉及到多人协作, 因此在开发过程中可能出现接口规范与实现不同步, 最终造成实际的接口不符合规范的定义, 接口规范就会慢慢失去存在的意义.

    为了尽量避免这种问题, 后端在实现接口的过程中应该确保与接口规范保持一致, 一旦出现分歧, 必须同步修改接口规范, 尽可能保持沟通.

    接口文档(示例)

    puer-mock-api-doc-html

    后端接口通用规范

    接口地址和请求方式

    接口根路径 - Root Endpoint 推荐为: http://api.yourdomain.com 或者 http://yourdomain.com/api

    接口地址即接口的 URL, 定义时使用相对路径(即不用带上域名信息), 建议分模块来定义, 推荐 REST 风格, 例如

    • GET /user/:id 表示获取用户信息
    • POST /user 表示新增用户

    接口参数

    向接口传递参数时, 如果是少量参数可以作为 URL query string 追加到接口的 URL 中, 或者作为 Content-Type: application/x-www-form-urlencoded 放在请求体(body)中(即表单提交的方式)

    对于复杂的接口参数(例如嵌套了多层的数据结构), 推荐在 HTTP 请求体(body)中包含一个 JSON 字符串作为接口的参数, 并设置 Content-Type: application/json; charset=utf-8.

    例如

    查询 VIP 用户的接口

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

    接口返回的数据结构

    返回的响应体类型推荐为 Content-Type: application/json; charset=utf-8, 返回的数据包含在 HTTP 响应体中, 是一个 JSON Object. 该 Object 可能包含 3 个字段 data, status, statusInfo

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "data": {},
        "status": 0,
        "statusInfo": {
            "message": "给用户的提示信息",
            "detail": "用于排查错误的详细错误信息"
        }
    }
    
    字段名 字段说明
    data 业务数据
    必须是任意 JSON 数据类型(number/string/boolean/object/array).
    推荐始终返回一个 object (即再包一层)以便于扩展字段.
    例如: 用户数据应该返回 {"user":{"name":"test"}}, 而不是直接为 {"name":"test"}
    status 状态码
    必须是 >= 0 的 JSON Number 整数.
    • 0 表示请求处理成功, 此时可以省略 status 字段, 省略时和为 0 时表示同一含义.
    • 非 0 表示发生错误时的错误码, 此时可以省略 data 字段, 并视情况输出 statusInfo 字段作为补充信息
    statusInfo 状态信息
    必须是任意 JSON 数据类型.
    推荐始终返回一个 object 包含 messagedetail 字段
    • message 字段作为接口处理失败时, 给予用户的友好的提示信息, 即所有给用户的提示信息都统一由后端来处理.
    • detail 字段用来放置接口处理失败时的详细错误信息. 只是为了方便排查错误, 前端无需使用.

    例如

    • 接口处理成功时接口返回的数据

      {
          "data": "api result"
          "status": 0
      }
      
    • 接口处理失败时接口返回的数据

      {
          "status": 1,
          "statusInfo": {
              "message": "服务器正忙",
              "detail": {
                  "exception": "java.util.List"
              }
          }
      }
      

    这样我们就可以非常容易地通过判断 status 来处理数据了

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

    错误码规范: status 字段该如何取值

    采用前后端分离开发模式的项目越来越多, 前端负责调用后端的接口来展现界面, 如果有界面显示异常, 需要有快速方便的手段来排查线上错误和定位出职责范围

    综合了经验总结和行业实践, 最简单有效的手段是制定出一套统一的错误码规范, 协助多方人员来排查出接口的错误

    例如

    • 用户发现错误, 可以截错误码的图, 就能够提供有效的信息帮助开发人员排查错误
    • 测试人员发现错误, 可以通过错误码, 快速定位是前端的问题还是后端接口的问题

    因此我们确定提示信息规范为: 当后端接口调用出错时, 接口提供一个用户可以理解的错误提示, 前端展示给用户错误提示和错误码, 给予用户反馈

    对于错误码的规范, 参考行业实践, 大致有两种方案

    具体实践如下

    • 错误码固定长度, 以区间来划分错误类型(例如 HTTP 的状态码)

      例如: 10404 表示 HTTP 请求 404 错误, 20000 表示 API 调用失败, 30000 代表业务错误, 31000 表示业务A错误, 32000 表示业务B错误

    • 错误码可不固定长度, 以首字母来划分错误类型, 可扩展性更好, 但实际运作还是需要划分区间

      例如: H404 表示 HTTP 请求 404 错误, A100 表示 API 调用失败, B100 表示业务A错误, B200 表示业务B错误

    关于错误分类的原则, 我们可以根据发送请求的最终状态来划分

    • 发送失败(即请求根本就没有发送出去)
    • 发送成功
      • HTTP 异常状态(例如 404/500…)
      • HTTP 正常状态(例如 200)
        • 接口调用成功
        • 接口调用失败(业务错误, 即接口规范中 status 非 0 的情况)

    最终规范

    错误码可不固定长度, 整体格式为: 字母+数字, 字母作为错误类型, 可扩展性更好, 数字建议划分区间来细分错误

    例如:

    • A for API: API 调用失败(请求发送失败)的错误, 例如 A100 表示 URL 非法
    • H for HTTP, HTTP 异常状态的错误, 例如 H404 表示 HTTP 请求404错误
    • B for backend or business, 接口调用失败的错误, 例如 B100 业务A错误, B200 业务B错误
    • C for Client: 客户端错误, 例如 C100 表示解析 JSON 失败

    统一错误提示

    • 错误日志
      • 接口调用出错(${错误码}) ${HTTP 方法} ${HTTP URL} ${请求参数} ${请求选项} ${请求返回结果}
      • 例如: 接口调用出错(H404) GET https://domain.com {foo: bar} {option1: 'test'} {status: 404}
    • 给用户的提示消息(参考自 QQ 的错误提示消息)
      • 提示消息(错误码: xxx)

        weapp-error-tip weibo-error-tip qq-error-tip

      • 提示消息和错误码之间用换行隔开

      • 错误码整块内容建议弱化使用灰色字

      • 例如

        mobile-error-code-message
        pc-error-code-message

    规范实现: weapp-backend-api

    接口实现建议

    • 接口实现的大方向建议遵循 RESTful 风格
    • HTTP 动词: 获取数据用 GET, 新增/修改/发送数据用 POST
      • 例如: 获取用户数据的接口用 GET, 修改用户数据的接口用 POST
    • 对于资源的操作类型, 使用 HTTP 动词来指定, 减少接口 URL 的数量
      • 例如: GET /contact 获取联系人, POST /contact 新增/修改联系人
    • 对外的 ID 字段使用字符串类型
      • 特别核心数据的 ID 字段, 不要使用自增的数字类型, 建议使用无规则的字符串类型(例如UUID), 避免核心数据被轻易抓取
      • 避免使用大数字类型(Long), 因为前端可能承载不了这个精度而溢出得到另外一个数值
      • 例如: Java 中的 Long 类型的数值: 362909601374617692, 作为 JSON 数据返回给前端, 前端拿到的值变成了 362909601374617660
    • 接口字段建议同时给出 ID 字段和用于显示字段, 前端提交数据时只提交 ID 字段
      • 例如: {"sex": 1, "sexText": "男"}
    • 图片的 URL 建议返回完整的 URL
      • 例如: {"pic": "https://domain.com/a.png"}
    • 时间字段建议同时返回时间戳的原始值(或 ISO 标准格式)和用于统一显示的格式化文本
      • 由后端接口集中控制各端的显示, 提供的原始值兼顾前端的自定义显示或者计算(例如倒计时)的需求
      • 避免每个端(例如H5/APP/小程序)都需要对时间做统一的格式化实现, 一旦需要调整, 需要各个端都调整一遍
      • 例如: {"createTime": 1543195480357, "createTimeText": "2018年11月26日"}
    • 统一分页的数据格式
      • 分页请求的参数和分页结果的数据结构

    注意

    参考

    • E-JSON数据传输标准

    • 有范云协作 让项目的协作姿势更有范儿

      • 交互阶段说明
        • 交互设计师根据产品方的需求对产品进行行为设计和界面设计的阶段,主要产出物为交互设计稿
        • 开发工程师需要做的事情是针对产品需求、交互设计稿中的内容进行技术评审,为产品方、交互设计师提供可行技术实现解决方案,对于多种不同解决方案需针对各种解决方案做分析说明,务必准确传达各种方案的优缺点,并根据需求给出建议方案
      • 系统设计说明
        • 各端开发工程师针对产品需求说明、交互设计稿开始设计系统架构、拆分子系统、划分子系统模块、协调端与端之间的接口规范,这个阶段各端根据实际情况输出若干系统设计说明书等文档
        • 除此之外更重要的是输出端与端之间通信的接口规范,而这个规范则可以借助 NEI 平台 来完成
      • 编码阶段说明
        • 开发工程师根据系统设计阶段的输出,用代码来实现这样的系统,包括技术方案的选型、项目框架的搭建、工具及环境的配置等
        • 其中有些工作可以借助于有范云协作提供的自动化工具 NEI-Toolkit 来完成,比如项目的初始结构代码、在 NEI平台 上定义好的接口规范等
      • 自测阶段说明
        • 各个端的工程师验证自己编写的代码的正确性,按角色不同,测试方式也有所有不同
        • 对于前端和移动端工程师来说,主要是需要测试各种可能的值会不会影响界面展示
        • 对于服务端工程师来说,主要是测试提供给客户端工程师使用的接口的正确性,对于不同的输入参数是否返回了预期的结果
      • 联调阶段说明
        • 主要是连测试环境进行测试
        • 对于前端和移动端工程师来说,主要是需要将本地容器提供的接口换成测试环境的接口
      • 测试阶段说明
        • 开发工程师开发完成后提测的过程,是产品上线前的最后环节
        • 测试工程师会对接 NEI 平台生成接口测试用例代码并集成到自动化测试平台运行,如果NEI平台的接口定义与实际提测的项目不符则此次提测失败,需由开发对照 NEI 平台检查接口实现情况,所以可以保证 NEI 平台上的接口定义始终与线上保持一致
    • 客户端API请求规范

      参数名 说明
      imei 国际移动设备身份码
      imsi 客户端用户标识
      t TIMESTAMP,请求的时间戳
      appkey 由服务端颁发的appkey
      sign md5签名串。为了减轻非法恶意请求,每次来自APP的请求都需要对请求参数进行签名以实现安全认证
      lng 手机上获取的经度
      lat 手机上获取的纬度
      ci 渠道标识,格式为:channelId@应用名平台客户端版本,例如:1001@nzaom_android_1.0,其中1001表示应用宝
    • GitHub API | 微博API | 淘宝开放平台 API

    • JSend | JSON API | JSON Schema | JSON-RPC | JWT | OAuth

      Type Description Required Keys Optional Keys
      success All went well, and (usually) some data was returned. status, data
      fail There was a problem with the data submitted, or some pre-condition of the API call wasn’t satisfied status, data
      error An error occurred in processing the request, i.e. an exception was thrown status, message code, data
    • Google JSON Style Guide

    • 最佳实践:更好的设计你的 REST API | RESTful API 设计指南 | Best Practices for Designing a Pragmatic RESTful API | HTTP API Design Guide | The RESTful Cookbook | RESTful API 编写指南

    • Restlet Studio - Web IDE for API design | Swagger | ReDoc | RAML | API Blueprint

    展开全文
  • 应用集成接口规范

    千次阅读 2018-11-09 10:31:41
    应用集成接口规范
  • [PCIe-M.2-接口规范-V1.0-接口定义] 总线和接口标准说明,介绍总线和接口标准规范
  • AXI Stream接口,AXI 流接口规范
  • 税控发票开票软件发票信息数据接口规范V4.0,增值税普通发票(电子)企业端(单机版数据文件)接口规范V1.1,增值税普通发票(电子)企业端(服务器版可编程)接口规范V1.1。国家税务总局最新发票接口规范,含电子...
  • 后端开发接口规范

    千次阅读 2019-05-23 07:33:07
    因此制定本接口规范,规范前后端的开发标准。 参考如下接口文档格式: 接口名称:审核列表 接口描述:接口的使用场景 接口URL: {service}/rider/check/r/new/list 请求方式:get|post 请求参数(json对象)...
  • API接口规范

    千次阅读 2018-03-13 13:22:54
    接口规范:1.使用HTTPs协议,确保交互数据的传输安全2.应该尽量将API部署在专用域名之下,如:https://api.example.com3.应该将API的版本号放入URL中,如:https://api.example.com/v{n}/4.网址中不能有动词,只能有...
  • RESTful api接口规范

    千次阅读 2018-09-15 19:58:51
    RESTful 接口规范 整体规范建议采用RESTful 方式来实施。   协议 API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全。   域名 应该尽量将API部署在专用域名之下。 https://api.example.com...
  • 因为是接口框架,首先要做的就是制定接口规范,好的接口规范能约束开发人员,能降低前后端人员之间的沟通协调,能避免后期联调带来的一系列问题。 1.接口规范 接口规范包含以下内容: 1、请求类型及参数 2、返回值及...
  • 写在前面:这是我最近整理的接口规范文档,无规矩不成方圆,为了app开发人员与后台接口开发人员更好的配合,我特意整理了这么一篇文档供大家参考学习,如有意见请在评论区留言谢谢。因部分内容涉及公司代码,我对本...
  • 后台API接口规范

    千次阅读 2018-04-07 21:36:58
    接口规范 最新公司新的项目,使用spring boot,cloud,服务之间使用rest api进行调用,所有使用了restful 风格的接口 @RequestMapping(value = "/getByRegionId/{regionId}", method = RequestMethod.GET)...
  • 系统接口规范以及常见的接口技术概述和比较   一、基本要求: 为了保证系统的完整性和健壮性,系统接口应满足下列基本要求: 1、接口应实现对外部系统的接入提供企业级的支持,在系统的高并发和大容量...
  • 银联网关支付接口规范

    千次阅读 2018-11-15 08:59:40
    全渠道平台产品接口规范 产品 1 互联网支付跳转支付 ——网关支付产品 版本号: V2.2 2015-03-31 发布 2015-03-31 实施 发布 中国银联 版权所有 Q/CUP071.2.1—2015 I 中国银联股份有限公司(以下简称“中国银联”)...
  • TPshop之App后台接口规范

    千次阅读 2017-06-08 21:30:08
    接口规范接口示例参考文档 最近在整理和开发TPshop开源商城App(包括Android和iOS)的后台接口(api),总结一下。 1、 接口规范 接口的 URL 一般是: 官网域名/index.php?m=api&c=控制器&a=方法 ...
  • 《Java 本地接口规范
  • 接口规范文档

    千次阅读 2019-05-08 21:49:21
    1 需要调用图形验证码接口 调用时需要向图形验证码接口发送 uuid 2 需要将图形验证码 和 uuid 用户名密码 一同发送到登陆接口 /login 3 登陆成功后 /login 返回access_token 和 当前登陆用户数据 三 权限 所有...
  • 同花顺HTTP行情接口规范 PDF

    热门讨论 2012-03-10 21:30:18
    同花顺HTTP行情接口规范 PDF 2012/03/10 21:29:27 空白) 1、接口采用 HTTP协议和外围程序通讯 2、接口处理 POST方法提交的请求,返回 XML格式的数据 3、请求 URL:http://IP:PORT/hexin
  • 一般门户接口规范

    2010-11-15 11:18:00
    门户接口规范针对目前大型企业的门户中需要集成不同系统(如绩效考核,办公自动化等等),以提供单点登录功能,那么就需要在门户与各个系统间建立统一的接口规范,以下为二种规范:接口规范一:将登陆的信息提交至...
  • 智能 IC 卡及智能密码钥匙密码应用接口规范
  • 聊聊前后端分离接口规范 猿码道芋道源码今天 点击上方“芋道源码”,选择“设为星标” 做积极的人,而不是积极废人! 源码精品专栏 中文详细注释的开源项目 RPC 框架 Dubbo 源码解析 网络应用...
  • 数据接口规范

    千次阅读 2019-02-21 14:28:17
    1、按公司标准走 2、预定义的结构及字段要易懂,如有更改...4、接口需要记录关键性日志 5、接口性能,耗时要少,要有合适的缓存降低数据库压力 6、即使按预定义格式返回给需求方,也要让自己的代码结构化,易维护 ...
  • 就是小弟我最近在写接口规范的文档。。。。可是我又不太认识各个字母代表什么意思 比如S 代表字符串 N代表number D代表时间类型 AN。。20代表0到20位最大长度 AN。。18,2代表最大18.2 可是 N20又代表啥? D10又是...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 42,296
精华内容 16,918
关键字:

接口规范