1. 接口(Interface)开发

注解

  • 更新时间:2020-06-30
  • 整理一下日常接口开发规范和经验,主要包含基本概念、设计项目接口、接口开发原则、接口定义规范等。仅供参考!

1.1. 参考

  • 《理解RESTful架构》 作者: 阮一峰
  • 《RESTful API 设计指南》作者: 阮一峰

1.2. 几个概念

平时开发基本都会听到这些高大上的词:API、REST-API、RESTful-API,对于追求事物本质的我就集中梳理总结下。

  1. API
    • Application Programming Interface(API)应用程序(编程)接口。 (有点蒙、有点蒙……)
    • 打个比方你现在用的电脑操作系统windows就是一个接口,这个接口连接了你和电脑的硬件。类似的,API就是连接程序和程序之间的接口。
    • 现在人工智能产品越来越多,好多公司也开放了功能接口,赋能各行各业,包括个人开发这。这就是接口的价值,你无需了解底层的原理,就可以使用开放的接口进行应用的开发。
  2. REST API
    • Representational State Transfer(REST) 表现层状态转化。
    • 关键的几个概念:资源、表现层、状态转移。
      • 资源:文本、图像、音频等实体;这里涉及两个概念URI和URL,URI统一资源*标识符*,就是标识前面提到资源的,一般用名词定义;URL统一资源*定位符*,URL是一种URI,标识一个资源,并指定对其进行*操作或获取该资源*的方法,一般用动词定义。
      • 表现层:将资源按照怎样的数据结构来表示。如XML、JSON、txt等;
      • 状态转移:指的是请求接口的操作,如GET、PUT、DELETE、POST。
  3. RESTful API
    • 理解了REST,再回头看RESTful就简单多了,只要符合REST的设计风格和原则就成为RESTful架构。
    • REST不完全等价于RESTful.REST API是Web API设计的一种规范或者指导原则,而RESTful API则是这中架构设计原则或者规范的一种*具体实现*方式之一。

1.2.1. 图述概念

画两张图直观感受下这几个概念的关系。

  • API
    ../../_images/API.png
  • URI
    ../../_images/URL.png

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 - 内部服务器错误
  1. 错误码设计
    • 核心是沟通:系统与系统、人与人、人与系统间的沟通。
    • 回答问题:谁的错?错在哪?
  2. 错误码编码方式
    1. 纯数字(大多数采用,腾讯、微博、Google等)
    2. 纯英文
    3. 字母+数字(阿里巴巴推荐方式)
      • 模式:错误产生来源(表示错误来源)+四位数字编号(表示具体错误)
      • 如,A0001-9999,便于快速问题溯源和记忆。
        • A来自用户、B来自系统.(提取标准化约定好系统各个服务的字母编号)
        • 如A来用户端。A0001 用户端错误(一级)、A0100 用户注册错误 (二级) A0101 未同意隐私条约 (三级,具体细节错误)
      • 全部正常可选择错误码:00000
  3. 错误码输出路径
    1. 面向日志输出
    2. 面向外部传递
      • 服务器端传向前端
      • OpenAPI 错误码
      • 内部不同域之间
  4. 错误码组成
    1. HttpCode HTTP响应码,符合HTTP协议语义
    2. Code 错误标识
    3. Message 错误消息
    4. Advice 建议处理方式

1.4.2.2. 路由名称

  1. 这里的路由名称就是请求接口时使用的,命名规则都是 名词 ,即前面讲到的URI,也就是说定位资源。
  2. 至于为何非要用名词,本质是定位资源(弄清概念),因此名称描述的也就是资源。
  3. 我们很容易用动词,比如/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": "",  // 返回数据
}

1.5. 项目结构

1.6. 接口开发经验