集成中的错误处理
错误处理对于构建成功的产品集成至关重要。事情并不总是能正常运行,您的目标应该是在这种情况发生时尽可能地减少客户的挫败感。本风格指南旨在使您(开发人员)能够以一种自我服务的方式编写更好的代码,更有效地处理错误,最终减少用户联系技术支持的需要。
免责声明
本指南是围绕使用Requests库构建的,尽管这些概念与代码无关。
信任并验证第三方API文档。
错误消息
所有面向用户的文本应遵循正确的英语语法/拼写/语法,除非另有说明,包括错误消息。用与你要构建插件的产品一致的语言编写错误消息。
如果可能,引导用户找到错误的潜在解决方案,并在他们解决问题后提醒他们测试集成
下面是两个错误消息示例——一个是好的,一个是坏的:
好:错误:到Acme服务的身份验证失败。请验证插件连接中配置的API密钥是否输入正确,以及Acme Service API密钥是否有效,然后重试。如果问题仍然存在,请联系技术支持。
缺点:无法验证痤疮
“good”消息很好,因为它详细说明了错误(身份验证),将身份验证凭据标识为问题,提供了解决问题的补救性自助服务步骤,并指示用户在需要时联系支持部门。
“不好的”信息之所以不好,是因为它不使用正确的英语,也不提供任何其他信息。这包括没有解释可能导致故障的原因,没有提供补救措施,没有指导用户采取适当的行动。这可能会导致未报告的错误和浪费时间。
的代码
这是对一些代码的总体概述,这些代码有效地处理错误,同时向用户显示有用的、人类可读的消息。
action.py
python
1
进口json
2
从komand.异常进口PluginException
3.
4
def运行(自我,参数个数={}):
5
business_object_id=参数个数[“business_object_id”]
6
public_id=参数个数[“public_id”]
7
8
url=自我.连接.base_url()+“/ api / V1 / getbusinessobject / busobid / {busobid} / publicid / {publicid}”.格式(
9
busobid=business_object_id,
10
publicid=public_id
11
)
12
13
回答=自我.连接.会话().得到(url)
14
如果回答.status_code不在范围(200,299):
15
提高PluginException(
16
导致="从Cherwell收到HTTP %d状态码。请确认您的Cherwell服务器状态,然后再试一次。”,
17
援助=“如果问题持续存在,请联系技术支持。”,
18
数据=f”{回答.status_code},{回答.文本}"
19
)
20.
21
试一试:
22
response_data=回答.json()
23
除了json.译码器.JSONDecodeError:
24
提高PluginException(
25
导致="从查威尔那里收到了意想不到的回复",
26
援助=(非json或没有收到响应)。,
27
数据=回答.文本
28
)
29
30.
返回{“成功”:真正的,“raw_response”:response_data}
现在让我们把这个例子拆开来研究一下。
第1节-状态码检查
python
1
如果回答.status_code不在范围(200,299):
2
提高PluginException(
3.
导致="从Cherwell收到HTTP %d状态码。请确认您的Cherwell服务器状态,然后再试一次。”,
4
援助=“如果问题持续存在,请联系技术支持。”,
5
数据=f”{回答.status_code}{回答.文本}"
6
)
本节处理响应的HTTP状态代码。可以找到HTTP状态代码的完整列表及其相应的标题和描述在这里.
并不是所有的API都使用适当的HTTP状态代码,所以一定要在任何通用列表上使用API文档状态代码。
此代码使用如果语句来验证状态码不在200-299范围内。200代表“OK”。如果状态代码不在这个范围内,那么我们将通过引发a的方式停止集成的执行PluginException并向用户解释问题所在。
第2部分-载荷验证
python
1
进口json
2
试一试:
3.
response_data=回答.json()
4
除了json.译码器.JSONDecodeError:
5
提高PluginException(
6
预设=PluginException.预设.INVALID_JSON,
7
数据=回答.文本
8
)
本节标记从响应获取JSON有效负载的尝试。如果有效负载不是JSON,或者它根本不存在,那么这个调用将失败并抛出JSONDecodeError。当用户查看日志时,如果不处理此异常,则该异常最终将毫无用处,因为它不包含任何关于响应的信息。
您可以通过通知用户收到的响应是意外的格式来处理这个问题,然后打印响应的文本。这将产生来自服务器的响应,该响应将向用户提供有关问题的更多信息,以及他们如何进行纠正。
在可能的情况下,引导用户查阅可能有助于解决问题的产品文档。下面是一个例子,引导用户在文档中提供一个自定义JSON对象作为插件操作的输入:
python
1
提高PluginException(
2
导致=“Okta:创建用户意外失败。”,
3.
援助=“确保提供的任何对象,如概要文件或凭据,都与Okta模式匹配。”
4
“更多详情,请参见https://developer.okta.com/docs/api/resources/users#request-parameters”
5
)
提高异常
作为开发人员,在处理错误时可以采取两种常规操作。
当不需要停止插件代码时,可以记录错误,但继续执行。你可以用self.logger.error(…)向用户提供错误消息。
一个PluginException将暂停插件代码执行。你可以用抛出PluginException(cause="reason", assistance="helpful message")然后向用户提供原因和帮助消息(如上一节所述),以便进行可能的补救。当代码中出现致命或错误场景时,您可以使用此方法——例如接收HTTP 500错误、无效响应、无效身份验证等。
潜在的错误
这个列表并不包含所有内容,所以请注意您正在使用的文档。考虑到这一点,遵循这个通用列表并根据具体集成进行必要的调整,应该会让你(和用户)有一个很好的开始。
- 确保用户输入正确。必要时验证用户输入。
- 检查响应上的HTTP状态码。使用API文档并处理它们列出的所有场景。根据文档定制错误消息。如果没有相关文档,请检查最常见的文档。注意:有些api在发生错误时在响应中提供错误消息。如果是这种情况,请将错误消息返回给用户。
- 检查响应负载类型。例如,如果您期望一个JSON响应,但您得到的是纯文本或甚至是XML响应,您的插件代码会崩溃吗?如果是-处理它。Try/except子句在这个场景中非常有效。如果可能,向用户提供完整的响应文本。
- 检查所需的数据是否存在。响应中是否包含了我们需要的所有数据?如果不是,我们是否可以继续执行,或者这是一个致命错误,我们需要引发PluginException?使用你的判断和可用的文件在这里。
约定
如果可能的话,将这些标准化。
例子
JSONDecode
python
1
进口json
2
从komand.异常进口PluginException
3.
...
4
试一试:
5
response_data=回答.json()
6
除了json.译码器.JSONDecodeError:
7
提高PluginException(
8
预设=PluginException.预设.INVALID_JSON,
9
数据=回答.文本
10
)
连接异常
提供与插件连接相关的错误消息ConnectionTestException接口。
该接口提供一个预先设置的错误消息列表。每一个预设都与特定的原因和帮助信息相关联。这个列表会经常变化,所以代码是最好的地方最新的列表.
列表中的一些预设错误消息可能包括:
1
API_KEY = " API_KEY”
2
未经授权的=“未经授权的”
3.
RATE_LIMIT = " RATE_LIMIT "
4
USERNAME_PASSWORD = " USERNAME_PASSWORD "
5
NOT_FOUND = " NOT_FOUND "
6
SERVER_ERROR = " SERVER_ERROR "
7
SERVICE_UNAVAILABLE = " SERVICE_UNAVAILABLE "
8
INVALID_JSON = " INVALID_JSON "
9
未知=“未知”
10
BASE64_ENCODE = " BASE64_ENCODE "
11
BASE64_DECODE = " BASE64_DECODE "
一个使用预设的例子USERNAME_PASSWORD:
python
1
从komand.异常进口ConnectionTestException
2
...
3.
回答=请求.得到(自我.url,身份验证={“用户名”:“废话”,“密码”:“废话”)
4
5
# https://developer.atlassian.com/cloud/jira/platform/rest/v2/?utm_source=%2Fcloud%2Fjira%2Fplatform%2Frest%2F&utm_medium=302错误响应
6
如果回答.status_code==401:
7
提高ConnectionTestException(预设=ConnectionTestException.预设.USERNAME_PASSWORD)
当异常被引发时,这个例子将返回以下消息:
komand.exceptions. loggeexception:连接测试失败!提供的用户名或密码无效。验证您的用户名和密码是否正确。
它还包括通过提供导致,援助,数据参数。
python
1
从komand.异常进口ConnectionTestException
2
...
3.
回答=请求.得到(自我.url,身份验证={“用户名”:“废话”,“密码”:“废话”)
4
如果回答.status_code==404:
5
提高ConnectionTestException(
6
导致="无法到达吉拉实例:%s。"%自我.url,
7
援助=验证Jira服务器在插件连接中配置的URL是正确的。
8
)
当异常被引发时,这个例子将返回以下消息:
1
komand.exceptions. loggeexception:连接测试失败!
2
3.
无法到达Jira实例:https://example.jira.com。验证Jira服务器在你的插件连接中配置的URL是正确的。
另一个使用可选选项的例子数据附加参数响应为:< data >在最后。当API提供了有用的消息,或者出现了错误,您希望向用户提供意料之外的响应时,使用这种方法是很好的。
python
1
进口json
2
从komand.异常进口ConnectionTestException
3.
...
4
试一试:
5
response_data=回答.json()
6
除了json.译码器.JSONDecodeError:
7
提高PluginException(
8
预设=PluginException.预设.INVALID_JSON,
9
数据=回答.文本
10
)
当异常被引发时,这个例子将返回以下消息:
1
komand.exceptions.LoggedException:插件执行时出错!
2
3.
收到来自服务器的意外响应。(非json或没有收到响应)。响应为:{"asdf": asdf}
插件的例外
您可以在Connection测试方法之外的ConnectionTestExceptions中使用相同的机制PluginException.它也支持相同的预置。
python
1
从komand.异常进口PluginException
2
味精=“用户在给定的时间内发送了太多请求:你已经超过了这项服务的速率限制。”
3.
...
4
提高PluginException(导致='从AbuseIPDB收到错误响应。',援助=“可能请求太多了。”,数据=味精)
当异常被引发时,这个例子将返回以下消息:
1
pluginexception:插件执行时发生错误!
2
3.
收到来自AbuseIPDB的错误响应。可能有太多的请求。用户在给定的时间内发送了太多的请求:您已经超过了该服务的速率限制。