接口设计评审规范 - 简书

标签: | 发表时间:2020-06-20 17:03 | 作者:
出处:https://www.jianshu.com

接口设计评审规范

前言

本接口设计规范,参考了restfull的部分设计理念。

以资源为中心的接口设计

资源是 Restful API的核心元素,所有的操作都是针对特定资源进行的。

任何事物,只要有被引用到的必要,它就是一个资源。资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值) 。下面是一些资源的例子:

  • 某用户的手机号码
  • 某用户的个人信息
  • 最多用户订购的GPRS套餐
  • 两个产品之间的依赖关系
  • 某用户可以办理的优惠套餐
  • 某手机号码的潜在价值

Github 可以说是这方面的典范,下面我们就拿 repository来说明。

    /users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

我们可以看到几个特性:

  • 资源分为单个文档和集合,尽量使用复数来表示资源,单个资源通过添加 id 或者 name 等来表示
  • 一个资源可以有多个不同的 URL
  • 资源可以嵌套,通过类似目录路径的方式来表示,以体现它们之间的关系

接口命名规则

接口名称及简介

接口名称应简单明了,望文知意,接口简介中,需描述清楚接口的具体业务功能。

接口的uri

原则上,接口命名规范整体采用“名词”+“动词”形式

接口返回或者操作的是单个资源对象,采用名称的单数形式命名,如:/user/add,/user/del,/user/get

接口返回或者操作的是多个资源对象,采用名称的复数形式命名,如:/users/get

接口版本

针对同一个接口,根据实际业务需求,为解决接口兼容性问题,可以对接口进行版本扩展,命名规范为“名词”+“动词”+“版本号”形式,版本号采用v1、v2、v3形式命名

例:/user/login ,/user/login/v1

接口返回值

接口返回值,将统一采用如下格式:

{
"sign": "f64b967289ac4d8cbfdc22ad30ec9d09",
"content": "{}",
"timestamp": 1561204602005,
"desc": "成功!",
"code": "000",
"accessToken": "83BAED4DAE9DEF783FDE243F4B5C"
}

sign:返回值签名验签(如果需要)

如遇第三方合作等特殊情况,根据实际情况进行设计。

其他规则

单一职责原则

一个接口只做一件事情

接口中使用连字符"-"代替下划线"_"的使用

连字符"-"一般用来分割URI中出现的字符串(单词),来提高URI的可读性,使用下划线"_"来分割字符串(单词)可能会和链接的样式冲突重叠,而影响阅读性。

接口中统一使用小写字母

根据RFC3986定义,URI是对大小写敏感的,所以为了避免歧义,我们尽量用小写字符。

同一业务概念需名称统一

例,针对金额,都统一为amount,而不是有的amount,有的money。

接口兼容性

如是对老接口进行改动,需考虑接口的兼容性,包括字段的增减、字段名称调整、字段类型的调整、字段值内容长度的调整,字段值取值范围的调整等。

拼写准确

接口一旦发布就不易修改,要保持兼容性,拼写错误也不能改了,所以要仔细检查拼写。
著名悲剧:unix 的 creat。

creat是一个函数,可以用来创建一个文件并以只写的方式打开。

参数命名

参数命名最好是定语+名词
比如 fileName, maxSize, textColor,而不是用name、size、colour

不要用生僻单词

不要用生僻单词,也不要用汉语拼音

不要自己发明缩写

除非是约定俗成已经被广泛使用的缩写,否则老老实实用完整拼写。

保持方法的对称性,有些方法一旦出现就应该是成对的,

比如 有open就要有close,有login就要有logout,这些单词基本是固定搭配的,使用者就很容易理解。

接口中不允许有is判断

例,业务需要vip用户,接口不允许设计为isVipUser,而应该设计为获取用户的会员等级接口,/user/level/get,这样保证接口的通用性和扩展性

分页接口参数

分页相关接口参数命名统一:

pageSize:每页记录条数

pageNum:当前页数

totalPageNum:总共页数

金额参数

统一以分为单位进行传递

时间参数

建议统一以时间毫秒数进行传递,避免前后端或者各种场景下日期格式不统一

相关 [接口设计 规范] 推荐:

API 接口设计规范

- - 掘金后端
这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考. 规范是死的,人是活的,希望自己定的规范,不要被打脸. url?后面的参数,存放请求接口的参数数据. 请求头,存放公共参数、requestId、token、加密字段等. Body 体,存放请求接口的参数数据. 调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用).

接口设计评审规范 - 简书

- -
本接口设计规范,参考了restfull的部分设计理念. Restful API的核心元素,所有的操作都是针对特定资源进行的. 任何事物,只要有被引用到的必要,它就是一个资源. 资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值). Github 可以说是这方面的典范,下面我们就拿. 资源分为单个文档和集合,尽量使用复数来表示资源,单个资源通过添加 id 或者 name 等来表示.

从 Feign 使用注意点到 RESTFUL 接口设计规范 - ImportNew

- -
最近项目中大量使用了Spring Cloud Feign来对接http接口,踩了不少坑,也产生了一些对RESTFUL接口设计的想法,特此一篇记录下. SpringMVC的请求参数绑定机制. 了解Feign历史的朋友会知道,Feign本身是Netflix的产品,Spring Cloud Feign是在原生Feign的基础上进行了封装,引入了大量的SpringMVC注解支持,这一方面使得其更容易被广大的Spring使用者开箱即用,但也产生了不小的混淆作用.

API接口设计之token、timestamp、sign具体实现

- - 企业架构 - ITeye博客
Token:访问令牌access token, 用于接口中, 用于标识接口调用者的身份、凭证,减少用户名和密码的传输次数. 一般情况下客户端(接口调用方)需要先向服务器端申请一个接口调用的账号,服务器会给出一个appId和一个key, key用于参数签名使用,注意key保存到客户端,需要做一些安全处理,防止泄露.

javascript 编程规范

- 红茶 - 博客园-Ruby's Louvre
为公司起草的javascript编程规范,参考了网上的许多资料,尤其是google的规范. 现在放出来,希望能抛砖引玉,大家多提宝贵意见. 本规范是针对javascript函数式编程风格与公司严重依赖于jQuery进行编码的现实制定出来. 禁止使用eval,with与caller(ecma262 v5 的use strict要求).

CSS命名规范

- - BlogJava-首页技术区
网上整理的比较好的css命名规则,为css代码的规范化做参考,增加代码的可读性. 容器: container 页头:header 内容:content/container. 页面主体:main 页尾:footer 导航:nav . 侧栏:sidebar 栏目:column 左右中:leftright center .

java编码规范

- - ITeye博客
   总结前期做的几个项目,个人认为代码的规范对团队的协作有着密切的关系. 现将一些常用的约束总结如下,以便今后参阅:. 1、所有的类、属性、方法都遵守以字母和数字为主,尽量不要参与特殊符号如下划线. 其次,除类名开头字母大写外,其他名字都要小写,然后第二个后的单词首字母大写,长度在30个字符以内.

csslint检测规范

- - ITeye博客
盒模型(box-model)/*消灭*/.     (1)当设定width 的同时,还设置了border,border-left,border-right,padding,padding-left,padding-right中的任意一个,那么必须显示设置box-sizing.     (2)当设定height的同时,还设置了border,border-top,border-bottom,padding,padding-top,padding-bottom中的任意一个,那么必须显示设置box-sizing.

oracle 编码规范

- - 操作系统 - ITeye博客
军规一:【恰当控制事务大小,commit不要过于频繁. 】 军规二:【在OLTP系统中一定要注意使用绑定变量. 】 军规三:【在OLTP系统中一定要注意复杂的多表关联不宜超过4个,关联十分复杂时,需要拆分成多个步骤,防止执行计划不正确. 】 军规四:【合理收集统计信息,固定住SQL的执行计划. 】 军规五:【尽量避免使用XA事务,在RAC环境中要避免XA事务跨节点操作.

python编程规范

- - 互联网 - ITeye博客
@FileName: @Author:[email protected] @Create date: @description:用一行文字概述模块或脚本,用句号结尾. 不影响编码的效率,不与大众习惯冲突.. 使代码的逻辑更清晰,更易于理解..   *所有的 Python 脚本文件都应在文件头标上如下标识或其兼容格式的标识.