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

متغيرات المسار ومعاملات الطلب

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

متغيرات المسار ومعاملات الطلب

تحتاج كل واجهة برمجية REST إلى طريقة تُمكّن المستدعين من تحديد أي مورد يريدون وكيف يريدون تصفيته أو تشكيله. تمنحك Spring MVC آليتين واضحتين لذلك: متغيرات المسار (مقاطع مُضمَّنة في URI نفسه) ومعاملات الطلب (أزواج مفتاح-قيمة في سلسلة الاستعلام). معرفة متى تستخدم كلًّا منهما — وكيف تستخدم الاثنتين بشكل صحيح — هو أساس تصميم واجهة REST متقنة.

متغيرات المسار مع @PathVariable

متغير المسار هو عنصر نائب مُسمَّى داخل قالب URL، يُحاط بأقواس معقوصة. عند وصول طلب، تستخرج Spring القيمة الفعلية عند ذلك الموضع وتحقنها في معامل الدالة المُزيَّن بـ @PathVariable.

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    // GET /api/products/42
    @GetMapping("/{id}")
    public ResponseEntity<Product> getById(@PathVariable Long id) {
        return productService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }
}

افتراضيًا يجب أن يتطابق اسم المتغير في القالب مع اسم المعامل. إن اختلفا (مثلًا في كود مُترجَم يُزيل أسماء المعاملات) مرِّر الاسم صراحةً: @PathVariable("id") Long productId.

متغيرات مسار متعددة

يمكنك امتلاك أكبر عدد من مقاطع المسار بحسب ما تتطلبه التسلسلية الهرمية للموارد. نمط شائع هو المورد المتداخل: طلب ينتمي إلى عميل محدد.

// GET /api/customers/7/orders/103
@GetMapping("/{customerId}/orders/{orderId}")
public ResponseEntity<Order> getOrder(
        @PathVariable Long customerId,
        @PathVariable Long orderId) {

    Order order = orderService.findByCustomerAndId(customerId, orderId);
    return ResponseEntity.ok(order);
}

متغيرات المسار تُشفِّر الهوية لا معايير التصفية. عنوان URL مثل /products/42 يُسمّي موردًا واحدًا بلا غموض. لهذا تستخدم واجهات REST البرمجية متغيرات المسار للمعرّفات ومفاتيح البحث الأولية.

متغيرات المسار الاختيارية

يمكنك جعل متغير المسار اختياريًا بتعيين required = false وإقرانه بـ java.util.Optional أو بمعامل يقبل القيم الفارغة. هذا نادر عمليًا لمقاطع المسار — فإن كان المقطع قد يغيب، فالتعيين المنفصل عادةً أوضح — لكنه صياغة صحيحة.

@GetMapping({"/{category}", "/"})
public List<Product> list(
        @PathVariable(required = false) String category) {
    return category == null
            ? productService.findAll()
            : productService.findByCategory(category);
}

معاملات الطلب مع @RequestParam

تقع معاملات الطلب في سلسلة الاستعلام: ?page=2&size=20&sort=name. تناسب المرشّحات الاختيارية والترقيم والترتيب والبحث — أي شيء يُضيِّق أو يُشكِّل مجموعة النتائج بدلًا من تحديد مورد بعينه.

// GET /api/products?category=electronics&page=0&size=10
@GetMapping
public Page<Product> list(
        @RequestParam(required = false) String category,
        @RequestParam(defaultValue = "0")  int page,
        @RequestParam(defaultValue = "10") int size) {

    Pageable pageable = PageRequest.of(page, size);
    return category == null
            ? productService.findAll(pageable)
            : productService.findByCategory(category, pageable);
}

السمات الأساسية لـ @RequestParam:

required — افتراضيًا true؛ تُعيد Spring 400 إن غاب المعامل ولم تُقدِّم قيمة افتراضية.
defaultValue — سلسلة تُحوَّل نوعيًا إلى نوع المعامل؛ تُضمِّن required = false ضمنيًا.
name (أو value) — استخدمها حين يختلف مفتاح سلسلة الاستعلام عن اسم معامل Java.

حدِّد دائمًا defaultValue لمعاملات الترقيم. المستدعي الذي يُغفل page أو size سيحصل وإلا على خطأ 400. الإعداد الافتراضي عند الصفحة 0 وحجم معقول (10–25) هو الاتفاقية المعيارية في واجهات REST.

معاملات متعددة القيم

يمكن لسلسلة الاستعلام أن تحمل المفتاح نفسه أكثر من مرة: ?tag=java&tag=spring. اربطها بـ List وستجمع Spring جميع القيم تلقائيًا.

// GET /api/products?tag=java&tag=spring
@GetMapping("/search")
public List<Product> searchByTags(
        @RequestParam List<String> tag) {
    return productService.findByTags(tag);
}

تحويل الأنواع

تُحوِّل ConversionService في Spring القيمة النصية الخام إلى نوع المعامل المُعلَن تلقائيًا. الأنواع البدائية (int، long، boolean) والأنواع المُغلَّفة وUUID وLocalDate والتعدادات (enums) كلها تعمل جاهزة. عند فشل التحويل تُعيد Spring 400 Bad Request برسالة وصفية — ولست بحاجة لكتابة كود تحليل بنفسك.

// GET /api/orders?status=SHIPPED&since=2024-01-01
@GetMapping("/orders")
public List<Order> orders(
        @RequestParam OrderStatus status,
        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate since) {
    return orderService.findByStatusSince(status, since);
}

لا تُمرِّر معاملات النص الحر غير المحدودة مباشرةً إلى استعلامات قاعدة البيانات دون تحقق. رغم أن Spring تضمن سلامة النوع، يمكن للمستدعي تمرير سلاسل بالغة الطول. تحقق من الأطوال والتنسيقات — إما بتعليقات Bean Validation (@RequestParam @Size(max=100) String q) أو في طبقة الخدمة — قبل تمرير القيم إلى كود الاستمرارية.

متغير المسار مقابل معامل الطلب — قاعدة التصميم

قاعدة عملية يعتمدها مصممو واجهات REST المتمرّسون:

استخدم متغير المسار حين تُحدّد القيمة موردًا بشكل فريد أو مستوىً محددًا في التسلسل الهرمي: /users/99، /users/99/posts/12.
استخدم معامل الطلب حين تُصفّي القيمة أو تُرتِّب أو تُرقِّم أو تعدّل الاستجابة بأي شكل دون تغيير مجموعة الموارد المُعالَجة: /users?role=admin&page=2.

يتوافق هذا بدقة مع دلالات REST: المسار يُسمّي المورد؛ وسلسلة الاستعلام تُشكّل التمثيل.

الجمع بين الاثنين — نقطة نهاية واقعية

// GET /api/products/42/reviews?rating=5&page=0&size=5
@GetMapping("/{productId}/reviews")
public Page<Review> getReviews(
        @PathVariable Long productId,
        @RequestParam(required = false) Integer rating,
        @RequestParam(defaultValue = "0")  int page,
        @RequestParam(defaultValue = "5")  int size) {

    Pageable pageable = PageRequest.of(page, size);
    return reviewService.findByProduct(productId, rating, pageable);
}

تُفصل هذه الدالة بوضوح بين الهوية (productId في المسار) والتصفية (rating) والترقيم (page، size) — وهو النمط ذاته الذي ستجده في واجهات REST الناضجة كـ GitHub وStripe وTwitter/X API.

الخلاصة

استخدم @PathVariable للقيم التي تُحدّد موردًا في التسلسل الهرمي لـ URI، و@RequestParam للقيم الاختيارية في سلسلة الاستعلام التي تُصفّي الاستجابة أو تُشكّلها. كلتاهما تدعمان تحويل الأنواع تلقائيًا. حدِّد دائمًا defaultValue للمعاملات الاختيارية لتجنّب استجابات 400 غير متوقعة وجعل واجهتك البرمجية أكثر تسامحًا مع المستدعين.