关于接口的规范和文档总结

一：接口规范

1.1 接口规范的重要性

接口，是APP端与服务器端交互密不可分的环节，接口的规范性会直接影响双方对接过程中 的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。接口应当有规范的约束。

1.2 接口规范的例子：

请看下面这个例子：

{
    "list": [
        {
            "name": "小红",
            "id": "100",
        },
        {
            "name": "小明",
            "id": "101",
        }
    ],
    "object":{
        "title":"demo",
    }
    "message": "数据加载成功",
    "status": "SUCCESS"，
    "page":"1",
    "number":"2",
}

这就是一个针对于移动端，规范性接口的事例：

list：只存储list数据，为空时也返回一个空list（"list":[]）。

object:：只存储实体类数据。

message：返回的提示消息，例如：加载成功、查询失败、登陆成功等。

statue：接口状态，例如SUCCESS-成功 ERROR-失败（静态‘变量’大写）。

page和number：其他可选性字段，例如页数，list条数等等根据项目需求的字段。

规范目的：

list：只能返回list数据，原因很简单：因为如果你的一个接口返回的是list数据，那么解析的时候移动端就要创建一个实体类，对这个list进行【List】接收。如果你的另一个接口的list字段返回了【Object】数据，那么移动端就需要再创建一个实体类进行另一种格式的接收，这无疑会让移动端不能进行代码复用，造成代码冗余，对性能影响增加。

建议：如果你的接口中返回的list、data这两个是list数据，那么以后这两个就只用来返回列表数据，obj、info这两个返回的是实体类数据，那么以后就只返回实体类数据。message和status这两个是必须要有的。其他字段都要确定好他们的规范。这样就让代码复用性增加，错误率降低，查bug便捷。才能让团队协作开发更高效便捷。

二：接口文档

后台接口人员和移动端开发人员之间的配合肯定少不了接口文档这种利器！像中大型项目可能一个接口包含的字段就有上百个，如果没有文档，仅仅靠两个人口头交流，那估计一天就能搞定几个接口配合。

接口文档有哪几种形式呢？

1.Excel、word等文档形式。（古老的方式）

2.接口管理开源网站。（高效便捷）

像用Excel、word。接口开发人员进行编写，然后发送给移动端人员。确实提高效率、但缺点也会慢慢暴露出来。优点：方便查找、接口定型后可用。缺点：更新麻烦。在开发项目阶段，这种方式是不可取的。因为在开发阶段，接口的变动将会非常的大，不可能两个程序员把接口文档copy来copy去的。所以这个时候，接口管理开源网站就应景而出。

接口管理开源网站的优点是开源、可以部署在自己的服务器上，比较安全。更新效率高，时时更新，方便团队协作开发，便捷高效。而在项目结束后，还可以导出word，形成定型的接口文档。省时省力。

在这里，接口管理工具有很多，我这里用的是eolinker。优点的话在他的主页已经详细的列了出来，这里我贴出他的主页： 点击进入eolinker

用法的话都很简单：

1.创建项目

2.邀请人员加入

3.进行编写接口

4.进行接口测试（重要）

5.形成文档

这里贴出使用教程： 点击进入eolinker使用教程

编写规范：

一个完整的接口需要由以下几部分组成

1.请求地址 例如：https://127.0.0.1:8080/xxx/xxx/xxx

2.请求方式 例如：POST、GET等

3.请求参数 例如：传 id：“1”，name：“小明”

4.返回参数 例如：{ json... } 【参考上面的接口规范】

5.返回事例 例如：{ json... }

。。。