api设计干货

现在流行云端化，前后端分离。要实现这样的设计就必须开发接口。接口开发就好比一个产品换了包装。业务逻辑上是没有任何变化的，唯一变化的就是数据接收和返回做了新的处理。接口开发需要注意以下几个基本点。

确定接口风格

到底你是采用传统的风格，还是使用restful风格。这很重要，直接关系到你的接口长相，换句话说，让对接你的人考到你的接口是什么样的。

比如微信的接口，采用的是传统的风格，url中带上token，post传输数据。

也有很多接口采用restful风格，特点就是接口地址比会变得简短许多，数据的传输方式也多样化，根据不同的目的选用不同的方式传递数据。比如get获取数据，post新增数据，put修改数据。关于restful的详情可以去网上查询。这里不做过多的阐述。

数据返回格式

这个很重要，一定要统一，设计之初就做好规划。现在主流的方式是json、xml。json好处是数据量小，结构简单已读扩展性强。xml更加丰富，除了数据描述，还可以描述属性信息。当然json通过扁平化处理也是可以做到的，毕竟是对象吗，一切皆对象。

状态码问题

一定一定一定不要把http状态码，和你的业务状态码混淆。

我见过最奇葩的设计把http状态码当做业务状态码返回，接口处理结构成功，直接放到header里状态码用200，当出现错误的时候统一用500。

这样的设计非常的糟糕，会增加你拍错的难度，同时也会让你混淆概念，分不清你的请求到底是失败还是成功。

比如你请求一个列表，遇到一个404错误码，你怀疑这个接口不存在是很正常的，但实际情况是接口找不到对应的数据，你去对接这个接口是不是很冤。打死也想不到因为这个列表没有数据吧。

建议你这样设计接口

接口根参数3个就够了code，message，data这样就可以描述你的接口了。

{
code:0,
message:'ok',
data:{...} //如果是列表就data:[....]
}

这样的返回结果一目了然。

code作为返回状态，0表示成功，如果大于0则表示有错误。错误码一定不能乱定，你可以根据接口情况分，也可以根据程序结构分。比如112001，前两位表示某个类，中间两位表示处理业务的方法，最后两位表示错误代号，比如112001表示user类->login方法->报错是缺少用户名。这样做的好处是你可以快速定位到底是哪个地方出现了问题。

message是错误说明，让对接人员更容易理解发生了什么

data存放数据，数据不管多么复杂统统在data中进行扩展。

身份验证

最为一个接口肯定不能让人随意折腾，一定要有一个机制去保护自己。所以一定有一个身份标示。以往的开发中我们用cookie或session存储。在跟服务端交互的时候浏览器会自动发送出去。但现在你是一个接口，也许来访问你的不是浏览器，可能是任何方式。

我们可以设计一下身份标示的接受方式，可以是header中接收，现在前后端分离的开发中很常见，特别是用restful风格的接口，几乎全是使用header方式传递身份标示。也可以是get方式接收，比如微信的接口，你会发现所有需要验证的接口都会要求你跟上一个token参数。

当然了，也可以配合上其他安全措施，比如数字签名，有效期等，提高安全性。

按照上面的几点，你就可以开始设计自己的接口了。这里没有写太过详细的例子，我不想限制别人的思维，总之接口的开发要根据需求而定。没有100分的标准答案，只有100%适合的方案。