为 Web API 管理 .NET 客户端库中的异常

Question

我正在为公共 Web API 构建一个 .NET 客户端库。我正在努力解决的一件事是如何最好地向库的用户指示错误情况。显然，当执行失败时，我的库应该向调用者抛出或传递异常，但是我应该使用现有的异常还是为我的库创建新的异常？如果我创建新的异常，我应该只创建一个异常还是多个？

选项 1：仅使用现有例外

在最基本的情况下，我可以例如 throw new Exception("API authentication error.");，但这是非常通用的，之后需要大量处理才能处理。我还可以使用更合适的现有异常，例如System.Security.Authentication.AuthenticationException，但是由于所有不同的命名空间，使用该库会很尴尬。在某些情况下，没有什么比InvalidOprationException 更合适的了，因此，对于使用该库处理错误的人来说，采用这种方法似乎会变得很麻烦。最简单的可能是只使用HttpException 类，因为大多数错误条件在任何情况下都是 HTTP 状态代码和消息的转换。

选项 2：为每种情况创建一个例外

我还可以为每个场景创建一个例外，但将它们全部保存在库中。所以我可以创建一个NotFoundException、AuthorizationException、TransactionsPendingException 和其他特定的异常。

选项 3：为我的客户创建一个例外

第三个选项是创建一个自定义异常MyApiException，其中包含出现的不同错误的状态代码（当然还有适当的消息）。所以我可能会throw new MyApiException(401,"Not authorized.")

在我看来，选项 3 是最容易实现且调用方法最容易处理的选项。我在 GitHub 和 Codeplex 上看到过使用这些选项的 API 客户端。是否有推荐的客户端库方法或所有方法都有效？

Answer 1

微软在 MSDN 上有一些关于此的有价值的信息：

https://msdn.microsoft.com/en-us/library/seyhszts%28v=vs.110%29.aspx

就个人而言，我倾向于做以下事情：

1. 在有意义的时候使用现有的异常

   例如当传递一个无效的键时，一个基于键的操作抛出KeyNotFoundException

2. 为需要的场景创建自定义例外

3. 避开异常以支持Either<TSuccess,TFail> 这样的结果类型
   1. 这里有一个例子：https://gist.github.com/siliconbrain/3923828
   2. 这对于迭代器块等可能引发异常的问题或需要支持 continue-on-error 时特别有用

现有异常

public int GetMyItem(string key)
{
   if (string.IsNullOrEmpty(key)) throw new ArgumentNullException("key");
   if (!_myDictionary.ContainsKey(key))
   {
      throw new KeyNotFoundException();
   }
   // Additional implementation left out
}

自定义异常

public class ArgumentNotOddException : ArgumentException
{
    public ArgumentNotOddException(string paramName)
        : base(@"The argument must be odd", paramName)
    {

    }
}

public class MyClass
{
    public void DoSomething(int x)
    {
        if (x%3 == 0) throw new ArgumentNotOddException("x");
    }
}

任一种类型

public class MyClass
{
    public IEnumerable<IEither<int, string>> Divide(int left, IEnumerable<int> right)
    {
        foreach (var num in right)
        {
            if (num == 0)
            {
                yield return Either.Right<int, string>("cannot divide by zero");
            }
            yield return Either.Left<int, string>(left/num);
        }
    }
}

您也可以只创建一个使用异常代码和消息的MyAppException，但随后您会失去表达能力，异常代码容易输入错误（除非您使用枚举），而MyAppException 不会和NotFoundException说的完全一样。

我最好的建议是认真考虑代码是否应该抛出，或者返回混合结果/错误是否合理；在 C# 中这样做有点笨拙，但它消除了未处理异常的负担，并允许您在调用代码时更加灵活。