API JSON 格式设计

本来一直觉得API是个很简单的东西，没啥可说的。因为某些原因，还是简单写一点。一般来说，一个API对应的bean对象应该只有一种，不过也会有工程师给的一个API对应两种Bean，请求成功的data为一种类型，失败又为另外一种类型，这个写起来就可能要解析两次了。不知道是不是我入门太浅，这里写一下个人对API的一个简单设计理解。

一般的API设计

 class Json<T> {
        int status;//状态码
        String msg;//简单描述
        String detail;//详细描述
        T data;//数据
    }

//测试方法
 public void test() {
        /**T为Object类型*/
        Json json = new Json();
        json.status = -1;
        json.msg = "参数错误";
        json.detail = "数据不能为空";
        String str = GsonUtil.INSTANCE.getGson().toJson(json);
        System.out.print(str + "\n\n\n");

        /** 没有detail信息*/
        Json jsonSuccess = new Json();
        jsonSuccess.status = 200;
        jsonSuccess.msg = "验证码已发送";
        jsonSuccess.data = "154564";
        String str1 = GsonUtil.INSTANCE.getGson().toJson(jsonSuccess);
        System.out.print(str1 + "\n");

        /**自定义类型，如果自定义类型的字段无数据，不返回此字段信息 比如Json里面不会有text1这个字段*/
        Json json2 = new Json();
        json2.status = 200;
        json2.msg = "验证码已发送";
        AA a1 = new AA();
        a1.text = "text";
        a1.code = 100;
        json2.data = a1;
        String str2 = GsonUtil.INSTANCE.getGson().toJson(json2);
        System.out.print(str2 + "\n");

        /** 基础数据类型，比如int ,java里默认会初始化一个值，所以不赋值时也会包含这个字段信息,简单的说就是int不能为null*/
        Json json3 = new Json();
        json3.status = 200;
        json3.msg = "验证码已发送";
        AA a = new AA();
        a.text = "text";
        a.text1 = "text1";
        json3.data = a;
        String str3 = GsonUtil.INSTANCE.getGson().toJson(json3);
        System.out.print(str3);

    }

输出

{"status":-1,"msg":"参数错误","detail":"数据不能为空"}


{"status":200,"msg":"验证码已发送","data":"154564"}
{"status":200,"msg":"验证码已发送","data":{"text":"text","code":100}}
{"status":200,"msg":"验证码已发送","data":{"text":"text","text1":"text1","code":0}}

这样很明了，但是有些时候，有的工程师可能回为了图简单啥的。没有detail字段，然后把detail的描述信息写到data字段里面，这样就会产生一个api对应几种bean.这么写也容易产生这种问题。个人建议写法

<!-- 方式一 -->
final class BaseJson{
 String status;//请求状态
 String msg;//数据错误  \ 成功等
 String detail;//用于描述详细信息：比如：手机号不能为空 -没有信息时不会返回此字段
}

<!-- 使用工厂模式创建ErrJson ,直接写个静态方法创建，定义系统级别ERRCODE 和API级别ERRCODE -->
class ErrJson extends BaseJson{}

class DataJson<T> extends BaseJson{
    T data;
}

避免返回数据出现不同类型。

至于为什么这么做，因为移动端人员是直接把数据解析为bean对象。而不是先把数据解析为json对象，再判断status,然后再去解析AA对象。

     Json<AA> aaJson = GsonUtil.INSTANCE.getGson().fromJson(str3, new TypeToken<AA>() {
        }.getType());
        System.out.println(aaJson.toString());