JSON的编码风格与常见的应用场景及最佳实战

JSON的编码风格与常见的应用场景及最佳实战 908 阅读 0 评论 0 点赞

JSON的编码风格与常见的应用场景及最佳实战

本篇内容包括如下部分内容：JSON编码指南；JSON应用场景；实践经验之谈

1.JSON风格指南

这里的JSON指南，主要推荐的是谷歌的Google JSON风格指南。无论什么语言编程，也通常遵循2/8法则，即遵循好的设计与编码风格，能提前解决80%的问题。关于谷歌的这个JSON编程风格指南手册，可以在如下两个地方找到：

英文版Google JSON Style Guide：https://google.github.io/styleguide/jsoncstyleguide.xml
中文版Google JSON风格指南：https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.md

请主要核心点，简单摘录如下：

属性名和值都是用双引号，不要把注释写到对象里面，对象数据要简洁
不要随意结构化分组对象，推荐是用扁平化方式，层次不要太复杂
命名方式要有意义，比如单复数表示
驼峰式命名，遵循Bean规范
使用版本来控制变更冲突
对于一些关键字，不要拿来做key
如果一个属性是可选的或者包含空值或null值，考虑从JSON中去掉该属性，除非它的存在有很强的语义原因
序列化枚举类型时，使用name而不是value
日期要用标准格式处理
设计好通用的分页参数
设计好异常处理

另外，需要关注的内容是JSON API规范，目前该项工作在推进中，取得了很多可喜成果。关于JSON API，这里提几点：

JSON API与Google JSON风格指南有很多可以相互参照之处。
JSON API是数据交互规范，用以定义客户端如何获取与修改资源，以及服务器如何响应对应请求。
JSON API设计用来最小化请求的数量，以及客户端与服务器间传输的数据量。在高效实现的同时，无需牺牲可读性、灵活性和可发现性。
JSON API需要使用JSON API媒体类型(application/vnd.api+json) 进行数据交互。
JSON API服务器支持通过GET方法获取资源。而且必须独立实现HTTP POST, PUT和DELETE方法的请求响应，以支持资源的创建、更新和删除。
JSON API服务器也可以选择性支持HTTP PATCH方法 [RFC5789]和JSON Patch格式 [RFC6902]，进行资源修改。JSON Patch支持是可行的，因为理论上来说，JSON API通过单一JSON 文档，反映域下的所有资源，并将JSON文档作为资源操作介质。在文档顶层，依据资源类型分组。每个资源都通过文档下的唯一路径辨识。

规范详情可以参考整理：http://jsonapi.org.cn/format/。

2.JSON应用场景

JSON的使用，依据不同用途，有几个典型的场景：

内部后台系统之间的数据传输，此种情况下基于HTTP的JSON格式其实没有优势。
前后台之间的API调用，典型的是前端作为React/VUE/AngularJS/ExtJS等框架做的，前后端使用JSON交互。

此时可以使用类似Dubbox之类的框架，或者原始一些SpringMVC的Controller上直接@ResponseBody或@RestController也可以。
强烈建议在Dubbox之类的rest之上再加一个Nginx转发，这样一些策略的控制，比如同源的控制、简单的缓存策略、安全策略等都可以放到Nginx上来做，也利于多个机器时的负载均衡。
建议使用swaggerUI来自动实现API文档和在线测试。功能很强大，操作简单，而且可以mock接口，在后台没有做好之前，前台就可以先开发了。
可以使用RestUnit或SoapUI来实现自动化测试与压力测试。

提供给第三方的开发接口API
基本同上，可以参考Google JSON风格指南与JSON API规范指南。

3.经验之谈

在借助各类工具处理JSON数据时，最常见的其实是大家使用的不规范性，这样碰到各种坑的可能性就很大。根据平时使用Fastjson的经验以及工程师的应用反馈，这里简要总结一下大家常见的问题，归纳如下：

3.1 遵循Java Beans规范与JSON规范

实践告诉我们：遵循beans规范和JSON规范的方式，能减少大部分的问题，比如正确实现setter、getter，用别名就加annotation。注意基本类型的匹配转换，比如在fastjson的issue见到试图把{a:{}}中的a转换成List的。

3.2 使用正常的key

尽量不要使用数字等字符开头的key，尽量使用符合Java的class或property命名规范的key，这样会减少不必要的冲突。在jsonpath或js里，a.1可能会被解释成a[1]或a[1]，这些都会带来不必要的麻烦。

3.3 关于日期处理

这一点前面的Google JSON风格指南里也提到了，尽量使用标准的日期格式。或者序列化和反序列化里都是用同样的datePattern格式。

3.4 自定义序列化与反序列化

对于新手来说，自定义序列化是一切罪恶的根源。

尽量不要使用自定义序列化，除非万不得已，优先考虑使用注解过滤，别名等方式，甚至是重新建一个VO类来组装实际需要的属性。使用自定义序列化时一切要小心，因为这样会导致两个问题：

改变了pojo <-> jsonstring 的自然对应关系，从而不利于阅读代码和排查问题，你改变的关系无法简单的从bean和json上看出来了；
反序列化可能出错，因为对应不上原来的属性了。

如果只是序列化发出去（响应）的是JSON数据、传过来（请求）的数据格式跟JSON无关或者是标准的，此时自定义序列化就无所谓了，反正是要接收方来处理。

3.5 JSONObject的使用

JSONObject是JSON字符串与pojo对象转换过程中的中间表达类型，实现了Map接口，可以看做是一个模拟JSON对象键值对再加上多层嵌套的数据集合，对象的每一个基本类型属性是map里的一个key-value，一个非基本类型属性是一个嵌套的JSONObject对象（key是属性名称，value是表示这个属性值的对象的JSONObject）。如果以前用过apache beanutils里的DynamicBean之类的，就知道JSONObject也是一种动态描述Bean的实现，相当于是拆解了Bean本身的结构与数据。这时候由于JSONObject里可能会没有记录全部的Bean类型数据，例如泛型的具体子类型之类的元数据，如果JSONObject与正常的POJO混用，出现问题的概率较高。

下列方式尽量不要使用：

public class TestBean{
 @Setter @Getter
 private TestBean1 testBean1;
 
 @Setter @Getter
 private JSONObject testBean2; // 尽量不要在POJO里用JSONObject
}
``` 
应该从设计上改为都用POJO比较合适:
```java
public class TestBean{
 @Setter @Getter
 private TestBean1 testBean1;
 
 @Setter @Getter
 private TestBean2 testBean2;; // 使用POJO
}
``` 
相对的，写一些临时性的测试代码、demo代码，可以直接全部用JSONObject先快速run起来。
同理，jsonstring中嵌套jsonstring也尽量不要用，例如：
```javascript
{
 "name":"zhangsan",
 "score":"{\"math\":78,\"history\":82}"
}

应该改为全部都是JSON风格的结构：

{
 "name":"zhangsan",
 "score":{
 "math":78,
 "history":82
 }
}

另外，对于jsonstring转POJO（或POJO转jsonstring），尽量使用直接转的方式，而不是先转成JSONObject过渡的方式。特别是对于Fastjson，由于性能优化的考虑，这两个执行的代码是不一样的，可能导致不一样的结果。

String jsonstring = "{\"a\":12}";
// 不推荐这种方式
// 除非这里需要对jsonObject做一些简单处理
JSONObject jsonObject = JSON.parseObject(jsonstring);
A a = jsonObject.toJavaObject(A.class);
// 推荐方式
A a = JSON.parseObject(jsonstring, A.class);