在程序中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机制）。

 

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

 

六、接口调用频率的控制

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

 

七、请求接口日志的记录

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

 

八、接口文档的可读性

    接口文档的可读性非常重要，一个接口开发出来并不是真正的完成，如果别人不会使用你的接口，那么你的接口开发出来也是没有用的，好多程序员非常的不重视接口文档撰写及接口文档可读性，写出来的文档就像一本天书看着就头大。好的文档应该让人一看就知道如何调用，如何规避一些坑，简单明了等等。

 

九、接口的反映速度

接口应该以最快的速度将数据返回给请求者,要达到的目标就是快，一个页面，秒开最好，超过三秒就需要找找原因了。数据量按需分配，APP客户端需要什么数据就返回什么数据，过多的数据量影响处理速度，最重要的是影响传输效率

十、  客户端与服务端的肥瘦平衡

在移动开发中，由于客户端的修改会很费时费力，特 别是IOS应用还要经过Apple审核，另外，当前IOS开发人员、Android开发人员的人工成本普遍较高，人才紧缺，基于这两点，能在服务器端实现 的功能就不要放在客户端，毕竟服务器端程序的修改要比客户端方便、灵活、快捷的多。

十一、隐式用户与显式用户

显式用户指的是，APP程序中有用户系统，一个username、password正确的合法用户，称之为显式的用户，
通常显式用户都需要注册，登录以后能完成一些个人相关的操作。
隐式用户指的是，APP程序本身就没有用户系统，或者一个在没有登录的情况下，使用我们APP的用户。
在这种情况下，可以通过客户端生成的UDID来标识一个用户。
有了用户信息，我们就能够了解不同用户的使用习惯，而不仅仅是全体用户的一个整体的统计信息，
有了这些个体的信息之后，就可以做一些用户分群、个性化推荐之类的事情。