疯子的自留地

当我老了,也一样写代码.不为别的,只为爱好!

API返回值设计的一些想法

白驹过隙,这篇文章已经有半年以上没有更新啦!如果是技术文章,文中的观点或代码很可能过时或失效,望自行甄别:)

背景

在用golang做一个mockhttp工具的时候模拟请求公司项目的api时发现用golang将请求结果值解析到struct并通过不同的返回值来判断是否请求成功,比如请求某接口成功时返回值:

{
   "name":"Scofield Peng",
   "age":18
}

失败时返回:

{
   "errcode":200001,
   "errmsg":"server error"
}

咋一看觉得很容易处理嘛,解析成相应的struct,看有没有值,omg,不觉得很累?很麻烦?尤其是像golang的json.UnMarshal()函数,如果接口返回错误时用正确时返回值得struct去解析,你还得判断struct是否为空,如果为空,再用错误时的struct去解析下. 太麻烦了好么!!!

解决办法

回到上面的话题,我们想要的无非就是如何优雅快速地判断请求成功与否.然后获取相应的值.知道我们想要什么了后就很好解决了,一般情况下我们用下面两种方法:

HTTP状态码

既然是HTTP请求,为什么不使用http状态码来判断是否请求成功呢? 比如200代表成功,4xx代表错误,5xx代表服务器内部错误,然后客户端进行处理时就可以根据状态码判断是否请求成功了

返回值

每次返回时body都携带一个请求结果的状态,比如上面的例子,成功时改写成这样:

{
    "success":true,
    "data":{
        "name":"Scofield Peng",
        "age":24
    }
}

失败时:

{
    "success":false,
    "data":{
        "errmsg":"server error",
        "errcode":200001
    }
}

这样一目了然,客户端也很容易进行处理了

最后

其实,写接口很容易,但是写出一个易读易用的接口就不容易了.这里分享下巨硬的一篇关于API设计的文章:

https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md

本文基于"姓名标识-非商业性-相同方式分享 4.0国际"协议创作或转载,转载原创文章请注明来源于疯子的自留地,否则请勿转载或再转载,谢谢合作:)