1. 接口(Interface)开发¶
注解
- 更新时间:2020-06-30
- 整理一下日常接口开发规范和经验,主要包含基本概念、设计项目接口、接口开发原则、接口定义规范等。仅供参考!
1.1. 参考¶
- 《理解RESTful架构》 作者: 阮一峰
- 《RESTful API 设计指南》作者: 阮一峰
1.2. 几个概念¶
平时开发基本都会听到这些高大上的词:API、REST-API、RESTful-API,对于追求事物本质的我就集中梳理总结下。
- API
- Application Programming Interface(API)应用程序(编程)接口。 (有点蒙、有点蒙……)
- 打个比方你现在用的电脑操作系统windows就是一个接口,这个接口连接了你和电脑的硬件。类似的,API就是连接程序和程序之间的接口。
- 现在人工智能产品越来越多,好多公司也开放了功能接口,赋能各行各业,包括个人开发这。这就是接口的价值,你无需了解底层的原理,就可以使用开放的接口进行应用的开发。
- REST API
- Representational State Transfer(REST) 表现层状态转化。
- 关键的几个概念:资源、表现层、状态转移。
- 资源:文本、图像、音频等实体;这里涉及两个概念URI和URL,URI统一资源*标识符*,就是标识前面提到资源的,一般用名词定义;URL统一资源*定位符*,URL是一种URI,标识一个资源,并指定对其进行*操作或获取该资源*的方法,一般用动词定义。
- 表现层:将资源按照怎样的数据结构来表示。如XML、JSON、txt等;
- 状态转移:指的是请求接口的操作,如GET、PUT、DELETE、POST。
- RESTful API
- 理解了REST,再回头看RESTful就简单多了,只要符合REST的设计风格和原则就成为RESTful架构。
- REST不完全等价于RESTful.REST API是Web API设计的一种规范或者指导原则,而RESTful API则是这中架构设计原则或者规范的一种*具体实现*方式之一。
1.3. 接口的好处¶
- 提高开发效率。前后端分类,通过约定来解藕前后端的开发。
- 便于维护。
- 便于功能扩展。
1.4. 接口定义原则及规范¶
接口的好处,离不开清晰的原则和规范。只有接口设计的合理才能更好的满足系统的使用和管理。
注解
本文就采用Backend For Frontend(BFF层),称为前端的后台,前端(网页、手机、平板等)的业务操作基于接口完成。
1.4.1. 原则¶
1.4.2. 常用规范(参考)¶
1.4.2.1. 基本状态码¶
注解
一般根据实际业务前后端约定码就行,大多数是一个区间,如:1000-1999,2000-2999等
- 200 - 请求成功
- 301 - 资源(网页等)被永久转移到其它URL
- 404 - 请求的资源(网页等)不存在
- 500 - 内部服务器错误
- 错误码设计
- 核心是沟通:系统与系统、人与人、人与系统间的沟通。
- 回答问题:谁的错?错在哪?
- 错误码编码方式
- 纯数字(大多数采用,腾讯、微博、Google等)
- 纯英文
- 字母+数字(阿里巴巴推荐方式)
- 模式:错误产生来源(表示错误来源)+四位数字编号(表示具体错误)
- 如,A0001-9999,便于快速问题溯源和记忆。
- A来自用户、B来自系统.(提取标准化约定好系统各个服务的字母编号)
- 如A来用户端。A0001 用户端错误(一级)、A0100 用户注册错误 (二级) A0101 未同意隐私条约 (三级,具体细节错误)
- 全部正常可选择错误码:00000
- 错误码输出路径
- 面向日志输出
- 面向外部传递
- 服务器端传向前端
- OpenAPI 错误码
- 内部不同域之间
- 错误码组成
- HttpCode HTTP响应码,符合HTTP协议语义
- Code 错误标识
- Message 错误消息
- Advice 建议处理方式
1.4.2.2. 路由名称¶
- 这里的路由名称就是请求接口时使用的,命名规则都是 名词 ,即前面讲到的URI,也就是说定位资源。
- 至于为何非要用名词,本质是定位资源(弄清概念),因此名称描述的也就是资源。
- 我们很容易用动词,比如/get_results、/del_item等等,其实这是多此一举的,因为RESTful方法名(GET、HEAD、POST、PUT、DELETE、OPTIONS、TRACE、PATCH)已经表达了对资源进行的动作了,所以接口名应定义为:/resluts、/item就行了(即资源的名称,如学生、肥皂、汽车等)。
1.4.2.3. 数据格式¶
小技巧
考虑到接口的可维护性和可扩展性,返回的msg、code最好集中定义,一一对应约定好。
{
"code": 0, // 0 位正常,其他数字则为异常,这里不须强制使用http的状态码
"msg": "" // 附加信息
"data": "", // 返回数据
}