Gson لجافا: دليل شامل مع أمثلة

ما هو Gson ولماذا نحتاجه؟

\n\n

Gson هي مكتبة قوية للغة جافا، طورتها شركة Google، تتيح تحويل كائنات جافا إلى تمثيل JSON الخاص بها (التسلسل)، والعكس، استعادة كائنات جافا من سلاسل JSON (إلغاء التسلسل). JSON (JavaScript Object Notation) هو تنسيق خفيف لتبادل البيانات يُستخدم على نطاق واسع في واجهات برمجة تطبيقات الويب، وملفات التكوين، وتخزين البيانات المنظمة.

\n\n

لماذا نستخدم Gson؟ في تطوير تطبيقات جافا الحديثة، لا يكاد يخلو أي مشروع من العمل مع JSON. سواء كان التواصل مع REST API، أو قراءة التكوينات، أو تبادل البيانات بين الخدمات المصغرة — يوفر Gson طريقة بسيطة وسريعة وموثوقة للتحويل. على عكس المكتبة القياسية لجافا (org.json)، يمكن لـ Gson العمل مباشرة مع كائنات جافا العشوائية (POJO)، مطابقة حقول الفئة تلقائيًا مع مفاتيح JSON. هذا يريح المطور من التحليل اليدوي وكتابة الكود النمطي.

\n\n

تثبيت Gson

\n\n

Gson هي مكتبة جافا، لذا يتم توزيعها من خلال أنظمة إدارة التبعيات لـ JVM. فيما يلي طرق التثبيت لأدوات البناء الأكثر شيوعًا.

\n\n

Maven

\n

أضف التبعية التالية إلى ملف pom.xml الخاص بك:

\n

<dependency>\n    <groupId>com.google.code.gson</groupId>\n    <artifactId>gson</artifactId>\n    <version>2.10.1</version> <!-- تحقق من أحدث إصدار على Maven Central -->\n</dependency>

\n\n

Gradle

\n

أضف إلى ملف build.gradle:

\n

implementation 'com.google.code.gson:gson:2.10.1'

\n\n

تنزيل JAR مباشر

\n

إذا كنت لا تستخدم أنظمة البناء، قم بتنزيل ملف JAR من Maven Central وأضفه إلى classpath لمشروعك.

\n\n

هام: على عكس Python (pip) أو Node.js (npm)، لا يوجد في جافا مدير حزم واحد. Maven و Gradle هما المعيار الفعلي.

\n\n

بداية سريعة: المثال الأول

\n\n

لنقم بإنشاء فئة بسيطة Person وتسلسلها إلى JSON، ثم إلغاء تسلسلها مرة أخرى.

\n\n

import com.google.gson.Gson;\n\npublic class QuickStart {\n    public static void main(String[] args) {\n        // 1. إنشاء كائن\n        Person person = new Person("إيفان", 30, "ivan@example.com");\n\n        // 2. إنشاء مثيل من Gson\n        Gson gson = new Gson();\n\n        // 3. التسلسل (جافا -> JSON)\n        String json = gson.toJson(person);\n        System.out.println("JSON: " + json);\n        // الإخراج: JSON: {"name":"إيفان","age":30,"email":"ivan@example.com"}\n\n        // 4. إلغاء التسلسل (JSON -> جافا)\n        String jsonInput = "{\\"name\\":\\"ماريا\\",\\"age\\":25,\\"email\\":\\"maria@test.com\\"}";\n        Person personFromJson = gson.fromJson(jsonInput, Person.class);\n        System.out.println("الاسم: " + personFromJson.getName());\n        // الإخراج: الاسم: ماريا\n    }\n}\n\nclass Person {\n    private String name;\n    private int age;\n    private String email;\n\n    // يجب وجود مُنشئ افتراضي (بدون وسائط) لإلغاء التسلسل!\n    public Person() {}\n\n    public Person(String name, int age, String email) {\n        this.name = name;\n        this.age = age;\n        this.email = email;\n    }\n\n    public String getName() { return name; }\n    public int getAge() { return age; }\n    public String getEmail() { return email; }\n}

\n\n

الطرق والوظائف الأساسية لـ Gson

\n\n

فيما يلي الطرق الرئيسية لمكتبة Gson. كل طريقة مصحوبة بوصف ومثال عملي.

\n\n

1. Gson.toJson(Object src)

\n

ما تفعله: تسلسل كائن جافا المُمرر إلى سلسلة JSON. هذه هي الطريقة الأساسية لتحويل كائن إلى JSON.

\n