بناء REST API بـ Spring Boot

Spring Boot إطار عمل لـ Java يساعد على تشغيل مشروع الخادم بسرعة. معظم الإعدادات الافتراضية جاهزة: خادم Tomcat مدمج، والاتصال بقاعدة البيانات، وتحويل البيانات إلى JSON. تبني هذه المقالة واجهة REST API صغيرة في ثلاث طبقات: Controller وService وRepository.

ملاحظة اختبار: الحاسوب الذي كُتبت عليه هذه المقالة لا يحتوي على Maven أو Gradle، ولم يُختبر تنزيل مكتبات Spring هنا. الكود أدناه هو النمط القياسي. شغّله بنفسك وتحقق من النتيجة قبل استخدامه فعليًا.

ما الذي تحتاجه

• JDK 17 أو أحدث
• Maven أو Gradle
• VS Code مع إضافة Spring Boot، أو IntelliJ IDEA

الطبقات الثلاث

الخطوة 1: إنشاء المشروع

ادخل إلى https://start.spring.io واختر Maven وJava 17، وأضف الاعتماديات Spring Web وSpring Data JPA، ثم أنشئ المشروع وفك ضغطه.

الخطوة 2: صنف البيانات

package com.example.demo;

import jakarta.persistence.*;

@Entity
public class Note {
    @Id
    @GeneratedValue
    private Long id;
    private String title;

    public Note() {}
    public Note(String title) { this.title = title; }

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
}

الخطوة 3: Repository

package com.example.demo;

import org.springframework.data.jpa.repository.JpaRepository;

public interface NoteRepository extends JpaRepository<Note, Long> {
}

يوفر Spring Data الدوال الأساسية مثل `findAll` و`save` و`deleteById` تلقائيًا عند وراثة `JpaRepository`.

الخطوة 4: Service

package com.example.demo;

import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class NoteService {
    private final NoteRepository repository;

    public NoteService(NoteRepository repository) {
        this.repository = repository;
    }

    public List<Note> all() {
        return repository.findAll();
    }

    public Note create(String title) {
        return repository.save(new Note(title));
    }
}

الخطوة 5: Controller

package com.example.demo;

import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/notes")
public class NoteController {
    private final NoteService service;

    public NoteController(NoteService service) {
        this.service = service;
    }

    @GetMapping
    public List<Note> list() {
        return service.all();
    }

    @PostMapping
    public Note create(@RequestBody Note body) {
        return service.create(body.getTitle());
    }
}

الخطوة 6: التشغيل والاختبار

./mvnw spring-boot:run

اختبر باستخدام curl:

curl -X POST http://localhost:8080/api/notes -H "Content-Type: application/json" -d "{\"title\":\"ซื้อกาแฟ\"}"
curl http://localhost:8080/api/notes

أخطاء شائعة

• **أسماء الحزم لا تطابق بنية المجلدات:** يبحث Spring عن الأصناف انطلاقًا من الحزمة الرئيسية، لذلك ضع الأصناف ضمن الحزمة نفسها للصنف المُعلَّم بـ `@SpringBootApplication`.
• **عدم إضافة تعريف قاعدة البيانات (Driver):** يفشل الاتصال. أضف التعريف واضبط `application.properties`.
• **حفظ بيانات غير صالحة دون فحص:** استخدم Bean Validation للتحقق قبل الحفظ.

الخطوات التالية

أضف التحقق من المدخلات، وادمج معالجة الأخطاء في مكان واحد باستخدام `@ControllerAdvice`، واختبر Service باستخدام JUnit.

الخلاصة

يقسّم Spring Boot واجهة REST API إلى ثلاث طبقات: يستقبل Controller الطلبات، ويعالج Service المنطق، ويتواصل Repository مع قاعدة البيانات. يجعل هذا الفصل الكود أسهل في الاختبار والصيانة.