API 返回结果设计

ztcwh 发布于 2015/09/15 10:44
阅读 3K+
收藏 3

NGINX Sprint China 2022--NGINX年度旗舰盛会,已开启免费预约!>>>

我现在开发的项目,是对外提供 API 接口,使用 JSON 数据格式。

现在对于返回数据的格式产生了疑惑,不确定用那种方式好些。

 

方案一:

不管执行成功还是执行失败,都返回同一数据格式的 JSON 数据:

 

执行成功时返回如下数据:
{
	"code": 0,
	"message": "用户添加成功",
	"data": {
		"id": 82,
		"name": "张三"
	}
}
执行失败时返回如下数据:
{
	"code": 500,
	"message": "用户添加失败,用户已存在",
	"data": null
}

 不管执行成功还失败,都会返回 code 值,0 代表成功,其它代表失败(不同的错误会返回不同的状态码)

 

方案二:

执行成功与执行失败返回不同的 JSON 格式数据:

执行成功返回如下代码:
{
	"id": 82,
	"name": "张三"
}
执行失败返回如下代码,并根据不同的错误返回不同的 HTTP 状态码(如:400,404,500)
{
	"code": 500,
	"message": "用户添加失败,用户已存在"
}

 执行失败返回的 JSON 数据格式是固定的,注意,执行失败时,会返回 HTTP 的不同的状态码。而 code 是详细的错误代码

 

此项目是 J2EE 项目,用哪种方案好些呢?优势又在哪里?

 

加载中
0
蒸发的葡萄汁
蒸发的葡萄汁
比较喜欢第一个,如果我有一个字段就刚好叫code,而我就是不想改名字怎么办?
蒸发的葡萄汁
蒸发的葡萄汁
回复 @ztcwh : 我知道啊,所以我选第一个,好像是我没有说清楚。
z
ztcwh
顶层的 code 是全局的,每次请求都会返回的状态码,用于判断是否成功的。 data 才是你要获取的数据,如果 data 里有 code 字段,不会影响到全局的 code 字段。
0
平安北京
我一般都是,code,errmsg,obj这样的
平安北京
回复 @ztcwh : 是的
z
ztcwh
按照你的意思是,你用的是第一种方案了,全部请求返回同一格式的 JSON 数据。
0
youlovebaby
youlovebaby

第一个,因为程序需要结果码的和结果信息,我们一般设置为transcode,和transmsg,统一返回字段数据利于和你对接的系统解析

z
ztcwh
回复 @刘禹星 : 我看了下阿里云的接口与谷歌的接口就是方案二,当然它返回的状态码非数字。模式是相同的
z
ztcwh
回复 @刘禹星 : 刚才的说的返回 404 HTTP 状态码只是一个例子,一般情况,业务执行出错会返回 500. 方案二可以直接知道是否执行成功了
ArrayListt
ArrayListt
回复 @ztcwh : 这个不一定,http状态200,只能说明那个接口存在,并且成功访问到了这个页面,页面访问正常和代码执行正常是2回事。
z
ztcwh
统一返回的字段,有利于判断执行是否成功或失败。 而第二种方案也是可行的哦,执行成功后,他是会返回 HTTP 200 的正常代码,当执行失败时,会返回 HTTP 404 类似的状态码,并返回统一格式的错误信息。
0
开源中国首席大弟子
z
ztcwh
哪个方案好些呢?好在哪里?
0
ArrayListt
ArrayListt
该评论暂时无法显示,详情咨询 QQ 群:点此入群
z
ztcwh
回复 @刘禹星 : HTTP 状态码只要证明请求是正确执行的就行了,正确执行返回所需要的 JSON 数据(不同格式),而执行失败返回不同的 HTTP 状态码,并返回固定格式的 JSON 错误信息(包含详细的错误代号,及错误说明)
ArrayListt
ArrayListt
回复 @ztcwh : 我明白的意思了。如果调用接口下载文件的话,那么按照你说的第二个确实能得到你说的,但是毕竟http的状态只是证明是网络,和你请求是正常的。不能保存你的业务还有代码执行正常
z
ztcwh
回复 @刘禹星 : 是对外提供下载文件的接口(用户上传的普通文件),当调用接口成功时,应该返回文件下载流,而失败时,得返回错误信息,方案二可以通过 HTTP 状态码实现,而方案一却不知道要怎样才能 实现?
ArrayListt
ArrayListt
回复 @ztcwh : 你是指把api接口返回的json当作文件下载?还是只是下载文件?如果是把json当作文件下载,那么也就只是从file读取json或者是从InputStream读取json而已。如果是下载普通的文件。那么你就需要判断http的状态,还有InputStream里面读取的内容了。
z
ztcwh
回复 @刘禹星 : 嗯,说的有理。如果在下载文件的场景中,当客户端调用接口时,正常的情况下会返回下载文件的流,不再会返回统一的 JSON 格式了,那该怎么判断该请求是否成功呢?
下一页
0
色魔张大妈
色魔张大妈
第一个无疑
z
ztcwh
方案二不好吗?
0
Steve
Steve
该评论暂时无法显示,详情咨询 QQ 群:点此入群
z
ztcwh
百度与腾讯的API是使用方案一的模式,而阿里及谷歌是使用方案的模式,现在是有点纠结,它们的优势有什么不一样。
0
AndyLam
AndyLam
第一种,第二种你确定能作为 对外提供 API 接口么?
z
ztcwh
谷歌与阿里是使用方案二的模式。
0
Fanxme
Fanxme

第一种!
看,大家的意见高度一致。

z
ztcwh
嗯,我是看了阿里及谷歌的API是使用模式二,因此产生纠结。
OSCHINA
登录后可查看更多优质内容
返回顶部
顶部