Java实用注解篇: @JSONField

前言

在 Java 开发中,进行对象与 JSON 的相互转换是一项常见操作,尤其在前后端分离的架构中显得尤为重要。Fastjson 作为阿里巴巴开源的 JSON 处理框架,因其高性能和强大功能而被广泛使用。@JSONField 是 Fastjson 提供的一个注解,用于精细控制 Java Bean 字段在序列化(Java 对象转 JSON)与反序列化(JSON 转 Java 对象)时的行为。


为什么需要 @JSONField?它解决了哪些痛点?

在日常开发中,我们经常会遇到以下几个痛点:

  • Java 字段名与前端字段不一致 :前端使用的是 user_name,而 Java 中是 username,映射困难。

  • 时间格式不统一:JSON 默认的时间格式与系统或业务需求不同,需要手动格式化。

  • 字段冗余或安全隐患 :某些字段如 passwordtoken 不能被序列化,但默认会输出。

  • 后端字段更新但兼容老版本前端字段名:需要兼容多个字段名进行反序列化。

@JSONField 注解可以精准控制每一个字段的序列化和反序列化行为,从而有效解决上述问题,提高开发效率并降低出错概率。


一、@JSONField 注解简介

@JSONField 注解是 Fastjson 提供的元注解,位于 com.alibaba.fastjson.annotation.JSONField 包中。它允许开发者在字段或方法上配置特定的序列化/反序列化规则,从而达到灵活控制 JSON 输出和输入的目的。


二、常用属性说明

属性名 类型 说明
name String 指定字段在 JSON 中的名称
format String 指定日期格式,例如 "yyyy-MM-dd HH:mm:ss"
serialize boolean 是否参与序列化,默认 true
deserialize boolean 是否参与反序列化,默认 true
ordinal int 字段排序优先级,值越小越靠前
defaultValue String 反序列化时的默认值
alternateNames String[] 支持反序列化时的多个字段名

三、基本使用示例

1. 重命名字段

java 复制代码
public class User {
    @JSONField(name = "user_name")
    private String username;

    // Getter & Setter
}

输出的 JSON:

java 复制代码
{
  "user_name": "jack"
}

2. 格式化日期字段

java 复制代码
public class Event {
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date createTime;
}

3. 控制字段参与序列化/反序列化

java 复制代码
public class Login {
    @JSONField(serialize = false)
    private String password;

    @JSONField(deserialize = false)
    private String token;
}

4. 使用别名反序列化

java 复制代码
public class Product {
    @JSONField(alternateNames = {"productId", "id"})
    private Long pid;
}

无论 JSON 中是 productId 还是 id,都能正确反序列化为 pid 字段。


四、进阶技巧:搭配方法使用

除了作用在字段上,@JSONField 还可以作用在方法(尤其是 getter/setter)上,控制方法参与序列化与反序列化的行为:

java 复制代码
public class Order {
    private String status;

    @JSONField(name = "order_status")
    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }
}

五、完整代码示例

我们通过一个综合示例类来演示多个 @JSONField 功能的组合使用:

java 复制代码
// JSONFieldDemo.java
package com.example.fastjsondemo;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.annotation.JSONField;

import java.util.Date;

public class JSONFieldDemo {

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

        @JSONField(serialize = false)
        private String password;

        @JSONField(format = "yyyy-MM-dd HH:mm:ss")
        private Date createdAt;

        public User(String username, String password, Date createdAt) {
            this.username = username;
            this.password = password;
            this.createdAt = createdAt;
        }

        public String getUsername() { return username; }
        public void setUsername(String username) { this.username = username; }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = password; }

        public Date getCreatedAt() { return createdAt; }
        public void setCreatedAt(Date createdAt) { this.createdAt = createdAt; }
    }

    public static void main(String[] args) {
        User user = new User("jack", "secret123", new Date());
        String json = JSON.toJSONString(user);
        System.out.println(json);
    }
}

运行输出示例:

java 复制代码
{
  "user_name":"jack",
  "createdAt":"2025-05-06 14:12:33"
}

六、实战注意事项

  1. 优先级问题 :Fastjson 默认使用字段进行序列化,如果字段和 getter 都使用了 @JSONField,字段上的注解优先。

  2. transient 冲突transient 修饰的字段不会被序列化,即使加上了 @JSONField,也需要设置 SerializerFeature.WriteMapNullValue 才可能生效。

  3. 性能优化 :通过设置 ordinal 属性可以控制序列化顺序,从而在某些场景下优化网络传输结构。

  4. 避免与 Jackson 混用:项目中如果同时使用了 Fastjson 和 Jackson,要避免注解混淆导致序列化失效。


七、总结

@JSONField 是 Fastjson 提供的一个功能强大的注解,它允许开发者更灵活地控制对象的 JSON 映射行为。通过合理配置其属性,可以实现字段重命名、日期格式转换、序列化控制等多种功能,在企业级开发中非常实用。

如果你在项目中使用 Fastjson,掌握 @JSONField 的用法将大大提升你对 JSON 数据处理的掌控能力。

相关推荐
先知后行。12 分钟前
QT实现计算器
开发语言·qt
掘根12 分钟前
【Qt】常用控件3——显示类控件
开发语言·数据库·qt
GUIQU.18 分钟前
【QT】嵌入式开发:从零开始,让硬件“活”起来的魔法之旅
java·数据库·c++·qt
西阳未落4 小时前
C++基础(21)——内存管理
开发语言·c++·面试
我的xiaodoujiao4 小时前
Windows系统Web UI自动化测试学习系列2--环境搭建--Python-PyCharm-Selenium
开发语言·python·测试工具
callJJ4 小时前
从 0 开始理解 Spring 的核心思想 —— IoC 和 DI(2)
java·开发语言·后端·spring·ioc·di
wangjialelele4 小时前
Linux中的线程
java·linux·jvm·c++
谷咕咕4 小时前
windows下python3,LLaMA-Factory部署以及微调大模型,ollama运行对话,开放api,java,springboot项目调用
java·windows·语言模型·llama
没有bug.的程序员5 小时前
MVCC(多版本并发控制):InnoDB 高并发的核心技术
java·大数据·数据库·mysql·mvcc
在下村刘湘5 小时前
maven pom文件中<dependencyManagement><dependencies><dependency> 三者的区别
java·maven