اختبارات العقود لتطبيق قائم على الأحداث باستخدام Kafka وSpring Cloud Contract
تعرض هذه المقالة كيفية استخدام Spring Cloud Contract للتحقق من الاتصال غير المتزامن بين الخدمات المصغّرة التي تعتمد على Kafka وسيطًا للرسائل.
عرضتُ سابقًا كيفية كتابة اختبارات العقود للاتصال المتزامن عبر واجهة REST API. وهذه حالة بسيطة وشائعة إلى حد كبير، وأغلب مقالات اختبار العقود على الإنترنت تعتمد عليها. أما العثور على إرشادات حول اختبار الاتصال غير المتزامن المبني على وسيط رسائل فهو أصعب بكثير.
سأستعرض هنا اختبار الاتصال غير المتزامن القائم على الأحداث الذي يستخدم Kafka وسيطًا للرسائل. ستحتاج إلى إلمام أساسي بـ Kafka لمتابعة الشرح، لأن وصف طريقة عمله يتجاوز نطاق هذه المقالة. لذا إن كان Kafka جديدًا عليك، فأنصحك بالتعرف على مفاهيمه الأساسية أولًا.
وإذا كنت مهتمًا بمعرفة كيف يدعم Kafka والعمارة القائمة على الأحداث تطوير الأنظمة الموزّعة، فأنصحك بالمقالة التالية.
تدور الأجزاء السابقة من هذه السلسلة حول طلب في منصة تجارة إلكترونية يُدفع تلقائيًا. هناك خدمتان، order-service وpayment-service، تتحدثان إلى بعضهما عبر REST API – إذ يستدعي order-service واجهة payment-service. في هذا الجزء عكستُ الاعتماديات لأبيّن كيف يمكن تنفيذ حالة الاستخدام نفسها بأسلوب قائم على الأحداث. أصبح order-service الآن يعلن عن إنشاء الطلب بإصدار حدث يصل إلى موضوع (topic) في Kafka. وpayment-service أحد المشتركين في هذا الموضوع، ويبدأ عملية دفع لكل طلب.
من منظور اختبار العقود، يجعل هذا التغيير order-service هو المنتِج (producer) وpayment-service هو المستهلِك (consumer). ولتبسيط الأمور، تُسلسَل الأحداث بصيغة JSON. يحمل كل حدث بيانات وصفية (eventId ووقت وقوعه) إلى جانب تفاصيل الطلب الذي أُنشئ.
{
"eventId": "9c465a8f-bf77-4f3a-b357-d760ced8b26f",
"occuredAt": "2023-12-02T13:00:00",
"orderId": "59404950-bc8d-4722-a521-0dee64b680d6",
"accountId": "5c2c2407-7202-4720-9a45-f0d0f8175ef1",
"total": 120.8
}
يشرح هذا الدليل كيف يمكن اختبار هذا النوع من الاتصال باستخدام Spring Cloud Contract. وكما في اختبار REST API، فإن الخطوة الأولى هي تعريف العقد.
تعريف العقد
يمكن التعبير عن العقد بلغة DSL التي يوفرها Spring Cloud Contract، وتُكتب بـ Java أو Kotlin أو Groovy أو Yaml. فيما يلي عقد Groovy للحدث OrderCreated الذي يصدره order-service:
Contract.make {
description("Should produce OrderCreated event when order was created")
input {
triggeredBy("createOrder()")
}
label("triggerOrderCreatedEvent")
outputMessage {
sentTo("OrderCreated")
body([
eventId: anyUuid(),
occurredAt: anyDateTime(),
orderId: anyUuid(),
accountId: anyUuid(),
total: $(consumer(regex("(\\d+\\.\\d+)")))
])
}
}
كما ترى، يختلف قليلًا عن عقد REST API. وهذا متوقع، لأن هذا النوع من الاتصال يتبع قواعد مختلفة. لا يوجد خادم يعالج طلبات المستهلِك، بل يصدر المنتِج (هنا order-service) حدثًا نتيجةً لعملية أعمال. ولهذا يجب أن يحفّزه الاختبار بطريقة ما. يحدد قسم input ما الذي يتسبب في إرسال الرسالة – وهو في حالتنا الدالة createOrder(). وتستفيد الاختبارات المولّدة منه، كما سترى لاحقًا.
وفي جانب المستهلِك نحتاج أيضًا إلى وسيلة لتحفيز تسليم الرسالة إلى مستهلِك Kafka. تتولى الدالة label ذلك. سمّيتُ التسمية triggerOrderCreatedEvent، وستحتاج إلى معرفتها عند كتابة اختبارات المستهلِك.
أخيرًا، يصف قسم outputMessage وجهة الرسالة ومحتواها. تنص الدالة sentTo() على أن الرسالة تُرسل إلى الموضوع OrderCreated. وتعلن الدالة body() أن جسم الرسالة ينبغي أن يحتوي على 5 حقول من الأنواع المحددة. وكما في المقالة عن اختبار REST API، لا نضع هنا قيمًا فعلية للحقول. بل نحدد أن eventId وorderId وaccountId يجب أن تحمل أي UUID صالح، وأن occurredAt (وقت وقوع الحدث) يجب أن تكون قيمة تاريخ ووقت، وأن total يجب أن تكون عددًا عشريًا موجبًا.
يوضع العقد في /src/contractTest/resources، ويمكن استخدام مجلدات فرعية لتجميع العقود حسب المستهلِك. هنا order-service هو المنتِج، لذا توجد عقوده في هذا المشروع ضمن المجلد
order-service/src/contractTest/resources/contracts/paymentService.
اختبار المنتِج
يتطلب توليد الاختبارات والمحاكيات (stubs) من العقد وتشغيل اختبارات المنتِج وجود اعتمادية Spring Cloud Contract والإضافة (plugin) الخاصة به.
plugins {
id 'org.springframework.cloud.contract' version '4.0.0'
}
dependencies {
testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-verifier:4.0.0'
}
للاختصار، تركتُ الاعتماديات والإضافات الأخرى اللازمة لتشغيل الاختبارات، مثل Spring Boot Test أو Spring Kafka. وفي ملف build.gradle الخاص بـ Gradle أضفتُ أيضًا الحد الأدنى من الإعدادات التي يحتاجها الإطار:
contracts {
baseClassForTests = "pl.rmaciak.payment.BaseContractTestsSpec"
testFramework = "SPOCK"
}
يحدد هذا أن الاختبارات المولّدة ستُكتب بـ Spock، والأهم أنها سترث الصنف الأساسي BaseContractTestsSpec. ويستحق هذا الصنف نظرة أقرب.
عند اختبار REST API، يشغّل الصنف الأساسي الخادم (أو خادمًا وهميًا) الذي تُجرى عليه الاختبارات. هناك يكون الخادم هو المنتِج الذي يعرض REST API، وتتحقق الاختبارات من أن هذه الواجهة تلبي المتطلبات الواردة في العقود. أما في الحالات القائمة على الأحداث فالأمر مختلف. المنتِج لا يعرض أي واجهة؛ بل ينشر رسالة إلى وسيط Kafka. وعلى الاختبارات أن تتحقق من أن هذه الرسالة تلبي المتطلبات المنصوص عليها في العقود. لذلك نحتاج إلى اعتراض الرسالة المرسلة إلى الوسيط والتحقق منها مقابل العقود.
توجد عدة طرق لاعتراض الرسالة. أحدها تشغيل الوسيط داخل حاوية Docker باستخدام Testcontainers مع صورة Kafka. يطلق اختبار العقد الوظيفة التي تصدر الحدث، فيذهب الحدث إلى الموضوع المناسب في وسيط Kafka الذي بدأ للتو وعمره قصير. وهذا هو جوهر ما يتولاه الصنف BaseContractTestsSpec.
@SpringBootTest(webEnvironment = NONE, classes = [OrderApplication.class])
@AutoConfigureMessageVerifier
@Testcontainers
abstract class BaseContractTestsSpec extends Specification {
@Shared
static KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:latest"))
@Autowired
private OrderCreator orderCreator
@DynamicPropertySource
static void kafkaProperties(DynamicPropertyRegistry registry) {
kafka.start()
registry.add("spring.kafka.bootstrap-servers", () -> kafka.getBootstrapServers())
}
void createOrder() {
orderCreator.createOrder(
UUID.randomUUID(),
UUID.randomUUID(),
BigDecimal.valueOf(120.8)
)
}
}
يعلن الصنف عن حاوية Kafka مبنية على أحدث صورة من النسخة المجتمعية لـ Kafka من Confluent (الحقل kafka). تبدأ الحاوية في الدالة المعلَّمة بـ @DynamicPropertySource، التي توجّه أيضًا الخاصية spring.kafka.bootstrap-server إلى العنوان الذي تعرضه الحاوية. بفضل ذلك يستطيع Spring نشر الأحداث واستهلاكها عبر الوسيط العامل داخل الحاوية. أما الدالة createOrder() فهي التي سُمّيت في العقد مُحفِّزًا. وكل ما تفعله هو تشغيل منطق إنشاء الطلب عبر OrderCreator المحقون، فينتج عن ذلك نشر الحدث.
بتنفيذ BaseContractTestsSpec على هذا النحو، يكتفي منطق الخدمة بنشر الرسائل إلى نسخة Kafka العاملة في الحاوية. ما ينقصنا بعد هو وسيلة لاستقبال الرسالة والتحقق منها مقابل العقد. وهذا ما يتولاه Message Verifier. لاحظ التعليق التوضيحي @AutoConfigureMessageVerifier على الصنف – فهو يُعدّ ويضبط الـ beans التي يستخدمها Spring Cloud Contract للتحقق من الرسائل. يأتي الإطار بعدد من أدوات التحقق الجاهزة لـ JMS وApache Camel وSpring Integration وغيرها. للأسف لا توجد أداة تستهدف وسطاء Kafka، لذا علينا كتابة واحدة بأنفسنا.
يوفّر Spring Cloud Contracts الواجهة MessageVerifierReceiver التي يتيح تنفيذها للاختبار استقبال الرسائل من Kafka. وهي تعلن عن دالتين receive() متحمّلتين للتحميل الزائد (overloaded)، وكلتاهما تعيد الواجهة Message من Spring Messaging. يتحقق Spring Cloud Contract من تلك الرسالة مقابل العقد. ولجلب الرسالة من الوسيط يمكننا كتابة مستهلِك للاختبار – وهو في هذا المثال يخزّن الرسائل في مجموعة (set). يستمع فقط إلى الموضوع OrderCreated، لذا لن يلتقط حدثًا أُرسل إلى وجهة خاطئة وسيفشل الاختبار. تأخذ الدالتان receive() رسالة من تلك المجموعة وتعيدها إن وُجدت. وبطبيعة الحال قد يستغرق استهلاك الرسائل بعض الوقت، لذا يتكرر الفحص كل بضع ثوانٍ.
class KafkaEventVerifier implements MessageVerifierReceiver<Message<?>> {
private final Set<Message> consumedEvents = Collections.synchronizedSet(new HashSet<Message>())
@KafkaListener(topics = ["OrderCreated"], groupId = "order-consumer")
void consumeOrderCreated(ConsumerRecord payload) {
consumedEvents.add(MessageBuilder.createMessage(payload.value(), new MessageHeaders(emptyMap())))
}
@Override
Message receive(String destination, long timeout, TimeUnit timeUnit, @Nullable YamlContract contract) {
for (int i = 0; i < timeout; i++) {
Message msg = consumedEvents.stream().findFirst().orElse(null)
if (msg != null) {
return msg
}
timeUnit.sleep(1)
}
return consumedEvents.stream().findFirst().orElse(null)
}
@Override
Message receive(String destination, YamlContract contract) {
return receive(destination, 5, SECONDS, contract)
}
}
تبدو معمارية هذا الأسلوب على النحو التالي:
لدينا الآن كل ما نحتاجه للتحقق من الرسالة. تُنشر الرسالة إلى Kafka ويلتقطها المتحقق الخاص بنا. ثم يأخذ Spring Cloud Contract الرسالة المستهلَكة ويفحص مطابقتها لما تتوقعه العقود. يحدث هذا في الاختبارات المولّدة التي ينتجها الإطار عند بناء التطبيق. يمكنك توليدها بالأمر التالي:
./gradlew check
وهذا هو الاختبار المولَّد من عقدنا:
@SuppressWarnings("rawtypes")
class PaymentServiceSpec extends BaseContractTestsSpec {
@Inject ContractVerifierMessaging contractVerifierMessaging
@Inject ContractVerifierObjectMapper contractVerifierObjectMapper
def validate_shouldProduceOrderCreatedEvent() throws Exception {
when:
createOrder()
then:
ContractVerifierMessage response = contractVerifierMessaging.receive("OrderCreated",
contract(this, "shouldProduceOrderCreatedEvent.yml"))
response != null
and:
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()))
assertThatJson(parsedJson).field("['eventId']").matches("[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}")
assertThatJson(parsedJson).field("['occurredAt']").matches("([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])")
assertThatJson(parsedJson).field("['orderId']").matches("[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}")
assertThatJson(parsedJson).field("['accountId']").matches("[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}")
assertThatJson(parsedJson).field("['total']").matches("(\\d+\\.\\d+)")
}
}
يرث صنف الاختبار الصنف BaseContractTestsSpec لدينا، ويستدعي قسم when فيه الدالة المحفِّزة createOrder() فقط. ونتيجة لذلك تُنشر الرسالة إلى وسيط Kafka ثم يجلبها مستهلِكنا، فتعيدها الدالة receive() في قسم then في النهاية. وفي الختام يُتحقق من كل حقل في الرسالة. يقع الاختبار في المجلد build/generated-test-sources.
تتحقق هذه المرحلة من الاختبار مما إذا كانت رسالة صالحة قد وصلت إلى الموضوع الصحيح في وسيط Kafka. وعندما تنجح الاختبارات يمكننا الاطمئنان إلى أن الرسالة تلبي ما يتوقعه العقد. صحيح أنك تضطر إلى كتابة بعض الشيفرة، ومعظم ذلك لأن Kafka تفتقر إلى أداة تحقق مدمجة. ومع ذلك فهذه الشيفرة عامة إلى حد كبير ويسهل توسيعها لتغطي أحداثًا أخرى أيضًا.
اختبار المستهلِك
في اختبارات عقود REST API، كان بناء التطبيق ينتج محاكيات Wiremock تعكس افتراضات العقد، وكان بإمكان اختبارات المستهلِك استخدامها. أما الاتصال القائم على الأحداث عبر وسيط رسائل فلا يتضمن اتصال HTTP مباشرًا بين المنتِج والمستهلِك. بل يعتمد على رسائل تُنشر إلى وسيط يقع بين الخدمتين وتُستهلك منه. لذلك فإن اختبار المستهلِك يعني في الحقيقة التحقق مما إذا كان قادرًا على فهم الحدث الذي أصدره المنتِج ومعالجته.
وبما أن المستهلِك يستهلك الأحداث، فهو يطبّق عادةً مستمعًا للأحداث (event listener). نريد في الاختبار أن نتأكد من أن رسالة تتبع قواعد العقد تُستهلك وتُعالج بشكل صحيح. ولهذا علينا إرسال رسالة نموذجية إلى Kafka ليلتقطها المستهلِك ويعالجها. في حالتنا، payment-service هو المستهلِك، ويستهلك الأحداث القادمة من order-service.
ولإنشاء رسالة مطابقة للعقد ونشرها، يجب أن نعرف شكلها. ولهذا فإن ملف JAR المبني للمنتِج لا يحتوي على محاكيات Wiremock بل على العقد نفسه – وهو العقد الذي عرّفناه في جانب المنتِج تمامًا. وهو يخبرنا بما يلي:
- أين يذهب الحدث (الموضوع)
- كيف تُبنى الرسالة
- ما الذي يتسبب في إرسال الرسالة
يُحزَّم العقد في ملف JAR يوجد في المجلد build/libs (order-service-0.0.1-SNAPSHOT-stubs.jar). ويمكن دفع ملف JAR مثلًا إلى مستودع Maven المحلي (المجلد .m2). وبوجود العقد بين أيدينا يمكننا كتابة اختبارات تتحقق من منطق payment-service. وللتذكير، ينبغي لهذه الخدمة أن تبدأ عملية دفع كلما وصل حدث OrderCreated.
يتطلب اختبار ذلك أيضًا وسيط Kafka، ومرة أخرى نشغّل Kafka حاوية Docker باستخدام Testcontainers. يحتاج إرسال الرسالة النموذجية إلى الوسيط إلى أمرين:
- تعريف الرسالة (العقد المخزَّن في ملف JAR)
- وسيلة لإرسال الرسالة إلى الوسيط. وكما سبق، ليس في Kafka آلية مدمجة لذلك، لذا علينا كتابتها بأنفسنا.
وهذا صنف الاختبار مع سيناريو اختبار واحد:
@SpringBootTest(webEnvironment = NONE, classes = [PaymentApplication.class, TestConfiguration.class])
@AutoConfigureStubRunner(ids = ["com.rmaciak:order-service:0.0.1-SNAPSHOT:stubs:8088"], stubsMode = LOCAL)
@Testcontainers
class EventHandlerSpec extends Specification {
@Shared
static KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:latest"))
@Autowired
PaymentRepository paymentRepository
@Autowired
StubTrigger stubTrigger
@DynamicPropertySource
static void kafkaProperties(DynamicPropertyRegistry registry) {
kafka.start()
registry.add("spring.kafka.bootstrap-servers", () -> kafka.getBootstrapServers())
}
def "should initiate payment on OrderCreatedEvent"() {
given:
def conditions = new PollingConditions(timeout: 10, initialDelay: 1.5, factor: 1.25)
when:
stubTrigger.trigger("triggerOrderCreatedEvent")
then:
conditions.eventually {
def payments = paymentRepository.getAll()
assert payments.size() == 1
assert payments[0].paymentStatus() == FINISHED
}
}
}
يحمل الصنف، من بين تعليقات توضيحية أخرى، @AutoConfigureStubRunner الذي ربما تعرفه من قبل. ويوفّر في اختبارنا العقد المستخدم لتوليد الحدث. وهناك أيضًا حاوية Kafka، مُعلَن عنها ومُشغَّلة في دالة معلَّمة بـ DynamicPropertySource، كما شرحنا في قسم المنتِج. أما الحقل الأكثر إثارة للاهتمام في صنف الاختبار هذا فهو stubTrigger – كائن من Spring Cloud Contract يتيح لك تحفيز إرسال الرسالة. ويُستخدم في قسم when من دالة الاختبار. أحفّز هنا بالتسمية (label)، وتأتي التسمية triggerOrderCreatedEvent من العقد. ويوفر Spring Cloud Contract آليات تحفيز أخرى موصوفة في الوثائق.
يتحقق هذا السيناريو من أنه بعد أن استهلكت الخدمة حدث OrderCreated، أُنشئت عملية دفع ونُفّذت (حالتها FINISHED). ويُحاط فحص الدفع والحالة بـ PoolingCondition، لأن نشر الحدث واستهلاكه يحدثان بشكل غير متزامن ولن يكتملا إلا في نهاية المطاف.
الاختبار بسيط للغاية: يحفّز الرسالة ويتحقق من تنفيذ المنطق المتوقع. لكن ما الذي يرسل الرسالة فعلًا؟ لذلك ننفّذ واجهة مخصصة هي MessageVerifierSender تُرسل الرسالة إلى Kafka.
@Configuration
class TestConfiguration {
@Bean
MessageVerifierSender<Message<?>> standaloneMessageVerifier(KafkaTemplate kafkaTemplate) {
return new MessageVerifierSender<Message<?>>() {
@Override
void send(Message<?> message, String destination, @Nullable YamlContract contract) {
kafkaTemplate.send(message)
}
@Override
<T> void send(T payload, Map<String, Object> headers, String destination, @Nullable YamlContract contract) {
kafkaTemplate.send(
createMessage(payload, new MessageHeaders(Map.of(TOPIC, destination)))
)
}
}
}
}
هي تنشر الحدث فقط باستخدام KafkaTemplate من SpringKafka. ثم يستهلكه مستمع payment-service ويعالجه.
أصبح كل من منتِج الحدث ومستهلِكه مختبَرًا الآن مقابل العقد نفسه، وهذا يضمن أن كل طرف في التبادل يلتزم بالقواعد التي يعلنها. وعلى الرغم من أن الخدمتين لا تتحدثان إلى بعضهما مباشرة وأن وسيطًا يقع بينهما، فإن اختبارات العقود تتيح لنا التأكد من صحة اتصالهما.
لماذا أحتاج إلى اختبارات العقود لرسائل Kafka؟
قد تتساءل هنا – لماذا نتكبد عناء اختبارات العقود لرسائل Kafka؟ الرسائل عادةً ليست JSON؛ بل تميل إلى استخدام صيغ قائمة على مخطط (schema) مثل Avro مع Schema Registry، وهذه تضمن توافق الرسائل. والجواب من وجهين:
- لسبب ما، لا تريد استخدام شيء مثل Avro + Schema Registry أو لا تستطيع
- المخطط يتحقق من صحة الرسالة من حيث الدلالة فقط. ولا يضمن أن الرسالة نُشرت إلى الموضوع الصحيح واستُهلكت منه، ولا يفحص ما إذا كانت الرسالة صالحة لسيناريو معين. فمثلًا قد تحتوي الرسالة على حقول اختيارية. وإذا لم يوجد أي منها تبقى الرسالة صالحة دلاليًا. لكن من حيث الأعمال لا معنى لمثل هذه الرسالة – كأن يلزم وجود حقل اختياري واحد على الأقل لتكون صالحة.
لذلك حتى مع وجود صيغة رسائل قائمة على مخطط وSchema Registry، فإن إضافة اختبارات العقود مفيدة للتأكد من أن الاتصال صحيح، ليس دلاليًا فحسب، بل أيضًا من حيث المتطلبات الوظيفية.
الخلاصة
بيّنت هذه المقالة كيف يمكن استخدام Spring Cloud Contract لاختبار الاتصال غير المتزامن بين الخدمات المصغّرة التي تستخدم Kafka وسيطًا للرسائل. بدأنا بتعريف العقد لهذا الاتصال، ثم اختبرنا المنتِج والمستهلِك مقابله. وفي أثناء ذلك أشرتُ إلى عدة فروق بين طريقة تعامل الإطار مع اختبار REST API والاتصال القائم على الأحداث.
وكما لاحظت ربما، فإن اختبار أحداث Kafka بهذا الإطار ليس سهلًا بشكل خاص (مقارنةً مثلًا باختبار REST API). عليك كتابة بعض الشيفرة للتحقق من صحة الرسالة المنشورة إلى الوسيط والمستهلكة منه. وكما ذكرت، يعود ذلك في معظمه إلى أن Spring Cloud Contract لا يملك آلية مدمجة لاختبار رسائل Kafka، فعلينا بناءها بأنفسنا. ومع ذلك آمل أن تكون هذه المقالة قد جعلت الموضوع أسهل فهمًا وأن تساعدك على تنفيذ مثل هذه الاختبارات في مشروعك.
ستتناول المقالة التالية والأخيرة في السلسلة اختبار عقود Kafka باستخدام وسيط Pact. أشجعك على قراءتها واختيار النهج الأنسب لمشروعك.