Fastjson2 @JSONField 注解：对象与 JSON 字段映射

在 Java 开发中，JSON 与对象之间的转换是常用需求，比如excel导出，接口对接等。Fastjson2 作为高性能的 JSON 处理库，提供了许多便捷的注解来简化这个过程。其中，@JSONField 是最常用、最核心的注解之一。本文将带你从零开始，全面掌握 @JSONField 的使用方法。

什么是 @JSONField？

@JSONField 是 Fastjson2 提供的一个字段级注解，用于控制 Java 对象属性与 JSON 字段之间的映射关系。通过这个注解，我们可以：

自定义 JSON 字段名
控制字段的序列化/反序列化行为
指定日期格式
设置字段顺序

基础用法

1. 修改字段名称

当 Java 属性名与 JSON 字段名不一致时，可以用 name 属性指定映射。

public class User {
    @JSONField(name = "user_name")
    private String name;

    @JSONField(name = "user_age")
    private int age;
}

// 测试代码
User user = new User();
user.setName("张三");
user.setAge(25);

String json = JSON.toJSONString(user);
System.out.println(json); // 输出：{"user_age":25,"user_name":"张三"}

2. 控制序列化与反序列化

serialize 和 deserialize 属性可以控制是否参与 JSON 转换。

public class Order {
    @JSONField(serialize = false)  // 生成JSON时忽略
    private String internalId;

    @JSONField(deserialize = false) // 解析JSON时忽略
    private String calculatedField;

    private String name;
}

根据上面的Order类看看下面的例子：

// 1. 序列化示例（Java对象 → JSON）
Order order = new Order();
order.setInternalId("INTERNAL_001");  // 有 @JSONField(serialize = false)
order.setCalculatedField("计算字段值");  // 有 @JSONField(deserialize = false)
order.setName("笔记本电脑订单");

String json = JSON.toJSONString(order);
System.out.println("序列化结果（序列化时）:");
System.out.println(json);
// 输出：{"calculatedField":"计算字段值","name":"笔记本电脑订单"}
// 注意：internalId 被 serialize=false 忽略，不输出
// calculatedField 虽然被标记为 deserialize=false，但序列化时不受影响，会被输出

System.out.println();

// 2. 反序列化示例（JSON → Java对象）
String jsonStr = "{\"internalId\":\"INTERNAL_002\",\"calculatedField\":\"新计算值\",\"name\":\"手机订单\"}";

Order newOrder = JSON.parseObject(jsonStr, Order.class);
System.out.println("反序列化结果（解析JSON时）:");
System.out.println("internalId: " + newOrder.getInternalId());     // INTERNAL_002
System.out.println("calculatedField: " + newOrder.getCalculatedField()); // null（被 deserialize=false 忽略）
System.out.println("name: " + newOrder.getName());                  // 手机订单

// 注意：deserialize=false 会让 calculatedField 在反序列化时被忽略
// 但 internalId 没有 deserialize=false，所以它会被正常反序列化

3. 指定日期格式

处理日期类型时，format 属性可以指定输出格式。

public class Event {
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date eventTime;
}

// 输出结果："eventTime":"2026-05-05 14:30:00"

4. 设置字段顺序

通过 ordinal 属性可以控制字段在 JSON 中的输出顺序，数值越小越靠前。

public class Person {
    @JSONField(ordinal = 1)
    private String name;

    @JSONField(ordinal = 3)
    private int age;

    @JSONField(ordinal = 2)
    private String email;
}

// 输出顺序：name -> email -> age

高级用法

1. alternateNames 处理多个别名

当 JSON 中的字段名可能有多个别名时，可以使用 alternateNames 来处理。

public class Product {
    @JSONField(alternateNames = {"id", "product_id", "pid"})
    private String productId;
}

// 以下JSON都能正确解析
// {"id":"001"}
// {"product_id":"001"}  
// {"pid":"001"}

2. 配合 getter/setter 使用

@JSONField 既可以放在字段上，也可以放在方法上。

public class Student {
    private String name;

    @JSONField(name = "student_name")
    public String getName() {
        return name;
    }

    @JSONField(name = "student_name") 
    public void setName(String name) {
        this.name = name;
    }
}

实战示例

下面是一个完整的实战示例：

package com.example.domain;

import com.alibaba.fastjson2.annotation.JSONField;
import lombok.Data;

import java.util.Date;
@Data
public class Employee {
    @JSONField(name = "employee_id", ordinal = 1)
    private String empId;

    @JSONField(ordinal = 2)
    private String name;

    @JSONField(format = "yyyy/MM/dd", ordinal = 3)
    private Date hireDate;
    // 生成JSON时忽略
    @JSONField(serialize = false)
    private String password;
    // 解析JSON时忽略
    @JSONField(deserialize = false)
    private String computedField;
}


Employee emp = new Employee();
emp.setEmpId("E001");
emp.setName("张三");
emp.setHireDate(new Date());
emp.setPassword("123456");

String json = JSON.toJSONString(emp);
System.out.println("序列化结果：");
System.out.println(json);
// 按照 employee_id name hireDate 顺序输出
// 输出：{"employee_id":"E001","name":"张三","hireDate":"2026/05/07"}
// 注意password字段被忽略 生成JSON时忽略

String inputJson = "{\"employee_id\":\"E002\",\"name\":\"李四\",\"hireDate\":\"2024/02/20\",\"computedField\":\"abc\"}";
Employee parsedEmp = JSON.parseObject(inputJson, Employee.class);
System.out.println("反序列化结果：");
System.out.println(parsedEmp.getName()); // 李四
System.out.println(parsedEmp.getComputedField()); // null 因为 解析JSON时忽略

注意事项

优先级问题：当字段和方法同时使用 @JSONField 时，方法上的注解优先级更高。
性能影响：过度使用 serialize = false 或 deserialize = false 可能会影响代码的灵活性和可维护性。
版本兼容：alternateNames 属性是在 Fastjson2 新增的，Fastjson1 中不适用。

总结

@JSONField 注解是 Fastjson2 中最实用的注解之一，它提供了丰富的配置选项来精细控制 JSON 与 Java 对象之间的映射关系。掌握它，能让你的 JSON 处理更加灵活、高效。