RESTful API 是一种基于 HTTP 协议的网络应用接口风格，它形式化了与服务器交互的约定。在设计 RESTful API 的过程中，特别是在处理错误响应时，一个好的 ErrorResponse 设计能够提高 API 的可读性和易用性。
设计ErrorResponse的目标
在设计 ErrorResponse 之前，我们需要明确它的目标。ErrorResponse 应该能够：
- 传达有关错误发生的信息
- 帮助 API 的使用者针对错误响应做出正确的决策
- 使得 API 的使用者更容易诊断和解决问题
构建ErrorResponse的工程
建构 ErrorResponse 是一个工程活动，我们需要通过下面这些步骤来构建它。
确定ErrorResponse风格
ErrorResponse 的风格应该遵循整个API端点（endpoint）的编码风格。实际上，ErrorResponse 常常是由 API 的开发者维护的，在想要提高 API 的可读性和易用性的同时，也可以对开发者的工作造成肯定的影响。
遵循HTTP规范
ErrorResponse 应该遵循 HTTP 规范。例如，对于 400 错误，我们应该返回一个包含以下信息的 JSON 响应。
-
-------- -
-------------- ----
---------- ---- --------
-
-给出详细错误信息
ErrorResponse 返回的详细错误信息包括错误类别，错误标识，错误信息，以及某些情况下需要的其他错误信息。例如，在处理终端程序启动请求时，如果发现一个请求既没有设备ID也没有作业，则可以用以下 JSON 响应来返回错误信息。
-
-------- -
-------------- ----
---------- -------------- --------
--------- -
-
------- --------------------
---------- ------- -- -- ---------
--
-
------- --------------
---------- ---- -- ---------
-
-
-
-提供良好的文档说明
ErrorResponse 应该具有良好的文档说明，让使用者对整个 API 的错误响应和返回格式有更深入的了解。实际上，在设计 API 时，文档说明应该是一个不可避免的部分。下面是一个示例：
-
-------- -
-------------- ----
---------- ---- ---------
--------- -
-
------- ---------------
---------- ---- ------- ---- -- --- - ----- ---- --------
--
-
------- ----------------
---------- ---- ------ ----- -- ----------
--
-
------- ----------------
---------- ---- ----- ----- ---- -- - ----- ---- --------------
-
--
------- -
-------------- -------------
--------------- ------------
-
-
-Tips
在设计 ErrorResponse 时，我们需要注意以下几点：
- 避免对外暴露服务器端的技术实现细节
- 遵循统一的风格并保持可读性
- 在错误信息中提供有用的帮助信息和修复建议
- 捕捉错误后应该及时通知相关人员，以便进行问题修复
结论
设计与构建 ErrorResponse 需要投入较多的精力，但它有助于开发者正确地诊断和修复问题，从而提高 API 的易用性。形式化的 ErrorResponse 规范可以减少开发人员需要自己编写返回错误信息的负担，提高开发效率。整体上，好的设计和规范将帮助开发者更好地构建 API，并提高消费者对其的认可。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/6735d70e0bc820c58250c4df