如何正确命名后端字段以避免序列化问题

在进行需求编写时，有时需要向前端返回一个字段，用于表示账单是否结清。然而，常见的命名方式可能会导致序列化问题，因此需要注意字段的命名规范。

在这篇文章中，我将分享一个踩坑的经历，以及如何避免类似的问题。

踩坑过程

在实际开发中，我曾遇到一个经典的错误。当我命名字段为 isSettle 时，与前端的文档不一致，导致了序列化问题。

后端：这个字段一直显示错误，有空帮忙看下
前端：你这边返回的是settle，我看文档上是isSettle
后端：好的，我去看下文档
几秒钟后
后端：有坑，我修改下

这是一个非常经典的错误，我立即意识到这是序列化的问题。尽管我之前知道这个坑，但在编写代码时并未太在意，差点酿成了大祸。这个字段直接影响用户，因为它表示账单是否结清，是非常重要的一个字段。

原理

在Java的世界中，特别是在Java Web领域，框架为我们处理了大部分问题。特别是随着Spring Boot的出现，降低了入门门槛，基本上都是Spring全家桶。

这对于开发者来说的确有好处，因为可以专注于业务逻辑。但是由于框架封装得太好，导致很多人其实并不清楚框架背后的原理。当出现问题时，不清楚如何解决，这是培训班或应届生经常遇到的问题。

在后端返回给前端数据时，Spring MVC会帮我们进行数据转换。具体的转换器是MappingJackson2HttpMessageConverter。它在Spring Boot启动时通过自动装配WebMvcAutoConfiguration加载到Spring容器中，其中默认使用的序列化工具是Jackson。

例子1

假设我们有一个Person类如下：

@Data
public class Person {
    private int age;
    private String name;
    private boolean isSettle; // isxxx需注意
}

使用主流的JSON转换器如下：

Person person = new Person();
person.setAge(18);
person.setName("zhangsan");
person.setSettle(true);

// 1. Gson
System.out.println("Gson -->  " + GsonUtils.toJson(person));

// 2. Fastjson
System.out.println("Fastjson -->  " + JSON.toJSONString(person));

// 3. Fastjson2
System.out.println("Fastjson2 -->  " + com.alibaba.fastjson2.JSON.toJSONString(person));

// 4. Jackson
ObjectMapper objectMapper = new ObjectMapper();
System.out.println("Jackson -->  " + objectMapper.writeValueAsString(person));

结果如下。我们发现除了Gson以isXxx输出，其他的全部把is给默认去掉了。

Gson -->  {"age":18,"name":"zhangsan","isSettle":true}
Fastjson -->  {"age":18,"name":"zhangsan","settle":true}
Fastjson2 -->  {"age":18,"name":"zhangsan","settle":true}
Jackson -->  {"age":18,"name":"zhangsan","settle":true}

例子2

我们尝试修改Spring MVC的序列化转换器。非常简单，只需要修改MessageConverters即可。

其中PrettyPrinting是为了更加方便看出修改Gson已经成功了。

@Configuration
public class MessageConverterConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
       converters.clear();  // 移除Jackson，或者在pom中完全排除Jackson
       GsonHttpMessageConverter gsonConverter = new GsonHttpMessageConverter();
       gsonConverter.setGson(new GsonBuilder().setPrettyPrinting().create()); // setPrettyPrinting 明确可以看出使用了Gson
       converters.add(gsonConverter);
    }
}

现在我们有一个Controller接口如下：

@RequestMapping("/test/message")
public Person test() {
    Person person = new Person();
    person.setAge(18);
    person.setName("zhangsan");
    person.setOk(true);
    return person;
}

结果如下。发现boolean isOk的值返回完全不同了，一个是有is，一个是没有is的，符合我们的预期。

默认Jackson的输出  --> {"name":"zhangsan","age":18,"ok":true}

修改成Gson转换器的输出 -->  
{
  "name": "zhangsan",
  "age": 18,
  "isOk": true
}

最后

这是一个非常基础的例子，稍微有点经验的程序员都应该避免。只是有时候大意疏忽会导致各种各样的问题。我想提醒大家，尽管框架帮助我们做了很多，但我们仍然需要理解其底层实现原理。当出现问题时，如果你懂原理，很容易可以快速解决问题，这也是高级程序员和普通开发者的区别之一。在阿里的规约中，已经明确禁止使用isxxx这种命名方式。

最后祝所有程序员，编写的代码无bug，世界上不再有bug出现。