بناء واجهات REST مع Spring Boot

التفاوض على المحتوى وجاكسون

18 دقيقة الدرس 8 من 13

التفاوض على المحتوى وجاكسون

في كل مرة يُعيد فيها مُتحكم REST في Spring Boot كائن Java، تحتاج إلى شيء يحوّله إلى بايتات عبر الشبكة. هذا الشيء هو جاكسون (Jackson) — مكتبة JSON التي تُهيّئها Spring Boot تلقائيًا فور إضافة spring-boot-starter-web. إن فهم كيفية قيام جاكسون بتسلسل كائنات Java وإلغاء تسلسلها، وكيفية توجيهه لتلبية احتياجات واجهة برمجية بعينها، مهارةٌ ستستخدمها في كل مشروع.

ما هو التفاوض على المحتوى؟

التفاوض على المحتوى هو آلية HTTP التي يتفق بموجبها العميل والخادم على تنسيق الاستجابة. يعبّر العميل عن تفضيله عبر ترويسة الطلب Accept (مثل Accept: application/json أو Accept: application/xml). يختار الخادم أفضل تنسيق يمكنه إنتاجه ويُعلنه في ترويسة الاستجابة Content-Type.

تجلس ContentNegotiationManager الخاصة بـ Spring MVC أمام كل دالة @RestController. تفحص ترويسة Accept، وتُعدّد حبّات HttpMessageConverter المسجلة في سياق التطبيق، وتختار المحوّل القادر على معالجة نوع الإعادة وإنتاج نوع الوسائط المطلوب. يتعامل محوّل جاكسون MappingJackson2HttpMessageConverter مع application/json (وapplication/*+json). إن لم يتطابق أي محوّل، يُعيد Spring 406 Not Acceptable.

السلوك الافتراضي في Spring Boot: مع وجود spring-boot-starter-web فقط في مسار الفئات، يكون JSON هو التنسيق الوحيد المُهيَّأ تلقائيًا. تؤدي إضافة jackson-dataformat-xml إلى تفعيل التفاوض على XML بجانب JSON بشفافية تامة — دون أي إعداد إضافي.

كيف يُسلسل جاكسون كائن Java

تتجوّل ObjectMapper الخاصة بجاكسون عبر كائن Java بالتعكيس (أو عبر توليد كود بايت في الإصدارات الحديثة) وتُصدر JSON. افتراضيًا تتضمّن كل دالة getter عامة كحقل JSON، باستخدام اسم الخاصية المستنبط من اسم دالة الـ getter. فالدالة getUserName() تصبح "userName" في المخرج.

لنتأمل هذا الكيان:

package com.example.api.model;

import java.time.LocalDate;
import java.util.List;

public class Employee {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;
    private LocalDate hireDate;
    private List<String> roles;

    // دوال getter و setter القياسية ...
}

يُنتج مُتحكم يُعيد Employee افتراضيًا:

{
  "id": 42,
  "firstName": "Leila",
  "lastName": "Nasser",
  "email": "leila@example.com",
  "hireDate": [2023, 3, 15],
  "roles": ["DEVELOPER", "REVIEWER"]
}

لاحظ أن hireDate تظهر كمصفوفة. هذا هو السلوك الافتراضي لجاكسون مع java.time.LocalDate — وهو ما لا تريده في الغالب. الحل موضّح في الأسفل.

تعليقات جاكسون التي ستستخدمها يوميًا

@JsonProperty — تجاوز مفتاح JSON لحقل واحد:

@JsonProperty("first_name")
private String firstName;

@JsonIgnore — استبعاد حقل من التسلسل وإلغاء التسلسل معًا:

@JsonIgnore
private String passwordHash;

@JsonInclude — حذف الحقول ذات القيمة null (أو المجموعات الفارغة) من المخرج للإبقاء على الاستجابات خفيفة:

import com.fasterxml.jackson.annotation.JsonInclude;

@JsonInclude(JsonInclude.Include.NON_NULL)
public class ApiResponse<T> {
    private T data;
    private String error;   // تُحذف عند كونها null
    private String message;
}

@JsonFormat — التحكم في طريقة تسلسل التواريخ والأرقام:

import com.fasterxml.jackson.annotation.JsonFormat;

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private LocalDate hireDate;

الآن تظهر hireDate كـ "2023-03-15" بدلًا من المصفوفة. هذا هو الحل الأكثر شيوعًا لمشاكل التواريخ.

@JsonNaming — تطبيق استراتيجية تسمية على جميع خصائص فئة دفعةً واحدة دون الحاجة لتعليق كل حقل على حدة:

import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import com.fasterxml.jackson.databind.annotation.JsonNaming;

@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
public class Employee {
    private String firstName;   // تُسلسَل كـ "first_name"
    private String lastName;    // تُسلسَل كـ "last_name"
}

إعداد جاكسون عالميًا عبر `application.properties`

يمكن تفعيل معظم إعدادات جاكسون أو إيقافها عبر فضاء الخاصية spring.jackson.* في Spring Boot، مما يُغني عن كتابة أي إعداد Java:

# application.properties

# استخدام snake_case لجميع أسماء الخصائص عالميًا
spring.jackson.property-naming-strategy=SNAKE_CASE

# حذف الحقول ذات القيمة null من كل جسم استجابة
spring.jackson.default-property-inclusion=non_null

# تسلسل LocalDate/LocalDateTime كنصوص ISO لا كمصفوفات
spring.jackson.serialization.write-dates-as-timestamps=false

# تنسيق المخرج لسهولة القراءة (أوقفه في الإنتاج لتقليص حجم البيانات)
spring.jackson.serialization.indent-output=true

# عدم الفشل عند وجود حقل في JSON لا يوجد في فئة Java
# (آمن للواجهات البرمجية المتوافقة مع الأمام)
spring.jackson.deserialization.fail-on-unknown-properties=false

فضّل application.properties للإعدادات العالمية. تُخصَّص التجاوزات على مستوى التعليقات (@JsonFormat، @JsonProperty) للاستثناءات من تلك السياسة العالمية. هذا يُبقي فئات النطاق نظيفة ويُمركز استراتيجية التسلسل في مكان واحد سهل المراجعة والتغيير.

تسجيل حبّة `ObjectMapper` مخصصة

حين تحتاج إلى تحكم برمجي — تسجيل مُسلسِل مخصص، أو تفعيل ميزة لا تقابلها خاصية، أو إعداد JavaTimeModule يدويًا — أعلن عن حبّة ObjectMapper (أو Jackson2ObjectMapperBuilder):

package com.example.api.config;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        // تسجيل الموديول الذي يُعالج أنواع java.time
        mapper.registerModule(new JavaTimeModule());
        // كتابة التواريخ كنصوص ISO لا كطوابع زمنية
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
}

تتراجع الإعداد التلقائي لـ Spring Boot حين تكتشف حبّة ObjectMapper في السياق. تحلّ حبّتك محلّ الحبّة الافتراضية كليًا، لذا تأكد من إعادة تطبيق أي إعداد كنت تعتمده ضمنيًا (مثل تسجيل JavaTimeModule لدعم java.time).

كتابة مُسلسِل مخصص

أحيانًا تحتاج إلى منطق تسلسل لا يمكن لأي تعليق التعبير عنه — كتنسيق BigDecimal كسلسلة عملة، أو إخفاء جزء من حقل حساس. امتد من JsonSerializer<T>:

package com.example.api.serializer;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import java.io.IOException;
import java.math.BigDecimal;

public class CurrencySerializer extends JsonSerializer<BigDecimal> {

    @Override
    public void serialize(BigDecimal value,
                          JsonGenerator gen,
                          SerializerProvider provider) throws IOException {
        // دائمًا يُصدر منزلتين عشريتين: 1500 -> "1500.00"
        gen.writeString(value.setScale(2, java.math.RoundingMode.HALF_UP).toPlainString());
    }
}

سجّله على الحقل:

import com.fasterxml.jackson.databind.annotation.JsonSerialize;

@JsonSerialize(using = CurrencySerializer.class)
private BigDecimal salary;

التحكم في إلغاء التسلسل: التعامل مع الحقول المجهولة

افتراضيًا يرمي جاكسون UnrecognizedPropertyException حين يحتوي جسم JSON الوارد على حقل لا تُعلنه فئة DTO. هذا آمن لكنه هش — فهو يكسر واجهتك البرمجية في كل مرة يرسل فيها عميل حمولة أحدث. النهج الجاهز للإنتاج هو تجاهل الحقول المجهولة عالميًا:

# application.properties
spring.jackson.deserialization.fail-on-unknown-properties=false

أو على مستوى الفئة لـ DTO محددة:

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class CreateEmployeeRequest {
    private String firstName;
    private String lastName;
    private String email;
}

لا تستخدم فئات كيانات JPA مباشرةً كأجسام طلب أو استجابة. تعريض الكيانات يُقرن عقد واجهتك البرمجية بمخطط قاعدة بياناتك. استخدم بدلًا من ذلك فئات DTO مخصصة (مثل CreateEmployeeRequest وEmployeeResponse) وطابق بينها. هذا يحمي من ثغرات الإسناد الجماعي ويتيح تطور مخططك باستقلالية عن سطح واجهتك البرمجية.

الخلاصة

تُوصّل Spring Boot جاكسون كمحرك JSON افتراضي لجميع مُتحكمات REST. تتحكم في مخرجاته على ثلاثة مستويات: عالميًا عبر خصائص spring.jackson.*، وعلى مستوى الفئة عبر تعليقات كـ @JsonNaming و@JsonInclude، وعلى مستوى الحقل عبر @JsonProperty و@JsonIgnore و@JsonFormat والمُسلسِلات المخصصة. استخدم دائمًا فئات DTO مخصصة بدلًا من تعريض كيانات JPA، وأعدّ write-dates-as-timestamps=false للحصول على تواريخ ISO مقروءة، وأوقف fail-on-unknown-properties لعقد واجهة برمجية أكثر مرونة. في الدرس القادم ستطبّق هذه المهارات على إصدار الواجهات البرمجية وأفضل ممارسات REST.

التفاوض على المحتوى وجاكسون

التفاوض على المحتوى وجاكسون

ما هو التفاوض على المحتوى؟

كيف يُسلسل جاكسون كائن Java

تعليقات جاكسون التي ستستخدمها يوميًا

إعداد جاكسون عالميًا عبر application.properties

تسجيل حبّة ObjectMapper مخصصة

كتابة مُسلسِل مخصص

التحكم في إلغاء التسلسل: التعامل مع الحقول المجهولة

الخلاصة

إعداد جاكسون عالميًا عبر `application.properties`

تسجيل حبّة `ObjectMapper` مخصصة