بناء الخدمات المصغّرة بـ Spring Boot

التواصل بين الخدمات باستخدام WebClient

18 دقيقة الدرس 3 من 12

التواصل بين الخدمات باستخدام WebClient

بمجرد تشغيل خدمتَين مصغَّرتَين، يصبح من الحتمي أن تتحدّث إحداهما إلى الأخرى عبر HTTP. يُوفّر Spring Boot 3 عميلَين HTTP رسميَّين: الأقدم الحاجب RestTemplate (الذي يُصان حاليًا دون تطوير)، والأحدث غير الحاجب WebClient من Spring WebFlux. حتى لو كانت خدمتك مبنيةً على المكدّس التقليدي القائم على Servlet لا على المكدّس التفاعلي، يظل WebClient الخيارَ الموصى به — إذ يمكن استخدامه بأسلوب تزامني حاجب مع الاحتفاظ بقدر أكبر من الإمكانات والقابلية للاختبار مقارنةً بـ RestTemplate.

لماذا WebClient بدلًا من RestTemplate؟

جاء RestTemplate مع Spring 3.0 وهو تزامني بطبيعته: يحجب كل استدعاء الخيط المُنفِّذ حتى تستجيب الخدمة البعيدة. أعلن فريق Spring أنه في وضع الصيانة منذ Spring 5.0. في المقابل، بُني WebClient من الصفر لعالم غير حاجب، لكنه يدعم الاستدعاءات الحاجبة أيضًا، مما يجعله بديلًا مناسبًا بمجموعة ميزات أفضل:

دعم البث (Streaming) — يمكنه استقبال text/event-stream أو حمولات كبيرة دون تخزينها بالكامل في الذاكرة المؤقتة.
سلسلة فلاتر غنية — تتيح المعترضات (المعروفة بـ ExchangeFilterFunction) إرفاق التسجيل وترويسات المصادقة ومنطق إعادة المحاولة وقواطع الدائرة في مكان واحد.
تفاعلي أو حاجب — استدعِ .block() حين تحتاج نتيجةً متزامنة، واتركه تفاعليًا حين تريد I/O غير حاجب.
دعم مدمج للترميز — تسلسل JSON وفكّه تلقائيًا بواسطة Jackson دون أي شيفرة إضافية.

مكدّس Servlet مقابل مكدّس تفاعلي: لا تحتاج إلى spring-boot-starter-webflux لاستخدام WebClient. أضف spring-boot-starter-web (Servlet) مع spring-webflux كتبعية مباشرة وستحصل على WebClient دون تحويل تطبيقك بالكامل إلى البرمجة التفاعلية.

إضافة التبعية

إذا كانت خدمتك تستخدم بالفعل spring-boot-starter-webflux، فإن WebClient موجود بالفعل في مسار الفئات. أما إذا كنت على مكدّس Servlet فأضف وحدة الويب التفاعلي فقط:

<!-- pom.xml — أضفها إلى جانب spring-boot-starter-web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

إنشاء Bean من WebClient

أنشئ دائمًا مثيلات WebClient عبر الـ Bean المُهيَّأ تلقائيًا WebClient.Builder من Spring Boot. يحمل هذا البنّاء أي ExchangeFilterFunction مسجّلة عالميًا — بما فيها تلك التي يضيفها Spring Cloud للتتبع الموزّع — لذا لا تُنشئ أبدًا WebClient.create() يدويًا في كود الإنتاج.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient inventoryClient(WebClient.Builder builder) {
        return builder
            .baseUrl("http://inventory-service")   // اسم الخدمة المنطقي (يحلّه نظام الاكتشاف)
            .defaultHeader("Accept", "application/json")
            .build();
    }
}

أعلن Bean واحدًا لكل خدمة في اتجاه المصب. استخدام Bean مخصَّص ومُسمَّى بدلًا من واحد مشترك يُبقي عناوين URL الأساسية والترويسات الافتراضية والفلاتر محدودةَ النطاق للخدمة الصحيحة.

تنفيذ طلب GET

يوضّح المثال التالي كيف تستدعي خدمة order-service خدمةَ inventory-service للتحقق من المخزون لمعرّف منتج معيّن.

import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.WebClientResponseException;

@Service
public class InventoryClientService {

    private final WebClient inventoryClient;

    public InventoryClientService(WebClient inventoryClient) {
        this.inventoryClient = inventoryClient;
    }

    public StockResponse checkStock(String productId) {
        return inventoryClient
            .get()
            .uri("/api/inventory/{id}", productId)
            .retrieve()
            .bodyToMono(StockResponse.class)
            .block();                            // استدعاء متزامن
    }
}

شرح السلسلة الطلاقية:

.get() — يبدأ مواصفة طلب GET.
.uri(...) — يُلحق المسار؛ تُوسَّع متغيرات قالب URI بأمان (دون ربط سلاسل، دون خطر حقن).
.retrieve() — يُطلق الطلب ويتيح الوصول إلى جسم الاستجابة. يرمي تلقائيًا WebClientResponseException لرموز الحالة 4xx/5xx.
.bodyToMono(StockResponse.class) — يُفكك جسم JSON إلى DTO الخاص بك باستخدام Jackson.
.block() — يحجب الخيط المُنفِّذ حتى وصول الاستجابة. مقبول في خدمة مبنية على Servlet؛ تجنّبه في خدمة تفاعلية.

تنفيذ طلب POST مع جسم

public OrderConfirmation placeOrder(OrderRequest request) {
    return inventoryClient
        .post()
        .uri("/api/orders")
        .contentType(MediaType.APPLICATION_JSON)
        .bodyValue(request)                     // يُسلسَل إلى JSON تلقائيًا
        .retrieve()
        .bodyToMono(OrderConfirmation.class)
        .block();
}

استخدم .bodyValue() لكائن واحد و.body(BodyInserters.fromValue(...)) حين تحتاج مزيدًا من التحكم (مثل النماذج متعددة الأجزاء). كلاهما يُسلسل بنفس ObjectMapper المُهيَّأ عالميًا في تطبيقك.

معالجة أخطاء HTTP صراحةً

افتراضيًا يُعيّن .retrieve() ردود 4xx إلى WebClientResponseException.BadRequest وردود 5xx إلى WebClientResponseException.InternalServerError. يمكنك اعتراض رموز حالة بعينها وترجمتها إلى استثناءات نطاقية:

public StockResponse checkStock(String productId) {
    return inventoryClient
        .get()
        .uri("/api/inventory/{id}", productId)
        .retrieve()
        .onStatus(HttpStatusCode::is4xxClientError, response ->
            response.bodyToMono(String.class)
                    .map(body -> new ProductNotFoundException("Product not found: " + productId)))
        .onStatus(HttpStatusCode::is5xxServerError, response ->
            Mono.error(new InventoryServiceException("Inventory service is unavailable")))
        .bodyToMono(StockResponse.class)
        .block();
}

إضافة ترويسات المصادقة

في بيئة خدمات مصغَّرة حقيقية، كثيرًا ما تحمل استدعاءات الخدمة-إلى-الخدمة JWT أو مفتاح API داخلي. طبّقه عبر ExchangeFilterFunction حتى يتضمّنه كل طلب من هذا العميل تلقائيًا — دون تكرار بُنية لكل استدعاء:

import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import reactor.core.publisher.Mono;

// داخل WebClientConfig:
@Bean
public WebClient inventoryClient(WebClient.Builder builder) {
    return builder
        .baseUrl("http://inventory-service")
        .filter(serviceTokenFilter())
        .build();
}

private ExchangeFilterFunction serviceTokenFilter() {
    return ExchangeFilterFunction.ofRequestProcessor(request ->
        Mono.just(ClientRequest.from(request)
            .header("X-Service-Token", System.getenv("INTERNAL_SERVICE_TOKEN"))
            .build())
    );
}

لا تُسجّل قيم ترويسة Authorization أو X-Service-Token كاملةً أبدًا. فلاتر تسجيل الطلبات مفيدة للغاية لتنقيح الأخطاء، لكن يجب إخفاء الترويسات الحساسة قبل كتابتها في أي مستودع تسجيل. الرموز التي تظهر في السجلات قابلة للاختراق من قِبَل أي شخص له صلاحية الوصول إليها — وهو مصدر شائع لتسرّب بيانات الاعتماد في بيئات الخدمات المصغَّرة.

المهل الزمنية — شبكة أمان أساسية

دون مهل زمنية، ستُبقي خدمة مصب بطيئة خيطَك (أو اشتراكك) معلّقًا إلى أجل غير مسمى، مما يستنزف تجمعات الاتصال في نهاية المطاف ويُولّد انهيارًا متسلسلًا على مستوى النظام. اضبط دائمًا مهلةً للاتصال وأخرى للقراءة:

import io.netty.channel.ChannelOption;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import reactor.netty.http.client.HttpClient;

import java.time.Duration;

@Bean
public WebClient inventoryClient(WebClient.Builder builder) {
    HttpClient httpClient = HttpClient.create()
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000)   // ثانيتان لإنشاء TCP
        .responseTimeout(Duration.ofSeconds(5));               // 5 ثوانٍ لاستقبال الاستجابة كاملةً

    return builder
        .baseUrl("http://inventory-service")
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();
}

قاعدة إبهام شائعة في الإنتاج: اضبط مهلة الاتصال قصيرة (1 إلى 3 ثوانٍ) ومهلة الاستجابة بما لا يتجاوز اتفاقية مستوى الخدمة التي تريد ضمانها لمُستدعييك. إذا وعدت خدمة المخزون بزمن استجابة p99 مدته ثلاث ثوانٍ، فيجب أن تكون مهلتك 4 إلى 5 ثوانٍ لتمنحها هامشًا مع الفشل السريع في الوقت ذاته.

الخلاصة

WebClient هو الأداة المعيارية للتواصل بين الخدمات عبر HTTP في Spring Boot 3. احصل عليه عبر الـ WebClient.Builder المُهيَّأ تلقائيًا، وخصّص Bean واحدًا لكل خدمة في اتجاه المصب، واستخدم قوالب URI لتجنب مخاطر الحقن، وترجم رموز أخطاء HTTP إلى استثناءات نطاقية بـ .onStatus()، وأرفق رموز المصادقة عبر ExchangeFilterFunction، واضبط دائمًا مهلتَي اتصال واستجابة صريحتَين. في الدرس القادم ستتعلم كيف يتيح لك OpenFeign التعبير عن الاستدعاءات ذاتها كواجهة تعريفية بشيفرة أقل بكثير.