服务返回码的设计

服务返回码的设计

服务的返回码指示服务正常返回结果或是执行出现异常。

最简单的设计

返回码只有两个：成功，服务正常返回；失败，服务执行出现异常。

实际情况下，返回码只有成功和失败可能不能满足需求。

程序异常的原因有很多种。
例如，服务消费者输入参数不合法、业务走不通、数据库无法访问、 网络不通等等。

服务消费者需要根据不同的返回码，向用户展示不同的提示信息。
例如，如果服务返回码指示输入参数不合法，服务消费者会根据每个返回码提示不同的信息；
如果服务返回码指示数据库无法访问、网络不通等基础设施异常，服务消费者为了隐藏非业务的细节，
会返回统一的提示信息 。

无结构的返回码设计

返回码字面上没有任何联系。

缺点：服务消费者需要分别处理每一个返回码。

可以优化的地方: 大部分返回码的处理逻辑都是一样的。
比如输入参数不合法, 处理逻辑都是将返回码转换成提示信息。

结构化的返回码设计

所有的返回码被组织成树形结构。

这样，服务消费者可以按返回码的类别来进行处理。

比如HTTP的返回码，第一位为分类，后两位为具体的情况。
详见 https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

有含义的文本或数字？

使用有含义的文本表示返回码，还是使用数字表示返回码，是一个问题。

使用数字的优点是返回码短，效率高一点；但是开发人员需要依据数据字典解释每个数字码代表的意思。

使用有含义的文本的缺点是返回码任意长度；优点是开发人员看见返回码就能大概知道其含义。

Java实现（使用有含义的文本）

public class ServiceCode {
    /**
     * 成功
     */
    public static final String SUCCESS = "S";
    /**
     * 异常
     */
    public static final String ERROR = "E";
    /**
     * 返回码是否为异常码
     */
    public static boolean isError(String code) {
        return isError(code, ERROR);
    }
    /**
     * 返回码是否属于某一类异常码
     */
    public static boolean isError(String code, String error) {
        return code.startsWith(error);
    }
}


public class ListArticleServiceCode extends ServiceCode {
    /**
     * 参数异常
     */
    public static final String E_PARA = ERROR + ".PARA";
    /**
     * 参数异常, 页数不能为空
     */
    public static final String E_PARA_PAGE_EMPTY = E_PARA + ".PAGE_EMPTY";

    /**
     * 业务异常
     */
    public static final String E_BIZ = ERROR + ".BIZ";

    /**
     * 基础设施异常
     */
    public static final String E_INFRA = ERROR + ".INFRA";

    /**
     * 数据库异常
     */
    public static final String E_INFRA_DB = E_INFRA + ".DB";
}