Thrift之TProtocol系列TJSONProtocol解析

在了解JSON协议之前，朋友们可以先去了解一下JSON的基础知识，和ASCII基本分布，关于JSON一些常识请见这里;

JSON (JavaScript Object Notation)是一种数据交换格式，是以JavaScript为基础的数据表示语言，是在以下两种数据结构的基础上来定义基本的数据描述格式的：1) 含有名称/值对的Object；2) 以”[“,",","]"组成的数组。对于 JSON，下例：形如{“name”:”tom”,”age”:23}就表示一个JSON 对象，其有两个属性，值分别为tom和23。key必须为string。JSON支持的基本数据类型，包括Number，Boolean,  null, String;  boolean, null类型值不能加” “，不然会当做string来出来，再通过object, array来组合成丰富的类型结构。

来看看Thrift中JSON常用标签的定义：

  private static final byte[] COMMA = new byte[] {','};      //json object中键值对之间, json array中元素之间的
  private static final byte[] COLON = new byte[] {':'};       //json object中key : value
  private static final byte[] LBRACE = new byte[] {'{'};      //json object开始标签
  private static final byte[] RBRACE = new byte[] {'}'};      //json object结束标签
  private static final byte[] LBRACKET = new byte[] {'['};    //json array开始标签
  private static final byte[] RBRACKET = new byte[] {']'};    //json array结束标签
  private static final byte[] QUOTE = new byte[] {'"'};       //json 字符串标签
  private static final byte[] BACKSLASH = new byte[] {'\\'};   //json中转义
  private static final byte[] ZERO = new byte[] {'0'};        // 0字符

Unicode编码形式：

private static final byte[] ESCSEQ = new byte[] {'\\','u','0','0'};

JSON中字符串是由双引号包围的任意数量的unicode字符结合，当然还要包含通过'\'转义字符（不多），如下；

  private static final String ESCAPE_CHARS = "\"\\/bfnrt";    //需要转义的字符 '"' , '\' , ' /' ,'b' , 'f' , 'n' ,'r' ,'t'

  private static final byte[] ESCAPE_CHAR_VALS = {
    '"', '\\', '/', '\b', '\f', '\n', '\r', '\t', // 转义字符对应的字节数组
  };

ASCII表前48字符表：

   private static final byte[] JSON_CHAR_TABLE = {
     /*  0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F */
         0,  0,  0,  0,  0,  0,  0,  0,'b','t','n',  0,'f','r',  0,  0, //
         0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0, //
         1,  1,'"',  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1, //
   };

前48个字符中，值为0的是一些不常用的控制字符，所以这里标为0，unicode输出；值为1的为那些可显示非转义字符，输出时直接按其ASCII编码值输出即可；其他的是需要转义的字符，按照上面的转义字符的字节数组输出，

下面是ASCII编码图，朋友们可以参照着看一下：

下面是Thrift内部数据类型对应的JSON输出字节数组标志，在write和read时，会按照其进行相应的转换，源码时，具体分析：

  private static final byte[] NAME_BOOL = new byte[] {'t', 'f'};
  private static final byte[] NAME_BYTE = new byte[] {'i','8'};
  private static final byte[] NAME_I16 = new byte[] {'i','1','6'};
  private static final byte[] NAME_I32 = new byte[] {'i','3','2'};
  private static final byte[] NAME_I64 = new byte[] {'i','6','4'};
  private static final byte[] NAME_DOUBLE = new byte[] {'d','b','l'};
  private static final byte[] NAME_STRUCT = new byte[] {'r','e','c'};
  private static final byte[] NAME_STRING = new byte[] {'s','t','r'};
  private static final byte[] NAME_MAP = new byte[] {'m','a','p'};
  private static final byte[] NAME_LIST = new byte[] {'l','s','t'};
  private static final byte[] NAME_SET = new byte[] {'s','e','t'};

基本重要数据成员介绍完毕，在具体分析读写前，再来介绍下写辅助方法和类，有助于后面读写的具体理解：

// 把char（'0 - 9' & ' a - f'）字符转变为相应的hex十六进制值。
  private static final byte hexVal(byte ch) throws TException {
    if ((ch >= '0') && (ch <= '9')) {
      return (byte)((char)ch - '0');
    }
    else if ((ch >= 'a') && (ch <= 'f')) {
      return (byte)((char)ch - 'a' + 10);
    }
    else {
      throw new TProtocolException(TProtocolException.INVALID_DATA,
                                   "Expected hex character");
    }
  }

  // 上面的反过程，把hex十六进制值转变为相应的字符。
  private static final byte hexChar(byte val) {
    val &= 0x0F;
    if (val < 10) {
      return (byte)((char)val + '0');
    }
    else {
      return (byte)((char)(val - 10) + 'a');
    }
  }

辅助类，用于具体读写过程中写入，或读取JSON语法字符，该类为基类，no-op：

 protected class JSONBaseContext {
    protected void write() throws TException {}

    protected void read() throws TException {}

    protected boolean escapeNum() { return false; }
  }

用于读取JSON数组的JSONBASEContext子类, 用于写入，读取元素item之间的JSON语法字符 ' ,':

 protected class JSONListContext extends JSONBaseContext {
    private boolean first_ = true;  //第一个元素之前不要添加,读取 ',';

    @Override
    protected void write() throws TException {
      if (first_) {
        first_ = false;
      } else {
        trans_.write(COMMA);
      }
    }

    @Override
    protected void read() throws TException {
      if (first_) {
        first_ = false;
      } else {
        readJSONSyntaxChar(COMMA);
      }
    }
  }

用于读取JSON 对象(Object)的JSONBASEContext子类,  用于写入，读取元素item之间的 ' ,' , 和key, value对之间的 ':' JSON语法字符:

  protected class JSONPairContext extends JSONBaseContext {
    private boolean first_ = true;   //添加，读取 ','字符的标志，第一个不需要加入和读取；
    private boolean colon_ = true;   //添加，读取 ':'字符的标志，

    @Override
    protected void write() throws TException {
      if (first_) {
        first_ = false;
        colon_ = true;
      } else {
        trans_.write(colon_ ? COLON : COMMA);
        colon_ = !colon_;
      }
    }

    @Override
    protected void read() throws TException {
      if (first_) {
        first_ = false;
        colon_ = true;
      } else {
        readJSONSyntaxChar(colon_ ? COLON : COMMA);
        colon_ = !colon_;
      }
    }

    @Override
    protected boolean escapeNum() { //由于JSON Object的key必须为string类型，所以这里用colon标志，同时标注是否需要写入，读取'"'字符；
      return colon_;
    }
  }

private Stack<JSONBaseContext> contextStack_ = new Stack<JSONBaseContext>(); //用于读取不同类型时，上下文上下切换，上面提及的两种上下文，读取和写入JSON Object,和JSON array,当递归解析和写入时，得随时切换
  private JSONBaseContext context_ = new JSONBaseContext(); //当前读取，写入上下文。
 //
  private void pushContext(JSONBaseContext c) { //吧方法参数的上下文设为当前上下文（比如当前真在解析JSON array，而array中出现一个JOSN object(map) item时，得切换到JSONPairContext来解析）
    contextStack_.push(context_); //当前上下文压入栈，
    context_ = c;
  }

  private void popContext() {
    context_ = contextStack_.pop();   //吧之前压入栈的上下文设为当前上下文（还是上面的例子，当JSON object解析完后，接着解析array别的item，所以还得之前压入栈的上下文）
  }

上面两个类都用到readJSONSyntaxChar(xxx)方法，我们再来看看：

 protected void readJSONSyntaxChar(byte[] b) throws TException {
    byte ch = reader_.read();     //方法参数设定一个字节数组，当读取的字节不等于b[0]抛异常，要来验证读取的字节是否为指定的JSON语句字符的。
    if (ch != b[0]) {
      throw new TProtocolException(TProtocolException.INVALID_DATA,
                                   "Unexpected character:" + (char)ch);
    }
  }

JOSN协议从传输层读取字节时都是一字节一字节的读取：

 protected class LookaheadReader {

    private boolean hasData_;
    private byte[] data_ = new byte[1];

   //检测当前容量为1的字节数组中是否有数据，没有从底层传输层读取一字节，该方法是消耗型的
    protected byte read() throws TException {
      if (hasData_) {
        hasData_ = false;
      }
      else {
        trans_.readAll(data_, 0, 1);
      }
      return data_[0];
    }

    // 同上，不同的是该方法不发生消耗
    protected byte peek() throws TException {
      if (!hasData_) {
        trans_.readAll(data_, 0, 1);
      }
      hasData_ = true;
      return data_[0];
    }
  }

别的参数成员：

 // 上面已经介绍，当前解析的底层读取器，一个字节一个字节的读取
  private LookaheadReader reader_ = new LookaheadReader();

  // 是否写入TField的(即方法参数的参数名)的标志，不写入参数名，就要参数标号来代替
  private boolean fieldNamesAsString_ = false;

OK！进入正文，首先看看JSON协议怎么写数据的，从string开始，JSON String分Unicode和转义字符两种：

 private void writeJSONString(byte[] b) throws TException {
    context_.write(); // JSONBaseContext 空操作
    trans_.write(QUOTE); //写入'"'字符
    int len = b.length;
    for (int i = 0; i < len; i++) {
      if ((b[i] & 0x00FF) >= 0x30) { //对照上面的ASCII表, >= 0x30即 >= 48(上面JSON_CHAR_TABLE表述的为0 - 47，48以上的用的着的转义字符就'\')
        if (b[i] == BACKSLASH[0]) { //如果写入的字符为 '\',需要转义。
          trans_.write(BACKSLASH);//
          trans_.write(BACKSLASH); // 写两次'\'
        }
        else {
          trans_.write(b, i, 1);// 0x30上除'\'，之外的字符直接写入
        }
      }
      else { // b[i] < 48的情况，即上面设计的那张ＪＳＯＮ＿ＣＨＡＲ＿ＴＡＢＬＥ倍
        tmpbuf_[0] = JSON_CHAR_TABLE[b[i]];　　
        if (tmpbuf_[0] == 1) { 　　    ／／查表后，表对应的值为1的情况：非转义，即可直接写入。
          trans_.write(b, i, 1);
        }
        else if (tmpbuf_[0] > 1) {     //即为那些转义字符 '"' , '/' , 'b' , 't' , 'r' , 'n';
          trans_.write(BACKSLASH); // 写之前先追加'\';
          trans_.write(tmpbuf_, 0, 1);
        }
        else { //
          trans_.write(ESCSEQ);//unicode   \u00xx形式写入。
          tmpbuf_[0] = hexChar((byte)(b[i] >> 4));
          tmpbuf_[1] = hexChar(b[i]);
          trans_.write(tmpbuf_, 0, 2);
        }
      }
    }
    trans_.write(QUOTE);  // 最后再加上'"';
  }

JSON 整形输出：

private void writeJSONInteger(long num) throws TException { //虽然这里取long的字符串表现形式，但是输出是按JSON 整数表示输出（没加 '"'）;
    context_.write();  //no -op
    String str = Long.toString(num); //string表示形式
    boolean escapeNum = context_.escapeNum();  //false
    if (escapeNum) {
      trans_.write(QUOTE);
    }
    try {
      byte[] buf = str.getBytes("UTF-8");  //UTF-8字符编码得到字节数组
      trans_.write(buf);
    } catch (UnsupportedEncodingException uex) {
      throw new TException("JVM DOES NOT SUPPORT UTF-8");
    }
    if (escapeNum) {
      trans_.write(QUOTE);
    }
  }

JSON 浮点数写入，JSON浮点数有几点特殊,JSON几种特殊的浮点数用字符串表示和传输：

a. NaN表示不是数字值；

b. Infinity表示正无穷大；

c. –Infinity表示负无穷大。

private void writeJSONDouble(double num) throws TException {
    context_.write();
    String str = Double.toString(num);
    boolean special = false;
    switch (str.charAt(0)) {
    case 'N': // NaN
    case 'I': // Infinity
      special = true;
      break;
    case '-':
      if (str.charAt(1) == 'I') { // -Infinity
        special = true;
      }
      break;
    default:
      break;
  }

    boolean escapeNum = special || context_.escapeNum();  //三种特殊情况，special标志位true，此时escapeNum为true， 即用JSON字符串形式表示和输出，否则还是以JSON Number类型输出
    if (escapeNum) {
      trans_.write(QUOTE); // '"'
    }
    try {
      byte[] b = str.getBytes("UTF-8");
      trans_.write(b, 0, b.length);
    } catch (UnsupportedEncodingException uex) {
      throw new TException("JVM DOES NOT SUPPORT UTF-8");
    }
    if (escapeNum) {
      trans_.write(QUOTE); // '"'
    }
  }

Thrift的二进制值并编码为base64编码然后作为JSON的字符串：

public void writeBinary(ByteBuffer bin) throws TException {
      writeJSONBase64(bin.array(), bin.position() + bin.arrayOffset(), bin.limit() - bin.position() - bin.arrayOffset());
   }

 private void writeJSONBase64(byte[] b, int offset, int length) throws TException {
    context_.write();
    trans_.write(QUOTE);
    int len = length;
    int off = offset;
    while (len >= 3) {
      // Encode 3 bytes at a time
      TBase64Utils.encode(b, off, 3, tmpbuf_, 0);
      trans_.write(tmpbuf_, 0, 4);
      off += 3;
      len -= 3;
    }
    if (len > 0) {
      // Encode remainder
      TBase64Utils.encode(b, off, len, tmpbuf_, 0);
      trans_.write(tmpbuf_, 0, len + 1);
    }
    trans_.write(QUOTE);
  }

Thrift的bool类型写入方式是按JSON 整形写入，false = 0 , ture = 1:

public void writeBool(boolean b) throws TException {
    writeJSONInteger(b ? (long)1 : (long)0);
  }

Thrift其他整型和字节写入方式一并贴出，转换为long类型，都是按JSON整形写入：

 @Override
  public void writeByte(byte b) throws TException {
    writeJSONInteger((long)b);
  }

  @Override
  public void writeI16(short i16) throws TException {
    writeJSONInteger((long)i16);
  }

  @Override
  public void writeI32(int i32) throws TException {
    writeJSONInteger((long)i32);
  }

  @Override
  public void writeI64(long i64) throws TException {
    writeJSONInteger(i64);
  }

Thrift的double类型，按照JSON浮点数写入：

 public void writeDouble(double dub) throws TException {
    writeJSONDouble(dub);
  }

Thrift的string类型按照JSON字符串写入，JSON在处理时，会对一些字符进行转义：

 public void writeString(String str) throws TException {
    try {
      byte[] b = str.getBytes("UTF-8"); //string utf-8编码之后得到字节数组
      writeJSONString(b);
    } catch (UnsupportedEncodingException uex) {
      throw new TException("JVM DOES NOT SUPPORT UTF-8");
    }
  }

再来看看Thrift 的set , list写入方法：

  @Override
  public void writeListBegin(TList list) throws TException {
    writeJSONArrayStart();
    writeJSONString(getTypeNameForTypeID(list.elemType));
    writeJSONInteger(list.size);
  }

  @Override
  public void writeListEnd() throws TException {
    writeJSONArrayEnd();
  }

  @Override
  public void writeSetBegin(TSet set) throws TException {
    writeJSONArrayStart();
    writeJSONString(getTypeNameForTypeID(set.elemType));
    writeJSONInteger(set.size);
  }

  @Override
  public void writeSetEnd() throws TException {
    writeJSONArrayEnd();
  }

Thrift的lists和sets被表示为JSON的array（数组），其中数组的第一个元素表示Thrift元素的数据类型，数组第二值表示后面Thrift元素的个数。接着后面就是所有的元素：

  private void writeJSONArrayStart() throws TException {
    context_.write();
    trans_.write(LBRACKET);  //写入JSON array语法字符 ‘[’
    pushContext(new JSONListContext()); //设置当前处理解析上下文，
  }

  private void writeJSONArrayEnd() throws TException {
    popContext();   //回复之前的处理解析上下文
    trans_.write(RBRACKET);  //补上JSON array语句结束字符']'
  }

数组的第一个元素为数据类型，按JSON字符串写入，即本篇开头贴出的代码，getTypeNameForTypeID(set.elemType) 用于Thrift数据类型和JSON为该类型表示的字符串的字节数组之间的转换：

 private static final byte[] getTypeNameForTypeID(byte typeID)
    throws TException {
    switch (typeID) {
    case TType.BOOL:
      return NAME_BOOL;
    case TType.BYTE:
      return NAME_BYTE;
    case TType.I16:
      return NAME_I16;
    case TType.I32:
      return NAME_I32;
    case TType.I64:
      return NAME_I64;
    case TType.DOUBLE:
      return NAME_DOUBLE;
    case TType.STRING:
      return NAME_STRING;
    case TType.STRUCT:
      return NAME_STRUCT;
    case TType.MAP:
      return NAME_MAP;
    case TType.SET:
      return NAME_SET;
    case TType.LIST:
      return NAME_LIST;
    default:
      throw new TProtocolException(TProtocolException.NOT_IMPLEMENTED,
                                   "Unrecognized type");
    }
  }

数组的第二个元素为整个list , set的长度，按JSON整形写入，然后写入各个容器成员。

Thrift map数据类型写入方式：

  public void writeMapBegin(TMap map) throws TException {
    writeJSONArrayStart(); // '[' ,设置当前处理解析上下文
    writeJSONString(getTypeNameForTypeID(map.keyType)); //数组的第一个元素为key类型 =>JSON的类型字符串表示字节数组
    writeJSONString(getTypeNameForTypeID(map.valueType)); // 数组的第二个元素  为 value类型
    writeJSONInteger(map.size); //数组的第三个元素，map的长度
    writeJSONObjectStart(); //map的key,value对按 Json object输出。
  }

  @Override
  public void writeMapEnd() throws TException {
    writeJSONObjectEnd(); //回复当前上下文 ‘}’
    writeJSONArrayEnd(); //回复当前上下文 ']'
  }

  private void writeJSONObjectStart() throws TException {
    context_.write();
    trans_.write(LBRACE);
    pushContext(new JSONPairContext());
  }

  private void writeJSONObjectEnd() throws TException {
    popContext();
    trans_.write(RBRACE);
  }

Thrift的maps被表示为JSON的array，其中前两个值分别表示键和值的类型，跟着就是键值对的个数，接着就是包含具体键值对的JSON对象了。注意了JSON的键只能是字符串，这就是要求Thrift的maps类型的键必须是数字和字符串的，并且数字和字符串做转换，就是下面提及的字符串。

有效的类型标识是："tf"代表 bool，"i8" 表示 byte，"i16"表示16位整数，"i32"表示32位整数，"i64"表示64位整数，"dbl"表示双精度浮点型，"str" 表示字符串（包括二进制），"rec"表示结构体 ("records")，"map"表示 map，"lst" 表示 list， "set" 表示set。

Thrift的messages（消息）被表示为JSON的array，前四个元素分别代表协议版本、消息名称、消息类型和序列ID：

public void writeMessageBegin(TMessage message) throws TException {
    writeJSONArrayStart();
    writeJSONInteger(VERSION);
    try {
      byte[] b = message.name.getBytes("UTF-8");
      writeJSONString(b);
    } catch (UnsupportedEncodingException uex) {
      throw new TException("JVM DOES NOT SUPPORT UTF-8");
    }
    writeJSONInteger(message.type);
    writeJSONInteger(message.seqid);
  }

然后呢？该写Thrift的tstructs了（具体的RPC方法参数封装），struct是按照JSON object写入：

public void writeStructBegin(TStruct struct) throws TException {
    writeJSONObjectStart();
  }

Thrift的TField（具体的每个参数）的写入：

 public void writeFieldBegin(TField field) throws TException {
    if (fieldNamesAsString_) {
      writeString(field.name); //参数名
    } else {
      writeJSONInteger(field.id); //或者参数id
    }
    writeJSONObjectStart();  // '{'
    writeJSONString(getTypeNameForTypeID(field.type)); Thrift数据类型的字符串表示
  }

即Thrift的消息类型形如：

[ 1 (version) ,   "messageName" ,  type (call, oneway, reply, exception (byte)) ,  seq id ,
   {  "argument name" : {  " argument  type"  :  value  },
       "argument name" : {  " argument  type" :   value},
     ....................................................................
   }
]