总阅读量:次

⭐⭐⭐ Spring Boot 项目实战 ⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》 《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》 《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》 《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》 《Java 面试题 + Java 学习指南》

摘要: 原创出处 ken.io/note/api-errorcode-or-resultcode-desgin 「ken的杂谈」欢迎转载，保留摘要，谢谢！

🙂🙂🙂关注**微信公众号：【芋道源码】**有福利：

  1. RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表
  2. RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址
  3. 您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。
  4. 新的源码解析文章实时收到通知。每周更新一篇左右。
  5. 认真的源码交流微信群。

一、前言

客户端请求 API，通常需要通过返回码来判断 API 返回的结果是否符合预期，以及该如何处理返回的内容等

相信很多同学都吃过返回码定义混乱的亏，有的 API 用返回码是 int 类型，有的是 string 类型，有的用 0 表示成功，又有的用 1 表示成功，还有用”true” 表示成功，碰上这种事情，只能说：头疼

API 返回码的设计还是要认真对待，毕竟好的返回码设计可以降低沟通成本以及程序的维护成本

二、HTTP 状态码参考

以 HTTP 状态码为例，为了更加清晰的表述和区分状态码的含义，HTTP 状态做了分段。

对于后端开发来说，我们通常见到的都是：

2XX 状态码，比如 200-> 请求成功，

5XX 状态码，比如 502-> 服务器异常，通常就是服务没正常运行，或者代码执行出错

通过状态码即可初步判断问题原因，HTTP 状态的设计思路值得借鉴。

三、参数约定

虽说是返回码设计，但是只有 code 是不行的，还要有对应的 message，让人可以看懂

参考 HTTP 状态码的思路，我们对错误码进行分段

通过这样的设计，不论是程序还是人都可以非常方便的区分 API 的返回结果，关键是统一！

四、个性化 Message

通常我们的 message 都是写给工程师看的，但是在不同的场景下，同样的错误，可能需要给用户看到不一样的错误提示。

比方说 20000-29999 表示订单创建失败：

  • 20001，订单创建失败，存在进行中的订单
  • 20002，订单创建失败，上一个订单正在排队创建中

这两种错误情况如果是给用户看，可能就只适合看到：很抱歉，您有一个正在进行中的订单，请到我的订单列表中处理。

但是对于 API 来说，返回的信息又必须是准确的，但用户看到的就必须转译，这个转译的工作调用方可以做，但是通常 API 提供者来提供个性化的 Message 能力会更好

我们可以把转译的消息配置到数据库，并缓存到 Redis 或者 API 本机

然后在请求处理结束即将返回的时候，根据 application_id+code，去匹配替换 message

这样我们就可以让手机 APP 的用户、微信小程序的用户、网页下单的企业用户看到不同的消息

五、返回信息的统一处理

有了统一的 code，我们就可以通过 Nginx 或者 APM 工具统计 API 请求 Code 数量及分布信息。

我们可以根据单位时间内 99999 的数量来做 API 的异常告警

我们可以根据 Code 的返回饼图，帮助我们发现系统、业务流程中的问题

等等

总之，好的返回码设计，可以帮助我们提高沟通效率，降低代码的维护成本

文章目录
  1. 1. 一、前言
  2. 2. 二、HTTP 状态码参考
  3. 3. 三、参数约定
  4. 4. 四、个性化 Message
  5. 5. 五、返回信息的统一处理