文档章节

RESTful实践:如何设计API的错误消息

狐狸糊涂
 狐狸糊涂
发布于 2015/03/04 09:00
字数 663
阅读 10984
收藏 29

现有状况

发现很多RESTful API的错误代码都是用HTTP的状态码(Status Code)作为API的错误代码,公司的一些产品也是如此,如下图所示: 在此输入图片描述 在此输入图片描述

这种设计基本是把错误代码依次映射到HTTP的状态码上,HTTP协议中定义的状态码基本包含下面几类:

  • 1xx Informational
  • 2xx Success
  • 3xx Redirection
  • 4xx Client Error
  • 5xx Server Error

比如对一个常见的新增用户的API,返回的Code会设计如下:

  • 201 创建成功
  • 400 请求错误(验证不通过,输入错误)
  • 401 操作未授权
  • 409 用户已存在

这种设计虽然可以覆盖大多数的情况,但对于一些业务逻辑错的话,就没有对应的HTTP状态码匹配了。比如,新增用户的时候,发现用户组人数已经达到上限了,给一个什么样的状态码呢?或者发现数据库无法访问了,又给一个什么状态码呢?

HTTP状态码是HTTP协议的一部分,应用层的API是不应该知道下层协议的细节的。假如有其他的业务错误无法对应上现有的HTTP状态码,岂不是还的自己扩展出更多的状态码?这样也会导致HTTP状态码和业务耦合,无论是服务端还是客户端。

设计方案

我的设计方案是,所有RESTful Web Service返回结果的结构都相同,不考虑改变HTTP返回的状态吗,而只是在返回结果中表明状态和错误信息,大致结构如下:

{success:true|false, data:[]|{} [, error_code:, error_message:] } 通过success字段来表明这个请求的成功或失败;如果成功,则可以读取data数据进行后续处理;如果失败,可以读取error_code和error_message进行错误的处理。这样的好处就是,既不用关心HTTP状态码,也不用对成功或失败来处理不同的JSON结构。

一些常见的设计

  • Facebook

自定义错误代码,HTTP状态码统一为200。 { "error": { "message": "(#803) Some of the aliases you requested do not exist: me1", "type": "OAuthException", "code": 803 } }

自定义错误代码,不需要关心HTTP状态码 { "error_code":"450", "error_message":"Required argument memberId : expect [type: java.lang.String]", "exception":"Required argument memberId : expect [type: java.lang.String]" }

© 著作权归作者所有

狐狸糊涂
粉丝 5
博文 7
码字总数 5276
作品 0
深圳
部门经理
私信 提问
加载中

评论(4)

狐狸糊涂
狐狸糊涂 博主

引用来自“zaobao”的评论

HTTP状态码有很多预留的,即使一个状态码后面也可以加点,如403.1、403.2,可以无限扩展,完全满足业务需求
大公司不用HTTP状态码返回错误的原因无非两个个:
1、SOA残余影响,接口服务开发的程序员的习惯已经改不回来了,restful喊了这么多年大部分实践不过是轻量的SOA
2、为了防止web服务器默认报错页面透露代码细节,4和5开头的响应都会被强制重定向,导致自定义的状态码根本无法使用
扩展是没问题,但是不是所有的服务端框架都能支持"403.1"这种格式?而且还要考虑到兼容性的问题。最主要的问题是,一个应用层的API为什么要侵入到HTTP协议层的状态码?
Rwing
Rwing

引用来自“zaobao”的评论

HTTP状态码有很多预留的,即使一个状态码后面也可以加点,如403.1、403.2,可以无限扩展,完全满足业务需求
大公司不用HTTP状态码返回错误的原因无非两个个:
1、SOA残余影响,接口服务开发的程序员的习惯已经改不回来了,restful喊了这么多年大部分实践不过是轻量的SOA
2、为了防止web服务器默认报错页面透露代码细节,4和5开头的响应都会被强制重定向,导致自定义的状态码根本无法使用
是的,第二个是主要原因,而且,在中国,你要担心4和5开头的响应被IDC拦截
zaobao
zaobao
HTTP状态码有很多预留的,即使一个状态码后面也可以加点,如403.1、403.2,可以无限扩展,完全满足业务需求
大公司不用HTTP状态码返回错误的原因无非两个个:
1、SOA残余影响,接口服务开发的程序员的习惯已经改不回来了,restful喊了这么多年大部分实践不过是轻量的SOA
2、为了防止web服务器默认报错页面透露代码细节,4和5开头的响应都会被强制重定向,导致自定义的状态码根本无法使用
雪梦科技
雪梦科技
同意
RESTful - 收藏集 - 掘金

远程接口设计经验分享 - 后端 - 掘金 写在前边 分布式架构是互联网应用的基础架构,很多新人入职以来就开始负责编写和调用阿里的各种远程接口。但如同结婚一般,用对一个正确的接口就如同嫁一...

掘金官方
2017/05/26
0
0
RESTful API

RESTful API 一、RESTful简介 1.Restful是什么 本质:一种软件架构风格 核心:面向资源 解决的问题: ①降低开发的复杂性 ②提高系统的可伸缩性 2.设计概念和准则 ①网络上所有事物都可以被抽...

JS_HCX
2018/01/08
0
0
如何编写相对标准的后端项目(二)设计 Restful API

本文主要介绍 Restful 风格,如何设计 HTTP Restful API,以及在设计过程中的一点经验之谈。文章有点枯燥,敬请谅解。最后建议在设计 HTTP API 时,遵循 Restful API 风格。 理解 Restful St...

koala bear
2018/01/18
0
0
RESTful 接口设计开发规范

API 接口可以说是软件开发人员的用户界面,API 设计也是系统架构的重要环节。尤其对复杂和分布式系统而言,其设计的好坏,直接影响着整个系统的设计,实现和演进。一套糟糕的 API 设计也会严...

garyond
2018/07/23
0
0
[Medium翻译]RESTful API权威设计指南-设计更好的API

本文为授权译文。希望查看原文的同学请戳链接:https://hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf 对于我们开发者来说,设计与实现REST API似乎已经成为了我们的日...

螺丝王
2018/07/28
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Python 开发植物大战僵尸游戏

作者:楷楷 链接:https://segmentfault.com/a/1190000019418065 开发思路 完整项目地址: https://github.com/371854496/pygame 更多好玩有趣的python,尽在公众号「Python专栏」,后台回复...

上海小胖
50分钟前
5
0
JVM优化之逃逸分析与分配消除

要了解逃逸分析背后的基本原理,我们先来看下这段有问题的C代码——当然这个是没法用Java来写的: 这段C代码在栈上创建了一个int类型的变量,然后把它的指针作为函数的返回值返回了。这样做是...

onedotdot
59分钟前
3
0
最简单的获取相机拍照的图片

  import android.content.Intent;import android.graphics.Bitmap;import android.os.Bundle;import android.os.Environment;import android.provider.MediaStore;import andr......

MrLins
今天
6
0
说好不哭!数据可视化深度干货,前端开发下一个涨薪点在这里~

随着互联网在各行各业的影响不断深入,数据规模越来越大,各企业也越来越重视数据的价值。作为一家专业的数据智能公司,个推从消息推送服务起家,经过多年的持续耕耘,积累沉淀了海量数据,在...

个推
今天
12
0
第三方支付-返回与回调注意事项

不管是支付宝,微信,还是其它第三方支付,第四方支付,支付机构服务商只要涉及到钱的交易都要进行如下校验,全部成功了才视为成功订单 1.http请求是否成功 2.校验商户号 3.校验订单号及状态...

Shingfi
今天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部