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

error-handling exception java api sdk

2022-09-02 03:57:12

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

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

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;
    }
}

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

通过查看方法的签名，开发人员不知道他可能需要处理哪种错误情况。
开发人员需要直接处理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;

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

4. 具有错误的类层次结构（使用未选中的异常）+在方法的签名中列出它们

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

public class RestServiceException extends RuntimeException

我们保留该方法的签名：

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

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

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

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

答案 1

异常处理替代方案：回调

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

    /**
     * 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中一样。

如何明确定义异常处理事项？

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

Sample exception lifecicle

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

我如何实现 Http 客户端？

好吧，我对http客户端了解不多，我总是使用apache 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;
    }

}

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

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

希望这有帮助！再见：]

答案 2

看来你是在用“手”做事。我建议你试试Apache CXF。

JAX-RS API 是一个简洁的实现，它使您能够几乎忘记 REST。它与（也推荐的）春天配合得很好。

您只需编写实现接口（API）的类。您需要做的是使用 JAX-RS 注释来注释接口的方法和参数。

然后，CXF做了魔术。

在 Java 代码中抛出正常的异常，然后在 server/nd 或客户端上使用异常映射器在它们和 HTTP 状态代码之间进行转换。

这样，在服务器/Java 客户端上，您只需处理常规的 100% Java 异常，而 CXF 将为您处理 HTTP：您既具有清晰的 REST API 的优势，又具有可供用户使用的 Java 客户端。

客户端可以从 WDSL 生成，也可以在运行时通过接口注释的内省生成。

看：

在我们的应用程序中，我们定义并映射了一组错误代码及其对应的异常：

4XX 预期/函数扩展（如错误的参数、空集等）
5XX 意外/无法恢复的运行时“不应发生”的内部错误异常

它遵循 REST 和 Java 标准。