Java SDK for REST API 服务的错​​误处理

我们正在构建一个 Java SDK，以简化对提供 REST API 的服务之一的访问。该SDK供第三方开发者使用。我正在努力寻找在 SDK 中实现错误处理的最佳模式，以更适合 Java 语言。

假设我们有其余端点：GET /photos/{photoId}。 这可能会返回以下 HTTP 状态代码：

• 401：用户未经过身份验证
• 403：用户无权访问此照片
• 404：没有该 ID 的照片

该服务看起来像这样：

interface RestService {   
    public Photo getPhoto(String photoID);
} 

在上面的代码中，我还没有解决错误处理问题。我显然想为 sdk 的客户端提供一种方法来了解发生了哪个错误，并有可能从中恢复。 Java 中的错误处理是使用异常来完成的，所以让我们继续吧。但是，使用异常执行此操作的最佳方法是什么？

1. 有一个异常，其中包含有关错误的信息。

public Photo getPhoto(String photoID) throws RestServiceException;

public class RestServiceException extends Exception {
    int statusCode;

    ...
}

sdk 的客户端可以执行如下操作：

try {
    Photo photo = getPhoto("photo1");
}
catch(RestServiceException e) {
    swtich(e.getStatusCode()) {
        case 401 : handleUnauthenticated(); break;
        case 403 : handleUnauthorized(); break;
        case 404 : handleNotFound(); break;
    }
}

但是我不太喜欢这个解决方案，主要有两个原因：

• 通过查看方法的签名，开发人员不知道他可能需要处理哪种错误情况。
• 开发人员需要直接处理 HTTP 状态代码并了解它们在此方法的上下文中的含义（显然，如果正确使用它们，很多时候其含义是已知的，但情况可能并非总是如此）。

2. 有错误的类层次结构

方法签名保持不变：

public Photo getPhoto(String photoID) throws RestServiceException;

但现在我们为每种错误类型创建异常：

public class UnauthenticatedException extends RestServiceException;
public class UnauthorizedException extends RestServiceException;
public class NotFoundException extends RestServiceException;

现在 SDK 的客户端可以执行如下操作：

try {
    Photo photo = getPhoto("photo1");
}
catch(UnauthenticatedException e) {
    handleUnauthorized();
}
catch(UnauthorizedException e) {
    handleUnauthenticated();
}
catch(NotFoundException e) {
    handleNotFound();
}

使用这种方法，开发人员不需要了解生成错误的 HTTP 状态代码，他只需处理 Java 异常。另一个优点是开发人员可能只捕获他想要处理的异常（不像之前必须捕获单个异常的情况（RestServiceException）然后才决定他是否要处理它）。

然而，仍然存在一个问题。通过查看方法的签名，开发人员仍然不知道他可能需要处理哪种错误，因为我们在方法的签名中只有超类。

3. 拥有错误的类层次结构+将它们列在方法的签名中

好的，现在想到的是将方法的签名更改为：

public Photo getPhoto(String photoID) throws UnauthenticatedException, UnauthorizedException, NotFoundException;

但是，将来可能会向此休息端点添加新的错误情况。这意味着向方法的签名添加一个新的 Exception，这将是对 java api 的重大更改。我们希望有一个更强大的解决方案，不会导致在所描述的情况下对 api 进行重大更改。

4. 拥有错误的类层次结构（使用未经检查的异常）+将它们列在方法的签名中

那么，未经检查的异常呢？如果我们更改 RestServiceException 以扩展 RuntimeException：

public class RestServiceException extends RuntimeException

我们保留方法的签名：

public Photo getPhoto(String photoID) throws UnauthenticatedException, UnauthorizedException, NotFoundException;

这样我就可以向方法的签名添加新的异常，而不会破坏现有代码。 但是，使用此解决方案，开发人员不会被迫捕获任何异常，也不会注意到需要处理的错误情况，直到他仔细阅读文档（是的，对！）或注意到方法签名中的异常。

在这种情况下处理错误的最佳实践是什么？

除了我提到的那些之外，还有其他（更好的）替代方案吗？

异常处理替代方案：回调

我不知道这是否是更好的选择，但您可以使用回调。您可以通过提供默认实现来使某些方法可选。看看这个：

    /**
     * Example 1.
     * Some callbacks will be always executed even if they fail or 
     * not, all the request will finish.
     * */
    RestRequest request = RestRequest.get("http://myserver.com/photos/31", 
        Photo.class, new RestCallback(){

            //I know that this error could be triggered, so I override the method.
            @Override
            public void onUnauthorized() {
                //Handle this error, maybe pop up a login windows (?)
            }

            //I always must override this method.
            @Override
            public void onFinish () {
                //Do some UI updates...
            }

        }).send();

回调类如下所示：

public abstract class RestCallback {

    public void onUnauthorized() {
        //Override this method is optional.
    }

    public abstract void onFinish(); //Override this method is obligatory.


    public void onError() {
        //Override this method is optional.
    }

    public void onBadParamsError() {
        //Override this method is optional.
    }

}

通过这样做，您可以定义请求生命周期，并管理请求的每个状态。您可以选择是否实现某些方法。您可以获得一些常规错误，并为用户提供实现处理的机会，就像在 onError 中一样。

如何清楚地定义处理哪些异常？

如果你问我，最好的方法是绘制请求的生命周期，如下所示：

这只是一个糟糕的例子，但重要的是要记住，所有方法的实现都可以是可选的，也可以不是可选的。如果onAuthenticationError是强制性的，但不一定是onBadUsername也会如此，反之亦然。这就是回调如此灵活的一点。

我如何实现 Http 客户端？

好吧，我对 http 客户端不太了解，我总是使用apache http://hc.apache.org/httpclient-3.x/HttpClient，但是http客户端之间并没有太大的区别，大多数都有或多或少的功能，但最终，它们都是一样的。只需选择 http 方法，输入 url、参数，然后发送。对于这个例子，我将使用 apache HttpClient

public class RestRequest {
    Gson gson = new Gson();

    public <T> T post(String url, Class<T> clazz,
            List<NameValuePair> parameters, RestCallback callback) {
        // Create a new HttpClient and Post Header
        HttpClient httpclient = new DefaultHttpClient();
        HttpPost httppost = new HttpPost(url);
        try {
            // Add your data
            httppost.setEntity(new UrlEncodedFormEntity(parameters));
            // Execute HTTP Post Request
            HttpResponse response = httpclient.execute(httppost);
            StringBuilder json = inputStreamToString(response.getEntity()
                    .getContent());
            T gsonObject = gson.fromJson(json.toString(), clazz);
            callback.onSuccess(); // Everything has gone OK
            return gsonObject;

        } catch (HttpResponseException e) {
            // Here are the http error codes!
            callback.onError();
            switch (e.getStatusCode()) {
            case 401:
                callback.onAuthorizationError();
                break;
            case 403:
                callback.onPermissionRefuse();
                break;
            case 404:
                callback.onNonExistingPhoto();
                break;
            }
            e.printStackTrace();
        } catch (ConnectTimeoutException e) {
            callback.onTimeOutError();
            e.printStackTrace();
        } catch (MalformedJsonException e) {
            callback.onMalformedJson();
        }
        return null;
    }

    // Fast Implementation
    private StringBuilder inputStreamToString(InputStream is)
            throws IOException {
        String line = "";
        StringBuilder total = new StringBuilder();

        // Wrap a BufferedReader around the InputStream
        BufferedReader rd = new BufferedReader(new InputStreamReader(is));

        // Read response until the end
        while ((line = rd.readLine()) != null) {
            total.append(line);
        }

        // Return full string
        return total;
    }

}

这是一个示例实现RestRequest。这只是一个简单的例子，当你制作自己的休息客户端时，有很多话题需要讨论。例如，“用什么类型的json库来解析？”，“你是为android工作还是为java工作？” （这很重要，因为我不知道 android 是否支持 java 7 的某些功能，例如多捕获异常，并且有些技术不适用于 java 或 android，反之亦然）。

但我能说的最好的办法是根据用户编写 sdk api 代码，请注意，发出其余请求的行很少。

希望这可以帮助！再见 ：]