วิธีใช้ @Since annotation ด้วย Gson ใน Java

คำอธิบายประกอบ @Since ใช้ร่วมกับเมธอด setVersion() ของคลาส GsonBuilder Annotation นี้วางได้ที่ฟิลด์ใน Java class และรับค่า float เป็น argument ค่านี้แทน version number ที่ฟิลด์นั้นถูก serialize แรกครั้ง กระบวนการ deserialize ทำงานในลักษณะเดียวกัน

Syntax

@Documented
@Retention(value=RUNTIME)
@Target(value={FIELD, TYPE})
public @interface Since

ตัวอย่างการใช้งาน

import com.google.gson.annotations.Since;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class GsonSinceAnnotationTest {
    public static void main(String[] args) {
        Employee emp = new Employee();
        emp.setEmployeeName("Raja Ramesh");
        emp.setEmployeeId(125);
        emp.setEmployeeTechnology("Java");
        emp.setEmploeeAddress("Hyderabad");
        
        System.out.println("Since version 0.5");
        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder.setPrettyPrinting().setVersion(0.5).create();
        String jsonString = gson.toJson(emp);
        System.out.println(jsonString);
        
        System.out.println("Since version 1.0");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
        
        System.out.println("Since version 1.1");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.1).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
    }
}

// Employee class
class Employee {
    private String empName;
    private int empId;
    
    @Since(1.0)
    private String empTech;
    
    @Since(1.1)
    private String empAddress;
    
    // getters และ setters...
}

ผลลัพธ์ (Output)

Since version 0.5
{
  "empName": "Raja Ramesh",
  "empId": 125
}

Since version 1.0
{
  "empName": "Raja Ramesh",
  "empId": 125,
  "empTech": "Java"
}

Since version 1.1
{
  "empName": "Raja Ramesh",
  "empId": 125,
  "empTech": "Java",
  "empAddress": "Hyderabad"
}

คำอธิบาย

เมื่อตั้ง version = 0.5 ฟิลด์ที่มี @Since(1.0) และ @Since(1.1) จะไม่ถูก serialize เพราะ version ปัจจุบันต่ำกว่า เมื่อ version เพิ่มขึ้น ฟิลด์ใหม่จะถูกเพิ่มเข้ามาใน JSON output

กรณีการใช้งาน (Use Cases)

• API Versioning - ควบคุมฟิลด์ที่แสดงตาม API version
• Backward Compatibility - เพิ่มฟิลด์ใหม่โดยไม่ทำลาย client เก่า
• Feature Flags - เปิด/ปิดฟิลด์ตาม version
• Data Migration - จัดการ schema evolution

สรุป

@Since annotation ใน Gson เป็นเครื่องมือที่ทรงพลังสำหรับ API versioning และ schema evolution ช่วยให้ควบคุมฟิลด์ที่ serialize/get ตาม version ได้อย่างง่ายดาย