web-services - API设计: How should distinct classes of errors be handled from an asynchronous XMLHTTP call?

Question

我有一个旧的VB6应用程序，需要对Web服务进行异步调用。该Web服务提供了一种search方法，该方法允许最终用户查询中央数据库并从应用程序内部查看结果。我正在使用MSXML2.XMLHTTP发出请求，并编写了一个SearchWebService类，该类封装了Web服务调用和代码以异步处理响应。

当前，SearchWebService向调用者引发两个事件之一:SearchCompleted和SearchFailed。如果调用成功完成，则会引发SearchCompleted事件，该事件包含搜索结果，该事件的参数中包含该结果。当检测到任何类型的故障时，就会引发SearchFailed，可能是格式不正确的URL(这是可能的，因为该URL是用户可配置的)，低级网络错误(例如“找不到主机”)到HTTP错误，例如内部服务器错误。它将错误消息字符串返回给最终用户(如果存在，则从Web服务响应正文中提取；如果响应没有正文，则从HTTP状态代码文本中提取；如果出现网络错误，则从网络错误代码中进行翻译)发生)。

由于各种安全要求，调用应用程序不会直接访问Web服务，而是通过在客户站点上运行的代理Web服务器访问它，而代理Web服务器又通过VPN访问实际的Web服务。但是，SearchWebService不知道调用应用程序正在通过代理访问Web服务:它只是被提供一个URL，并被告知发出请求。代理的存在是应用程序级别的要求。

问题是，从最终用户的 Angular 来看， call 应用程序必须能够区分低级网络错误和Web服务中的HTTP错误，并区分代理错误和远程Web服务器错误。例如，应用程序需要知道请求是否由于代理服务器关闭或代理访问的远程Web服务关闭而失败。在每种情况下，都需要向最终用户显示特定于应用程序的消息，例如“搜索Web服务代理服务器似乎已关闭。可能需要重新启动代理服务器”与“代理当前正在运行，但是远程Web服务器似乎不可用。请与(远程Web服务器负责人的姓名)联系。”我可以直接在SearchWebService类中处理此问题，但是从此类泛型类生成这些特定于应用程序的错误消息似乎是错误的(并且该类可能用于不需要代理的环境中，而错误消息不会不再有意义)。

这种区别对于故障排除非常重要:代理服务器问题通常可以由客户解决，但是远程Web服务器错误必须由第三方处理。

我在想一种解决此问题的方法是让SearchWebService类检测不同类型的错误并在每种情况下引发不同的事件。例如，除了一个SearchFailed事件外，我还可以使用NetworkError事件来处理低级网络错误(这表明访问代理服务器有问题)，而使用ConfigurationError事件来处理SearchWebService类上的无效属性(例如不正确地传递)格式的URL)，以及用于在远程Web服务器上发生的错误的ServiceError(这意味着代理可以正常工作，但远程服务器返回了错误)。

现在，我考虑了一下，还有另外一种错误情况:代理服务器可能正在正常运行，但是远程Web服务器已关闭，或者代理服务器配置错误。

使用多个错误事件对不同类别的错误进行分类的方法是否是对此问题的合理解决方案？对于最后一种情况(代理正在运行，但无法访问远程服务器)，我猜测我可能必须设置代理以返回特定的HTTP错误代码，以便客户端可以检测到这种情况(即，比500个响应)。

最初，我保留了一个SearchFailed事件，并只是向该事件添加了一个额外的errorCode参数，但这很快就变得困惑了，特别是在没有逻辑错误代码可使用的情况下(例如，如果VB6引发“真实”错误) ，即如果未注册XMLHTTP类)。

Answer 1

我认为我在Java异常中使用过的一些想法可能适用于此。

拥有大量不同的异常会变得很困惑，但是我们需要向用户提供足够的细节，因此我们不想丢失信息。

因此，我有少量的特定异常，我想它们与您的事件相对应:

InvalidRequestEvent:当用户指定错误信息

时使用

TransientErrorEvent:当可能发生重试时存在基础结构问题时使用。

我倾向于在拥有服务器群集的环境中工作，因此，如果用户请求命中了即将死机的服务器，那么如果他重新提交，他可能会得到一个好的服务器，因此从他的 Angular 来看，通常可以进行一次简单的重试。但是，有时错误是由于诸如网络或数据库之类的服务造成的，在这种情况下，用户需要诊断信息才能向服务台报告。因此，我们需要确定要放入异常(exception)的其他信息。这是(如果我理解正确的话)您的问题。

在InvalidRequestException的情况下，我们打赌会提供一些有关输入问题的信息。它可能在“括号不匹配”或“表ORDER中的未知列CUTSOMER”的行上。如果是TransientErrorException，则可能是“代理服务器已关闭”。

现在，根据您的确切要求，您可能实际上没有选择将该文本放入“异常”中，而是将一个错误号(表示层转换为特定于语言环境的字符串(英语，法语...))放入异常(exception)中。

因此，任何一个Exception都可能包含这样的内容(对不起Java语法，但我希望这个想法很清楚):

BaseException {
    String ErrorText;     // the error text itself

    // OR if you want to allow for internationaliation

    int ErrorCode;        // my application specific code, corresponds to text held by the UI
    String[] params;      // specific parameters to be substitued in the error text
                          // CUTSOMER and ORDER in my example above


    int SystemErrorCode;    // If you have an underlying error code it goes here


    String SystemErrorText; // any further diagnoistic you might need to give to 
                            // the user so that they can report the problem to the 
                            // help desk.

    // OR instead of the text (this is something I've seen done)

    int SystemErrorTag;     // A unique id for this particular error problem. 
                            // This server systems will label their message in the
                            // server logs. Users just tell the help desk this number
                            // they don't need to read detailed server error text.
}