|
|
@@ -1,12 +1,14 @@
|
|
|
## 网络API接口设计
|
|
|
|
|
|
-目前许多的Web应用和移动应用都使用了前后端分离的开发模式,前后端分离简单的说就是前端或移动端通过网络API接口和后台进行交互。API是应用程序的编程接口的缩写;网络API通常指的是基于一个URL(统一资源定位符)可以访问到的资源,也就是说通过这个URL我们可以让服务器对某个资源进行操作并返回操作的结果,复杂的业务逻辑被隐藏在简单的API接口中。URL的通用格式如下所示:
|
|
|
+目前许多的Web应用和移动应用都使用了前后端分离的开发模式,前后端分离简单的说就是前端或移动端通过网络API接口和后台进行交互,获得接口中提供的数据并负责用户界面的渲染。API是应用程序的编程接口的缩写,网络API通常指的是基于一个URL(统一资源定位符)可以访问到的资源,也就是说通过这个URL我们就可以请求服务器对某个资源进行操作并返回操作的结果。大家可以想想,网络API接口不也是一种封装吗,简单的说就是将复杂的业务逻辑隐藏在简单的API接口中。
|
|
|
+
|
|
|
+URL的通用格式如下所示:
|
|
|
|
|
|
```
|
|
|
协议://用户名:口令@主机:端口/路径1/.../路径N/资源名
|
|
|
```
|
|
|
|
|
|
-> 说明:URL中的用户名(有可能不需要提供用户名)、口令(有可能不需要提供口令)、端口(有可能使用默认端口)、路径(资源有可能直接位于根路径`/`下)并不是必需的部分,可以根据需要进行设置。
|
|
|
+> **说明**:URL中的用户名(有可能不需要提供用户名)、口令(有可能不需要提供口令)、端口(有可能使用默认端口)、路径(资源有可能直接位于根路径`/`下)并不是必需的部分,可以根据需要进行设置。
|
|
|
|
|
|
网络API通常基于HTTP或HTTPS进行访问,基于HTTP/HTTPS最大的好处就在于访问起来非常的简单方便,而且可以跨语言、跨应用进行访问和互操作。
|
|
|
|
|
|
@@ -14,7 +16,7 @@
|
|
|
|
|
|
#### 关键问题
|
|
|
|
|
|
-为移动端或者PC端设计网络API接口一个非常重要的原则是:根据业务实体而不是用户界面或操作来设计。如果API接口的设计是根据用户的操作或者界面上的功能设置来设计,随着需求的变更,用户界面也会进行调整,需要的数据也在发生变化,那么后端开发者就要不停的调整API,或者给一个API设计出多个版本,这些都会使项目的开发和维护成本增加。
|
|
|
+为移动端或者PC端设计网络API接口一个非常重要的原则是:**根据业务实体而不是用户界面或操作来设计API接口**。如果API接口的设计是根据用户的操作或者界面上的功能设置来设计,随着需求的变更,用户界面也会进行调整,需要的数据也在发生变化,那么后端开发者就要不停的调整API,或者给一个API设计出多个版本,这些都会使项目的开发和维护成本增加。我们可以将业务实体理解为服务器提供的资源,而URL就是资源的定位符(标识符),这种方式是最为简单自然的。对于相对复杂的用户操作,我们可以提供一个“门面”(设计模式中的“门面模式”),通过该“门面”把多个接口的功能组装起来即可。
|
|
|
|
|
|
下面是某个网站开放API的接口,可以看出API的设计是围绕业务实体来进行的,而且都做到了“见名知意”。
|
|
|
|
|
|
@@ -28,9 +30,9 @@
|
|
|
| comments/destroy | 删除一条评论 |
|
|
|
| comments/reply | 回复一条评论 |
|
|
|
|
|
|
-需要说明的是,上面的API接口并不是REST风格的。REST是一种网络应用架构风格,被认为最适合分布式的网络应用。关于REST的知识,可以阅读阮一峰老师的[《理解RESTful架构》](http://www.ruanyifeng.com/blog/2011/09/restful.html)以及[《RESTful API设计指南》](http://www.ruanyifeng.com/blog/2014/05/restful_api.html),当然这两篇文章大家也要批判的阅读,因为上面阐述的观点并不完全正确,有些内容甚至是自相矛盾的。
|
|
|
+需要说明的是,**上面的API接口并不是REST风格的**。REST是一种网络应用架构风格,被认为最适合分布式的网络应用。关于REST的知识,可以阅读阮一峰的[《理解RESTful架构》](http://www.ruanyifeng.com/blog/2011/09/restful.html)以及[《RESTful API设计指南》](http://www.ruanyifeng.com/blog/2014/05/restful_api.html),当然这两篇文章大家也要批判的阅读,因为上面阐述的观点并不完全正确,有些内容甚至是自相矛盾的。
|
|
|
|
|
|
-API接口返回的数据通常都是**JSON**或**XML**格式,我们这里不会讲述XML的知识,因为这种格式几乎已经被淘汰掉了。对于JSON格式的数据,我们需要做到不要返回null这的值,因为这样的值一旦处置失当,会给前端和移动端开发带来不必要的麻烦(因为开发者有可能会使用强类型语言)。要解决这个问题可以从源头入手,在设计数据库的时候,尽量给每个字段都加上“not null”约束或者设置合理的默认值约束。
|
|
|
+API接口返回的数据通常都是**JSON**或**XML**格式,XML这种数据格式目前基本已经被弃用了。对于JSON格式的数据,我们需要做到不要返回null这的值,因为这样的值一旦处置失当,会给前端和移动端开发带来不必要的麻烦(因为开发者有可能会使用强类型语言)。要解决这个问题可以从源头入手,在设计数据库的时候,尽量给每个字段都加上“not null”约束或者设置合理的默认值约束。
|
|
|
|
|
|
#### 其他问题
|
|
|
|
|
|
@@ -42,9 +44,7 @@ API接口返回的数据通常都是**JSON**或**XML**格式,我们这里不
|
|
|
|
|
|
下面以设计评论接口为例,简单说明接口文档应该如何撰写。
|
|
|
|
|
|
-#### 评论接口
|
|
|
-
|
|
|
-全局返回状态码
|
|
|
+首先,我们可以定义全局返回状态码。
|
|
|
|
|
|
| 返回码 | 返回信息 | 说明 |
|
|
|
| ------ | ------------ | ---------------------------------- |
|
|
|
@@ -54,7 +54,9 @@ API接口返回的数据通常都是**JSON**或**XML**格式,我们这里不
|
|
|
| 10003 | 评论已被删除 | 查看评论时评论因不和谐因素已被删除 |
|
|
|
| 10004 | …… | …… |
|
|
|
|
|
|
-1. **GET** `/articles/{article-id}/comments/`
|
|
|
+1. 获取文章评论。
|
|
|
+
|
|
|
+ URL:**GET** `/articles/{article-id}/comments/`
|
|
|
|
|
|
开发者:王大锤
|
|
|
|
|
|
@@ -103,7 +105,9 @@ API接口返回的数据通常都是**JSON**或**XML**格式,我们这里不
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-2. **POST** `/articles/{article-id}/comments`
|
|
|
+2. 新增文章评论。
|
|
|
+
|
|
|
+ **POST** `/articles/{article-id}/comments`
|
|
|
|
|
|
开发者:王大锤
|
|
|
|
|
|
@@ -140,5 +144,5 @@ API接口返回的数据通常都是**JSON**或**XML**格式,我们这里不
|
|
|
|
|
|
|
|
|
|
|
|
-> 提示:如果没有接口文档撰写经验,可以使用在线接口文档编辑平台RAP2或YAPI来进行接口文档撰写,也可以参考我的[《FTX(租房项目)接口文档》](../番外篇/FTX(租房项目)接口文档.md)来了解如何撰写接口文档。
|
|
|
+> **提示**:如果没有接口文档撰写经验,可以使用在线接口文档编辑平台[RAP2](<http://rap2.taobao.org/>)或[YAPI](<http://yapi.demo.qunar.com/>)来进行接口文档撰写。
|
|
|
|