@asce1885 2015-08-12T08:29:41.000000Z 字数 7009 阅读 560

JSON解析函数库HFJson

新框架文档

Modified from LoganSquare
@author ASCE1885的 Github 简书微博 CSDN

基础知识

HFJson是在著名的jackson-core解析器基础上封装的快速解析json的函数库，它使用编译时注解代替运行时注解，从而获得速度上的提升。

HFJson包括三个Module：hfjson，hfjson-example和hfjson-processor，processor是用于编译时将注解转换成java类的，已经将修改后的代码通过Gradle发布到jcenter上面，调用者只需在build.gradle中加入一行代码就可以，processor不会出现在最终的SDK和APK中。

hfjson-processor

hfjson-processor是一个Java Library，最终生成一个jar包，为了让Android Studio通过android-apt引用它，需要将这个jar包通过Gradle发布到公共仓库JCenter上。JCenter现在是Android Studio中repositories的默认节点（之前是Maven的，不过JCenter是兼容Maven的）。

申请Bintray账号

Bintray的基本功能类似于Maven Central，首先我们需要注册一个Bintray账号。

配置build文件

我们需要生成项目的JavaDoc和source JARs，这两项都是要上传到JCenter的文件，由于生成过程需要用到android-maven-plugin插件，上传到bintray上面需要gradle-bintray-plugin的支持，所以在工程的build.gradle（最外层的build.gradle文件）中添加依赖如下所示：

// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:1.1.0'
        classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.0'
        classpath 'com.github.dcendents:android-maven-plugin:1.2'
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}
allprojects {
    repositories {
        jcenter()
    }
}

接着配置hfjson-processor这个module的build.gradle文件如下：

apply plugin: 'java'
apply plugin: 'com.github.dcendents.android-maven'
apply plugin: 'com.jfrog.bintray'
repositories {
    jcenter()
}
// This is the library version used when deploying the artifact
version = "1.0.3"
dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'org.apache.commons:commons-lang3:3.2'
}
def siteUrl = 'https://github.com/ASCE1885/hfjson-compiler' // 项目的主页
def gitUrl = 'https://github.com/ASCE1885/hfjson-compiler.git' // Git仓库的url
group = "com.paic.hyperion.core.hfjson.compiler"
install {
    repositories.mavenInstaller {
// This generates POM.xml with proper parameters
        pom {
            project {
                packaging 'jar'
// Add your description here
                name 'com.paic.hyperion.core.hfjson.compiler' //项目描述
                url siteUrl
// Set your license
                licenses {
                    license {
                        name 'The Apache Software License, Version 2.0'
                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                    }
                }
                developers {
                    developer {
                        id 'paichyperion' //填写的一
                        // 些基本信息
                        name 'hfjson-processor'
                        email 'paichyperion@gmail.com'
                    }
                }
                scm {
                    connection gitUrl
                    developerConnection gitUrl
                    url siteUrl
                }
            }
        }
    }
}
task sourcesJar(type: Jar) {
    from sourceSets.main.java.srcDirs
    classifier = 'sources'
}
//task javadoc(type: Javadoc) {
//    source = sourceSets.main.java.srcDirs
//    // classpath += project.files(getBootClasspath().join(File.pathSeparator))
//}
task javadocJar(type: Jar, dependsOn: javadoc) {
    classifier = 'javadoc'
    from javadoc.destinationDir
}
artifacts {
    archives javadocJar
    archives sourcesJar
}
Properties properties = new Properties()
properties.load(project.rootProject.file('local.properties').newDataInputStream())
bintray {
    user = properties.getProperty("bintray.user")
    key = properties.getProperty("bintray.apikey")
    configurations = ['archives']
    pkg {
        repo = "maven"
        name = "hfjson-processor" //发布到JCenter上的项目名字
        websiteUrl = siteUrl
        vcsUrl = gitUrl
        licenses = ["Apache-2.0"]
        publish = true
    }
}

上面文件中用到的bintray.user和bintray.apikey分别是你注册bintray的用户名，以及它生成的apikey，登录bintray点击进入你的账户信息里再点击Edit即有查看API Key的选项信息。我们把这两个值定义在工程的local.properties文件中（一般这文件需gitignore，防止泄露账户信息）：

bintray.user=your_user_name
bintray.apikey=your_apikey

生成文件并上传到Bintray

build一下工程，并在Android Studio的Terminal窗口中cd到工程根目录，执行

./gradlew bintrayUpload

命令，即可在hfjson-compiler Module的build/libs目录中生成项目需要的jar包：

hfjson

上传完成后，即可登录Bintray网站找到hfjson-compiler这个repo，最后一步就是申请把这个repo添加到JCenter中。我们可以进入这个搜索页面检索我们的hfjson-compiler，找到后点击进入项目主页，然后找到link to选项，添加我们的package到jcenter即可，后面等待管理员审核通过就可以使用了，使用的方式是在调用者的build.gradle文件中添加如下一行依赖：

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.neenbedankt.gradle.plugins:android-apt:1.4'
    }
}
apply plugin: 'com.neenbedankt.android-apt'
dependencies {
    apt 'com.paic.hyperion.core.hfjson.compiler:hfjson-processor:1.0.3'
}

API使用方法

Model类的创建

创建Model类有三种方式，下面分别进行介绍：

1. 为Model类的每个变量添加注解

@HFJsonObject
public class Image {
    /**
     * 标准的变量标记，表示name变量将参与到json解析和序列化中
     */
    @HFJsonField
    public String name;
    /**
     * 标准的变量标记，表示imageId变量参与到json解析和序列化中，而且会重命名为_id
     */
    @HFJsonField(name="_id")
    public int imageId;
    @HFJsonField
    public String url;
    /**
     * 虽然这是一个包访问范围的变量，但使用@HFJsonField注解后，仍然可以参与到
     * json的解析和序列化中
     */
    @HFJsonField(name="similar_images")
    List<Image> similarImages;
    /**
     * 该变量没有使用@HFJsonField注解，因此不会参与到json的解析和序列化中
     */
    public int nonJsonField;
    /**
     * 由于这是一个私有变量，因此使用@HFJsonField注解，需要同时提供该变量的
     * getter和setter函数，否则将会出错
     */
    @HFJsonField
    private int privateInt;
    public int getPrivateInt() {
        return privateInt;
    }
    public void setPrivateInt(int i) {
        privateInt = i;
    }
    /**
     * 可选的回调函数，用于该类实例结束解析后调用
     */
    @OnHFJsonParseComplete
    void onParseComplete() {
        // 在这里可以增加Json解析前的预处理
    }
    /**
     * 可选的回调函数，用于该类实例开始序列化之前调用
     */
    @OnPreHFJsonSerialize
    void onPreSerialize() {
        // 在这里可以增加Json序列后的后处理
    }
}

2. 标记所有公共和包访问范围的变量

/**
 * NONPRIVATE_FIELDS策略模式说明要标记所有非私有的变量，即使这些变量没有使用@HFJsonField注解
 *
 */
@HFJsonObject(fieldDetectionPolicy = HFJsonObject.FieldDetectionPolicy.NONPRIVATE_FIELDS)
public class Image2 {
    public String name;
    /**
     * 如果想要imageId变量在json解析和序列化中使用新的名字_id，那么还是需要单独注解
     */
    @HFJsonField(name="_id")
    public int imageId;
    public String url;
    /**
     * 包访问范围的变量仍然会参与到Json解析和序列化中
     */
    List<Image> similarImages;
    /**
     * 对于不想参与到Json解析和序列化中的变量，使用@HFJsonIgnore进行注解标记
     */
    @HFJsonIgnore
    public int nonJsonField;
    /**
     * 由于这是私有变量，在NONPRIVATE_FIELDS策略下，该变量将不会参与到Json解析和序列化中
     */
    private int privateInt;
    public int getPrivateInt() {
        return privateInt;
    }
    public void setPrivateInt(int i) {
        privateInt = i;
    }
    /**
     * 可选的回调函数，用于该类实例结束解析后调用
     */
    @OnHFJsonParseComplete
    void onParseComplete() {
        // 在这里可以增加Json解析前的预处理
    }
    /**
     * 可选的回调函数，用于该类实例开始序列化之前调用
     */
    @OnPreHFJsonSerialize
    void onPreSerialize() {
        // 在这里可以增加Json序列后的后处理
    }
}

3. 标记所有公共和包访问范围的变量以及访问函数

/**
 * NONPRIVATE_FIELDS_AND_ACCESSORS策略模式说明要标记所有非私有的变量以及具有getter和setter函数的私有变量，
 * 即使这些变量没有使用@HFJsonField注解
 *
 */
@HFJsonObject(fieldDetectionPolicy = HFJsonObject.FieldDetectionPolicy.NONPRIVATE_FIELDS_AND_ACCESSORS)
public class Image3 {
    public String name;
    /**
     * 如果想要imageId变量在json解析和序列化中使用新的名字_id，那么还是需要单独注解
     */
    @HFJsonField(name="_id")
    public int imageId;
    public String url;
    /**
     * 包访问范围的变量仍然会参与到Json解析和序列化中
     */
    List<Image> similarImages;
    /**
     * 对于不想参与到Json解析和序列化中的变量，使用@HFJsonIgnore进行注解标记
     */
    @HFJsonIgnore
    public int nonJsonField;
    /**
     * 由于这是私有变量，在NONPRIVATE_FIELDS_AND_ACCESSORS策略下，
     * 该变量如果具有setter和getter函数，那它将会参与到Json解析和序列化中
     * 如果两个函数缺一，或者都没有，则不参与到Json解析和序列化中
     */
    private int privateInt;
    public int getPrivateInt() {
        return privateInt;
    }
    public void setPrivateInt(int i) {
        privateInt = i;
    }
    /**
     * 可选的回调函数，用于该类实例结束解析后调用
     */
    @OnHFJsonParseComplete
    void onParseComplete() {
        // 在这里可以增加Json解析前的预处理
    }
    /**
     * 可选的回调函数，用于该类实例开始序列化之前调用
     */
    @OnPreHFJsonSerialize
    void onPreSerialize() {
        // 在这里可以增加Json序列后的后处理
    }
}

Json的解析

Json解析的数据来源可以有两种：InputStream和String。

// Parse from an InputStream
try {
        InputStream is = ...;
        Image imageFromInputStream = HFJson.parse(is, Image.class);
        // Parse from a String
        String jsonString = ...;
        Image imageFromString = HFJson.parse(jsonString, Image.class);
} catch (IOException e) {
    e.printStackTrace();
}

Json的序列化

Json对象可以序列化到OutputStream和String中。

try {
    Image image =  new Image();
    // Serialize it to an OutputStream
    OutputStream os = ...;
    HFJson.serialize(image, os);
    // Serialize it to a String
    String jsonString = HFJson.serialize(image);
} catch (IOException e) {
    e.printStackTrace();
}

支持的数据类型

支持的内建数据类型

使用@JsonObject标记的任何对象
int和Integer
long和Long
float和Float
double和Double
boolean和Boolean
String
Date（需要以ISO 8601标准：yyyy-MM-dd'T'HH:mm:ss.SSSZ）

支持的集合类型

ArrayList，LinkedList
HashSet
ArrayDeque
HashMap，TreeMap，LinkedHashMap