Api接口设计注意事项

设计接口是一件容易的事，也是件困难的事。设计接口每个人都会，每个人都能设计，也由此产生了各种各样的理念的接口。工作这么多年，我也很有感悟。很多人会说，设计接口多么简单，只要命名好，然后联调通了，上线可以调用就行了。特别是非互联网行业的人，这里没有歧视的意思。因为互联网行业和传统行业太多不一致性决定了这种思想的产生。

接口是项目里面的最小粒度的单元，接口设计需要注意点很多，需要的考虑方方面面，很多人也不重视，而且设计接口需要的技术栈也需要很多，能充分考察到技术人的知识的广度以及深度。下面介绍的是在工作中的一些总结，希望能与诸位共同交流，探讨。

一、接口版本化

    生产环境中，如果没有版本控制的程序变更会导致调用接口的相关方频繁的跟着变更，假设相关方没有及时的跟着变更，那么系统就会报错，从而影响到用户的使用及体验，使其对整个系统的运营都是不利的，接口对接的难度也会不断的加大。

    如果接口能够有版本的控制，则升级系统的主动权就掌握在相关方，这样当有新版本的程序发布时旧版本的业务逻辑不会受到影响，从用户感知上也受到的影响就比较小，相关方也可以根据自身的条件是否要升级版本。

二、接口面向的应用场景

    在对接口进行设计时，我们还要考虑接口是面向web前端开发还是手机app开发，或者服务端开发。不同的应用场景接口总体规划是不同的（例如：当我们的接口是提供给web前端或APP端使用时，接口安全验证我们可以采用jwt、oauth2.0等，如果我们的接口是提供给后端服务使用时，那么我可以采用token机制）。

三、请求参数的规范性及处理的统一性

    请求参数的规范性意思就是说，接口要以什么样的方式来接收参数。是统一使用json的方式接收呢还是xml或者form表单方式接收。

    在开发接口应该统一在一个地方进行对参数的接收、校验等操作。为了保证参数的完整性，我们可以考虑新增签名验证等处理。

四、返回数据类型、返回码及信息提示的规范性

返回给客户端的数据类型应该要统一化（例如：我们统一以json的形式进行返回，或者是统一以xml的形式返回）。

不同的接口设计模式返回码也会不同，如果使用现在非常火也比较流行的restfull风格那么就应该要准许restfull风格的返回码规定。如果是统一采用自定返回码的话在设计返回码时，应该要学会针对不同的业务处理模块对返回码进行分段处理（例如：系统基础管理我们使用10000-10050，用户管理则就应该要从10051到10100，……），针对不同业务模块我们要预留足够的返回码，因为后期针对该模块的开发可能还会有其它业务的扩展或者调整等问题。

返回码分段处理的一个好处就是方便调用接口的相关方能够很快的定位到错误是属于哪一个部分，同时也方便接口开发人员定位接口错误在哪个地方。

除了返回码，我们对接口返回的错误提示信息和接口调用成功的提示信息都应该明确，提示到点上。当然有些错误信息可能是自身API的bug或者服务器的问题等因素，这样的话我们就应该要转化一下提示不能把API自身问题暴露给接口调用相关方，这样会导致接口的安全性等问题。

五、接口安全验证及权限的控制

    接口并不是每个操作者都能请求访问的，所以我们要为接口提供一个安全验证，就像用户登录系统一样，没有在我们系统注册的合法用户我们是不允许请求访问的。那么我们要如何对接口进行安全验证呢？其实针对不同的应用场景我们的接口安全验证也不一样（例如：当我们的接口是提供给web前端或APP端使用时，接口安全验证我们可以采用jwt、oauth2.0等，如果我们的接口是提供给后端服务使用时，那么我可以采用token机制）。

    权限的控制是指针对不同的用户群体，我们要分配不同的权限（例如：超级管理员可以操作所有接口，普通用户只允许操作部分接口），这里除了针对用户群体我们可以针对不同的调用接口的相关方（这里的相关方是指调用接口的应用）进行权限控制。

六、接口调用频率的控制

    对接口的调用频率进行控制从另一方面来讲也是为了接口的安全性及接口的可维护性，当然这里是否要对接口访问次数进行控制还是取决于接口针对不同的应用场景，有些接口的设计是不需要限制调用频率的，而有些接口则对接口调用是要进行严格控制的（例如：大家熟知的微信公众号的开发就是对接口的调用频率进行限制，并且针对不同的场景及用户群体限制的频率也不一样）。

七、请求接口日志的记录

    我们应该要为接口请求做一下日志的记录，这样我们后期维护接口时则会大大降低维护成本。而且还可以针对日志进行相关的统计处理。

八、接口文档的可读性

    接口文档的可读性非常重要，一个接口开发出来并不是真正的完成，如果别人不会使用你的接口，那么你的接口开发出来也是没有用的，好多程序员非常的不重视接口文档撰写及接口文档可读性，写出来的文档就像一本天书看着就头大。好的文档应该让人一看就知道如何调用，如何规避一些坑，简单明了等等。这里我介绍两个比较好的接口管理可视化工具给大家参考一下，swagger和阿里巴巴的rap。有空可以去搜索一下。