专业游戏门户,分享手游网游单机游戏百科知识攻略!

嗨游网
嗨游网

接口设计怎么写,接口设计规范与6大原则

来源:小嗨整编  作者:小嗨  发布时间:2023-02-08 10:47
摘要:接口设计怎么写,接口设计规范与6大原则在设计接口时,有很多因素要考虑:接口的业务定位接口的安全性接口的可扩展性接口的稳定性接口的跨域性接口的协议规则接口的路径规则接口单一原则接口过滤及接口组合本篇文章将简要分析这些因素。一规范性建议1.职责...

接口设计怎么写,接口设计规范与6大原则

在设计接口时,有很多因素要考虑:

  • 接口的业务定位

  • 接口的安全性

  • 接口的可扩展性

  • 接口的稳定性

  • 接口的跨域性

  • 接口的协议规则

  • 接口的路径规则

  • 接口单一原则

  • 接口过滤及接口组合

本篇文章将简要分析这些因素。

一 规范性建议

1.职责原则

在设计接口时,必须明确接口的职责,即接口类型,接口应解决什么业务问题等

2.单一性原则

在明确接口职责的条件下,尽量做到接口单一,即一个接口只做一件事,而非两件以上。

很多非资深接口设计者,在设计接口时,总认为接口所做的事越多,越牛叉,这是非常严重的错误认识。

3.协议规范

在设计接口时,应明确接口协议,是采用HTTP协议,HTTPS协议还是FTP协议,要根据具体情况来定。

(1)FTP协议(File Transfer Protocol,简称FTP),是一套标准的文件传输协议,用于传输文件,如.txt,.csv等,一般文件传输,采用FTP协议

(2)HTTP协议,适用一般对安全性要求比较低或没要求的业务情景

(3)HTTPS=HTTP+SSL,适用于对安全性要求较高的业务情景

4.路径规则

由于api获取的是一种资源,所以网址中尽量为名词,而非动词

/api/v1.0/Product/2019

/api/v1.0/Users/2019

5.http请求方式

接口基本访问协议:get(获取),post(新增),put(修改)和delete(删除)

get /users:列出所有用户

get /users/id:根据id获取用户

post /user:新增用户

put /user/id:根据用户id更新用户

delete /user/id:根据用户id删除用户

6.域名

一般地,域名分为主域名和专有域名,主域名适合api长期不变或变化较少的业务,专有域名是解决具体的专有业务的

以百度举例:

(1)主域名:www.baidu点com

(2)产品服务类

百度文库:https://wenku.baidu点com/

百度知道:https://zhidao.baidu点com/

(3)市场活动类

百度公益:http://gongyi.baidu点com

百度logo:http://logo.baidu点com/

7.跨域考虑

在明确域名的情况下,一定要考虑接口是否跨域,以及跨域应采用的技术手段等

8.api版本

对于接口的url,应加版本号http://api.demo点com/v{d}/,如 ,其中d表示版本号,如v1.0,v2.0

例子:获取产品号为2019,版本号为v1.0的版本号的产品信息

/api/v1.0/Pruducts/2019

9.适度过滤信息

当记录数比较多时(如 SELECT * FROM TBName),应适当添加一些条件对数据进行过滤,如TOP,分页,分组,排序和WHERE条件等

下面是一些常见的参数。

?limit=100:返回100条数据

?offset=101:从第101条数据开始返回

?page=10:指第10页

per_page=100:每页100条数据

?sortby=name:排序字段

?order=desc:降序

?group=groupName:分组

?producy_type=1:筛选条件

10.返回数据格式

返回数据格式,一般包括三个字段:

(1)失败情况(状态码、错误码和错误描述)

{“status”:0,//状态码 0-表示失败,1-表示成功“error_code”:“2003”,//错误码,一般在设计时定义“error_des”:“身份验证失败”//错误描述,一般在设计时定义}

(2)成功情况(标识id,数据对象,状态码)

{“sid“:“sh20190111”,//token id“users”:{“id”:“al201901111341”,//用户id“name”:“Alan_beijing”,//用户名“addr”:“用户地址”},“status”:1//状态码 0-表示失败,1-表示成功}

11.安全性原则

接口暴露的考虑,接口并发量的考虑,接口防攻击的考虑,接口跨域的考虑等

12.可扩展性原则

在设计接口时,充分考虑接口的可扩展性。

13.定义api界限

任何api,从权限上,可归结为匿名api和非匿名api,前者不需要验证,后者需要验证

14.定义api返回码

在api设计时,要定好api返回码,如

  • 1 --授权过期

  • 404--未找到资源

  • 500--内部服务器错误

  • 600--账号被锁

二 反规范性建议

存在这样一种业务场景:某个接口需要返回多个api接口组合的结果 ,在类似的业务场景下,所设计的接口,具有一定的反规范性。

1.Request

data:[{url:'api1',type:'get',data:{...}},{url:'api2',type:'get',data:{...}},]

2.Responce

{status:0,msg:'',data:[{status:1,msg:'',data:[]},{status:1,msg:'',data:{}}]}

三 实例

假设存在这样一个一个业务:一个ERP系统,需要提供两个接口,一个是用户访问接口(需要验证),另一个是用户注册接口(不需要验证)。

根据本篇文章一,二部分的建议,我们来设计满足该业务需求的接口


本文地址:网络百科频道 https://www.eeeoo.cn/wangluo/903050.html,嗨游网一个专业手游免费下载攻略知识分享平台,本站部分内容来自网络分享,不对内容负责,如有涉及到您的权益,请联系我们删除,谢谢!


网络百科
小编:小嗨整编
相关文章相关阅读
  • 微信支付接口收费标准(微信支付接口申请条件)

    微信支付接口收费标准(微信支付接口申请条件)

    微信支付接口收费标准(微信支付接口申请条件)在通常情况下,申请微信支付的官方支付接口,费率为0.6%(即千分之六)。这也就意味着1000元的交易费用需要6元的手续费。微信支付接口申请条件需要准备以下材料吧:1、营业执照:为了证明你是一家合法...

  • PHP调用美联软通短信接口实现短信发送

    PHP调用美联软通短信接口实现短信发送

    随着人们生活水平的提高和科技的发展,短信已成为人们交流的主要方式之一,越来越多的企业开始通过短信平台来实现营销、提醒等功能。在这个过程中,短信接口的选择显得尤为重要。本文将介绍如何通过php调用美联软通短信接口实现短信发送。一、美联软通短信...

  • type-c接口是啥意思

    type-c接口是啥意思

    type-c接口是一种全新的连接标准,它可以实现多种功能,如传输数据、充电、音频输出等,type-c接口采用了最新的usb3.1标准,支持高速的数据传输和充电,最显著特点是插头两端相同,也就是说插入方式无需区分正反面,因此非常便捷。本文的...

  • output接口是什么意思

    output接口是什么意思

    output接口是指输出接口,指切换器的输出接口方式,一般为bnc插头或复合视频接口;对于矩阵切换器,因为它是将多种信号源选择两种或两种以上输出给不同的显示设备,所以矩阵切换器是多输入接口和多输出接口的。本文操作环境:windows7系统,...

  • 天气预报API接口大全

    天气预报API接口大全

     对于第三个接口,返回信息比较全面,也是以json格式提供,格式如下 {"weatherinfo":{//基本信息;"city":"北京","city_en":......

  • Mysql索引的最左前缀原则是什么

    Mysql索引的最左前缀原则是什么

    前言之所以有这个最左前缀索引归根结底是mysql的数据库结构B+树在实际问题中比如索引index(a,b,c)有三个字段,使用查询语句select*fromtablewherec='1',sql语句不会走index索引...

  • Type-C接口是什么意思

    Type-C接口是什么意思

    type-c是一种usb接口形式,是一种通用串行总线(usb)的硬件接口规范;它是usb标准化组织为了解决usb接口长期以来物理接口规范不统一,电能只能单向传输等弊端而制定的全新接口,它集充电,显示,数据传输等功能于一身。type-c接口最...

  • type-b接口是什么意思

    type-b接口是什么意思

    TypeB接口:常见于打印机以及带触摸和USB接口的显示器,日常使用频率低。         (推荐学习:phpstorm)刚才提到的Type-B虽然应用场景很少。但是他的分支之一,MicroB,却是在USB-C到来之前统...

  • 周排行
  • 月排行
  • 年排行

精彩推荐