专栏首页技术那些事如何写出完美的接口:接口规范定义、接口管理工具推荐

如何写出完美的接口:接口规范定义、接口管理工具推荐

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

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

接口规范定义

一、协议规范

为了确保不同系统/模块间的数据交互,需要事先约定好通讯协议,如: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的接口也可以手工维护进去,这样可以很方便的做到全公司接口统一维护,而且也有比较完善的接口权限管理,方便分组管理。但缺点就是过于庞大,可能太适合小一点项目或团队。

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

本文分享自微信公众号 - 程序猿技术大咖(cxyjsdk),作者:xcbey0nd

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-07-10

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Java统一异常处理(配置文件集中化定义)

    无论任何项目,都避免不了在运行期间出现的一些异常,并伴随着因业务逻辑的需要而给出相应的提示,使得系统变得更加友好,这类提示处理,我们统称为异常处理(ex...

    xcbeyond
  • MySQL性能优化(二):选择优化的数据类型

    良好的设计是高性能的基石,应该根据系统的实际业务需求、使用场景进行设计、优化、再调整,在这其中往往需要权衡各种因素,例如,数据库表究竟如何划分、字段如何选择合适...

    xcbeyond
  • 面试官:给我说说你对Java GC机制的理解?

    使用Java快一年时间了,从最早大学时候对Java的憎恶,到逐渐接受,到工作中体会到了Java开发的各种便捷与福利,这确实是一门不错的开发语言。不仅是 ...

    xcbeyond
  • 6大设计原则之接口隔离原则

    如果有一天,他不在教书了,或者又有了新的职业,那我们还要修改调用该类的代码,更好的做法是将臃肿的接口变更为几个独立的接口

    烟草的香味
  • Java编程思想精粹(九)-接口

    尽管你的第一想法是创建接口,但对于构建具有属性和未实现方法的类来说,抽象类也是重要且必要的工具。毕竟你不可能总是使用纯粹的接口。

    JavaEdge
  • Java基础系列(二十四):接口入门

    接口主要用来描述类具有什么功能,而并不给出每个功能的具体实现。一个类可以实现一个或多个接口,并在需要接口的地方,随时使用实现了相应接口的对象。接口主要就是对行为...

    Vi的技术博客
  • 数据结构与算法2016-06-03

    一个算法调用自己来完成它的部分工作,在解决某些问题时,一个算法需要调用自身。如果一个算法直接调用自己或间接调用自己,就称这个算法是递归的。根据调用方式的不同,它...

  • 「JAVA」Java面向对象之面向接口编程,细节都在这里了

    比如,显示器中封装了很多电子元器件,这些元器件连接在一起为显示器的正常共工作提供支持,那显示器如何与外界的其他设备(如电脑主机、外放音响、耳机等设备)通信交互呢...

    老夫不正经
  • Go语言核心编程(4)——接口

    Go 语言的接口分为接口字面量类型和接口命名类型,接口的声明使用 interface 关键字 。 接口定义大括号内可以是方法声明的集合, 也可以嵌入另一个接口...

    羊羽shine
  • 接口测试

    模拟客户端向服务器发送请求,服务器接收请求后对相应的请求做处理并向客户端返回响应结果,客户端接收结果的一个过程

    zx钟

扫码关注云+社区

领取腾讯云代金券