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

最新推荐文章于 2024-11-19 12:30:00 发布

weixin_33775582

最新推荐文章于 2024-11-19 12:30:00 发布

阅读量328

点赞数

CC 4.0 BY-SA版权

文章标签： java json 数据库

原文链接：https://my.oschina.net/foxty/blog/382344

本文探讨了RESTful API设计中常见的错误处理方式，指出直接使用HTTP状态码作为API错误码的局限性，并提出了一种新的设计方案，即在响应体中自定义错误码和错误消息，分离业务逻辑错误与HTTP协议层面的错误。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

为什么80%的码农都做不了架构师？>>>

现有状况

发现很多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状态码是400。 http://open.weibo.com/wiki/Error_code
腾讯使用自定义错误代码，错误的HTTP状态码统一是200。 http://wiki.open.qq.com/wiki/%E5%85%AC%E5%85%B1%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98%8E
阿里巴巴

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

转载于:https://my.oschina.net/foxty/blog/382344