Spring Boot দিয়ে REST API — অনলাইন দোকানের ব্যাকএন্ড

১ · অ্যাপ আর সার্ভারের কথোপকথন — HTTP-র ভেতরে কী থাকে

ধরুন রাজশাহীর একটি ছোট অনলাইন দোকান — চা-পাতা, চাল, মশলা বিক্রি করে। তাদের একটি মোবাইল অ্যাপ আছে, একটি ওয়েবসাইটও আছে। দুটোই পণ্যের তালিকা দেখায়, অর্ডার নেয়। কিন্তু পণ্যের দাম আর স্টক থাকে একটি জায়গায়: সার্ভারের ডেটাবেসে। তাই অ্যাপকে প্রতিবার সার্ভারকে জিজ্ঞেস করতে হয় — “১ নম্বর পণ্যের তথ্য দাও”, “এই অর্ডারটি নাও”। এই প্রশ্ন-উত্তরের ভাষার নাম HTTP.

পর্ব ৩৯-এ দেখেছেন, দুই প্রোগ্রামের মধ্যে ডেটা যায় JSON হয়ে। HTTP হলো সেই JSON বহন করার খাম — কে পাঠাচ্ছে, কী চাইছে, উত্তর সফল কি না, সব লেখা থাকে খামের গায়ে। আর সার্ভারের যে দরজাগুলো দিয়ে অ্যাপ এভাবে কথা বলে, সেগুলো মিলেই সার্ভারের API. এই পর্বে আপনি Java আর Spring Boot দিয়ে সেই দরজাগুলো বানাবেন।

একটি আসল HTTP request লেখামাত্র — মানুষও পড়তে পারে। অ্যাপ নতুন পণ্য যোগ করতে চাইলে এমন কিছু পাঠায়:

POST /api/v1/products HTTP/1.1          ← request line: method, পথ, সংস্করণ
Host: shop.example.com                  ← header শুরু
Content-Type: application/json          ← body কোন ফরম্যাটে
Accept: application/json                ← উত্তর কোন ফরম্যাটে চাই
Authorization: Bearer eyJhbGciOi...     ← আমি কে (token)
                                        ← ফাঁকা লাইন: header শেষ
{"name":"চা-পাতা","category":"grocery","price":120,"stock":50}

প্রথম লাইনটি request line: method POST, পথ /api/v1/products, আর HTTP-র সংস্করণ। তারপর কয়েকটি header — প্রতিটি “নাম: মান” জোড়া। একটি ফাঁকা লাইনের পর আসে body. সার্ভারের উত্তরও একই গঠনের:

HTTP/1.1 201 Created                    ← status line: সংস্করণ, কোড, ছোট বর্ণনা
Location: /api/v1/products/42           ← নতুন পণ্যটি কোথায় পাওয়া যাবে
Content-Type: application/json

{"id":42,"name":"চা-পাতা","category":"grocery","price":120,"inStock":true}

দুটি header বিশেষ গুরুত্বপূর্ণ। Content-Type বলে body কোন ফরম্যাটে — JSON হলে application/json. এটা ভুল হলে সার্ভার body পড়তেই পারে না। আর Accept বলে client কোন ফরম্যাটে উত্তর চায়। পুরো ঠিকানাটি — https://shop.example.com/api/v1/products/42 — একটি URL.

এবার JDK দিয়েই একটি সত্যিকারের ছোট সার্ভার চালিয়ে দেখুন। Spring লাগবে না: JDK-র ভেতরে একটি সরল HTTP সার্ভার (com.sun.net.httpserver) আর Java 11 থেকে একটি HTTP client (java.net.http) আছে। প্রোগ্রামটি নিজেই সার্ভার চালু করে, তারপর নিজেই client হয়ে দুটি request পাঠায়:

import com.sun.net.httpserver.HttpServer;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;

class Main {
    public static void main(String[] args) throws Exception {
        var server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);   // 0 = যেকোনো খালি port
        server.createContext("/api/v1/products/", ex -> {
            String id = ex.getRequestURI().getPath().replace("/api/v1/products/", "");
            boolean found = id.equals("1");
            String body = found ? "{\"id\":1,\"name\":\"চা-পাতা\",\"price\":120}"
                                : "{\"status\":404,\"detail\":\"product " + id + " not found\"}";
            byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
            ex.getResponseHeaders().set("Content-Type", "application/json");
            ex.sendResponseHeaders(found ? 200 : 404, bytes.length);
            try (var out = ex.getResponseBody()) { out.write(bytes); }
        });
        server.start();
        var client = HttpClient.newHttpClient();
        String base = "http://127.0.0.1:" + server.getAddress().getPort();
        for (String path : new String[] {"/api/v1/products/1", "/api/v1/products/99"}) {
            var req = HttpRequest.newBuilder(URI.create(base + path)).GET().build();
            var res = client.send(req, HttpResponse.BodyHandlers.ofString());
            System.out.println("GET " + path + " -> " + res.statusCode() + " "
                + res.headers().firstValue("Content-Type").orElse("?") + "\n    " + res.body());
        }
        server.stop(0);
    }
}

২ · method আর status code — কোনটি কী বোঝায়

HTTP-তে কাজের ধরন বোঝাতে কয়েকটি method আছে। ডেটা নিয়ে প্রায় সব কাজ চারটি মৌলিক কাজে পড়ে — তৈরি, পড়া, বদলানো, মোছা; ইংরেজিতে সংক্ষেপে CRUD. প্রতিটির জন্য একটি method:

শেষের দুটি কলাম গুরুত্বপূর্ণ। safe method সার্ভারের কিছু বদলায় না — GET যতবার খুশি পাঠানো যায়। idempotent মানে একই request একবার পাঠানো আর দশবার পাঠানোর ফল সার্ভারে একই। PUT /products/7 দিয়ে দাম ১২০ করলে দশবারেও দাম ১২০। DELETE দুবার পাঠালে দ্বিতীয়বার হয়তো 404 আসবে, কিন্তু সার্ভারের অবস্থা একই — পণ্যটি নেই। কিন্তু POST /orders দশবার গেলে দশটি অর্ডার! মোবাইল নেটওয়ার্কে উত্তর হারিয়ে গেলে অ্যাপ আবার চেষ্টা করে, তাই এই পার্থক্য টাকার হিসাবে সরাসরি প্রভাব ফেলে (ভাবনার প্রশ্ন ৪)।

উত্তরে সার্ভার দেয় একটি তিন অঙ্কের status code. প্রথম অঙ্কটি দলের নাম বলে: 2xx সফল, 3xx অন্য জায়গায় যান, 4xx client-এর ভুল, 5xx সার্ভারের ভুল। প্রতিদিন যেগুলো লাগে:

401-এর নাম “Unauthorized” হলেও আসল অর্থ “পরিচয় যাচাই হয়নি” (authentication). আর 403 মানে পরিচয় জানা, কিন্তু অনুমতি নেই (authorization). নামটি ঐতিহাসিক ভুল, অর্থটি মনে রাখুন। নিচের stepper-এ পণ্যের API-র আটটি পরিস্থিতিতে কোন code ঠিক, ধাপে ধাপে দেখুন:

GET /api/v1/products/7
200 OK
{"id":7,"name":"মিনিকেট চাল ৫ কেজি","price":420,"inStock":true}

GET /api/v1/products/99
404 Not Found
{"title":"Product not found","status":404,"detail":"Product 99 not found"}
200 দিয়ে body-তে "error" লিখবেন না

POST /api/v1/products   {"name":"চা-পাতা", ...}
201 Created
Location: /api/v1/products/42
{"id":42,"name":"চা-পাতা", ...}

POST /api/v1/products   {"name":"","price":-5}
400 Bad Request
{"title":"Validation failed","errors":{"name":"...","price":"..."}}

POST /api/v1/products   {"name":"চা-পাতা", ...}
409 Conflict
{"title":"Duplicate product","detail":"'চা-পাতা' already exists"}

PUT /api/v1/products/42   {"name":"চা-পাতা","price":130, ...}
200 OK
{"id":42,"price":130, ...}
একই PUT আবার পাঠালেও ফল একই — idempotent

DELETE /api/v1/products/42
204 No Content
(body নেই)

DELETE /api/v1/products/42
404 Not Found
উত্তর আলাদা, কিন্তু সার্ভারের অবস্থা একই — পণ্যটি নেই

৩ · REST-এর নিয়মে URL সাজানো

REST (Representational State Transfer) কোনো লাইব্রেরি বা প্রোটোকল নয় — একটি নকশার ধরন। ২০০০ সালে Roy Fielding তাঁর PhD গবেষণাপত্রে ওয়েব কেন এত বড় হয়েও টিকে আছে, তা ব্যাখ্যা করতে গিয়ে এর নাম দেন। মূল ভাবনা: সার্ভারের ডেটাকে কয়েকটি resource হিসেবে দেখুন — পণ্য, অর্ডার, গ্রাহক। প্রতিটি resource-এর একটি স্থায়ী ঠিকানা (URL). আর সেগুলোর ওপর কাজ হবে HTTP-র সাধারণ method দিয়েই। দৈনন্দিন কাজে “REST API” মানে সাধারণত এটুকুই: সুন্দর URL, সঠিক method, সঠিক status code আর JSON. Fielding-এর মূল সংজ্ঞা এর চেয়ে কঠোর ছিল; সেই গল্প ভাবনার প্রশ্ন ১-এ।

প্রতিটি URL আর method-এর জোড়া একটি endpoint — যেমন GET /api/v1/products/{id}. ভালো endpoint নকশার কয়েকটি নিয়ম:

পথের ভেতরের অংশ /products/7 একটি path parameter — কোন resource, তা বলে। ?-এর পরের অংশ category=grocery একটি query parameter — কেমন করে দেখাব (ছাঁকা, সাজানো, কোন পাতা)। আর /api/v1 হলো API versioning: অ্যাপের পুরোনো সংস্করণ মাসের পর মাস মানুষের ফোনে থেকে যায়, তাই JSON-এর গঠন ভাঙার মতো বদল এলে /api/v2 খুলুন, v1 কিছুদিন চালু রাখুন (ভাবনার প্রশ্ন ৫)।

৪ · তিন স্তরের নকশা — Controller, Service, Repository

একটি অর্ডার নেওয়ার কাজে অনেক রকম চিন্তা মিশে থাকে: JSON পড়া, ইনপুট যাচাই, স্টক আছে কি না দেখা, স্টক কমানো, ডেটাবেসে লেখা, ঠিক status code দেওয়া। সব একটি method-এ লিখলে কোড দ্রুত জট পাকায়। তাই প্রায় সব Spring প্রজেক্টে একই স্তরভিত্তিক নকশা দেখবেন:

স্তরগুলোর মধ্যে ডেটাও আলাদা রূপে চলে। ডেটাবেসের টেবিলের সাথে মেলানো class হলো entity — এতে থাকতে পারে কেনা দাম, সরবরাহকারীর ফোন নম্বর, ভেতরের নোট। আর বাইরের জগতের সাথে চুক্তি হলো DTO (Data Transfer Object) — শুধু যা পাঠানো বা নেওয়ার কথা। Java-তে DTO-র জন্য record একদম মানানসই: অপরিবর্তনীয়, ছোট, আর Jackson সরাসরি বোঝে (পর্ব ২৫, ৩৯)।

Spring আসার আগে, শুধু Java দিয়ে এই তিন স্তর চালিয়ে দেখুন। এখানে ডেটাবেসের বদলে একটি TreeMap, আর HTTP-র বদলে method call — কিন্তু দায়িত্বের ভাগ আর status code-এর সিদ্ধান্ত হুবহু Spring প্রজেক্টের মতো:

import java.util.*;

record Product(long id, String name, int stock) {}
record OrderRequest(long productId, int qty) {}
class ApiError extends RuntimeException {                  // HTTP status-সহ ব্যর্থতা
    final int status;
    ApiError(int status, String msg) { super(msg); this.status = status; }
}
class ProductRepository {                                   // ডেটার স্তর (এখানে Map, বাস্তবে ডেটাবেস)
    private final Map<Long, Product> db = new TreeMap<>(Map.of(1L, new Product(1, "Tea", 5), 2L, new Product(2, "Rice", 0)));
    Optional<Product> findById(long id) { return Optional.ofNullable(db.get(id)); }
    void save(Product p) { db.put(p.id(), p); }
}
class OrderService {                                        // ব্যবসার নিয়মের স্তর
    private final ProductRepository repo;
    OrderService(ProductRepository repo) { this.repo = repo; }
    int place(OrderRequest r) {
        var p = repo.findById(r.productId()).orElseThrow(() -> new ApiError(404, "product " + r.productId() + " not found"));
        if (p.stock() < r.qty()) throw new ApiError(409, "only " + p.stock() + " in stock");
        repo.save(new Product(p.id(), p.name(), p.stock() - r.qty()));
        return p.stock() - r.qty();
    }
}
class OrderController {                                     // HTTP-র স্তর
    private final OrderService service;
    OrderController(OrderService service) { this.service = service; }
    String post(OrderRequest r) {
        try {
            if (r.qty() <= 0) throw new ApiError(400, "qty must be positive");   // যাচাই
            return "201 Created, stock left " + service.place(r);
        } catch (ApiError e) { return e.status + " " + e.getMessage(); }     // advice-এর কাজ
    }
}
class Main {
    public static void main(String[] args) {
        var api = new OrderController(new OrderService(new ProductRepository()));
        for (var r : List.of(new OrderRequest(1, 2), new OrderRequest(1, 0), new OrderRequest(9, 1),
                             new OrderRequest(2, 1), new OrderRequest(1, 4)))
            System.out.println("POST /orders " + r + " -> " + api.post(r));
    }
}

৫ · Spring MVC দিয়ে controller — method থেকে endpoint

পর্ব ৫০-এ দেখেছেন, @SpringBootApplication লেখা একটি class চালালেই Spring Boot অ্যাপ চালু হয়, starter দিয়ে লাইব্রেরি আসে, আর @Service, @Repository লেখা class-গুলো bean হয়ে constructor-এ জোড়া লাগে। REST API-র জন্য লাগে spring-boot-starter-web — এটি Spring MVC, Jackson আর একটি embedded server (ডিফল্টে Tomcat) নিয়ে আসে। ফলে আলাদা কোনো সার্ভার install করতে হয় না; অ্যাপ চালু হলেই port 8080-এ শোনা শুরু করে। এই পর্বের Spring কোড Spring Boot 3.x (Java 17 বা নতুন) ধরে লেখা। পরের বড় সংস্করণে (Spring Boot 4) কিছু starter বা package-এর নাম বদলাতে পারে — নতুন প্রজেক্টে start.spring.io আর অফিসিয়াল migration guide দেখে নিন; annotation আর ধারণা মূলত একই থাকে। এই লাইব্রেরি অনলাইন runner-এ নেই, তাই Spring কোডগুলো চালানো যাবে না; পাশে প্রত্যাশিত ফল লেখা আছে।

প্রথমে DTO দুটি — একটি আসা ডেটার জন্য, একটি যাওয়ার জন্য:

public record CreateProductRequest(
        @NotBlank(message = "নাম দিতে হবে") @Size(max = 100) String name,
        @NotBlank(message = "ক্যাটাগরি দিতে হবে") String category,
        @NotNull @Positive(message = "দাম শূন্যের বেশি হতে হবে") BigDecimal price,
        @PositiveOrZero int stock,
        @Pattern(regexp = "^01[3-9]\\d{8}$", message = "সঠিক বাংলাদেশি মোবাইল নম্বর দিন")
        String supplierPhone) {}

public record ProductResponse(Long id, String name, String category,
                              BigDecimal price, boolean inStock) {
    static ProductResponse from(Product p) {                 // entity → DTO
        return new ProductResponse(p.getId(), p.getName(), p.getCategory(),
                                   p.getPrice(), p.getStock() > 0);
    }
}

লক্ষ করুন, response-এ costPrice বা supplierPhone নেই, আর স্টকের সঠিক সংখ্যার বদলে শুধু inStock. annotation-গুলোর অর্থ অংশ ৬-এ। এবার controller:

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {
    private final ProductService service;
    public ProductController(ProductService service) { this.service = service; }

    @GetMapping                                               // GET /api/v1/products?category=grocery&page=0
    public PageResponse<ProductResponse> list(
            @RequestParam(required = false) String category,
            @PageableDefault(size = 20, sort = "name") Pageable pageable) {
        return PageResponse.of(service.list(category, pageable));
    }

    @GetMapping("/{id}")                                      // GET /api/v1/products/7 → 200
    public ProductResponse get(@PathVariable long id) {
        return service.get(id);
    }

    @PostMapping                                              // POST → 201 + Location
    public ResponseEntity<ProductResponse> create(@Valid @RequestBody CreateProductRequest req) {
        ProductResponse saved = service.create(req);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}").buildAndExpand(saved.id()).toUri();
        return ResponseEntity.created(location).body(saved);
    }

    @PutMapping("/{id}")                                      // PUT → 200
    public ProductResponse update(@PathVariable long id,
                                  @Valid @RequestBody UpdateProductRequest req) {
        return service.update(id, req);
    }

    @DeleteMapping("/{id}")                                   // DELETE → 204
    public ResponseEntity<Void> delete(@PathVariable long id) {
        service.delete(id);
        return ResponseEntity.noContent().build();
    }
}

JSON ⇄ record রূপান্তরের জন্য কোথাও ObjectMapper ডাকতে হয়নি। Spring Boot নিজেই একটি Jackson ObjectMapper বানিয়ে রাখে, java.time-এর সমর্থনসহ; record ফেরত দিলে সেটি JSON হয়, @RequestBody record-এ JSON ঢোকে (পর্ব ৩৯)। একটি পার্থক্য মনে রাখুন: পর্ব ৩৯-এর সাধারণ ObjectMapper অজানা key পেলে exception দেয়, কিন্তু Spring Boot-এর ObjectMapper ডিফল্টে অজানা key উপেক্ষা করে। তাই কেউ "costPrice":1 পাঠালেও DTO-তে সেই component না থাকলে তা নীরবে বাদ পড়ে — DTO-র আরেকটি সুবিধা।

এবার দেখুন, একটি POST request আসার পর থেকে উত্তর যাওয়া পর্যন্ত Spring-এর ভেতরে কী কী ঘটে:

POST /api/v1/products HTTP/1.1
Content-Type: application/json

{"name":"চা-পাতা","category":"grocery","price":120,"stock":50}

Tomcat: সংযোগ নিল, একটি thread দিল
  └─▶ DispatcherServlet.service(request, response)
সব request একই দরজা দিয়ে ঢোকে

POST /api/v1/products   →  ProductController.create(..)
GET  /api/v1/products/{id} →  ProductController.get(..)
DELETE /api/v1/products/{id} → ProductController.delete(..)
অ্যাপ চালুর সময়েই এই তালিকা তৈরি

Jackson: CreateProductRequest[name=চা-পাতা, category=grocery,
         price=120, stock=50, supplierPhone=null]
Validator: @NotBlank ✓  @Positive ✓  @Pattern ✓ (null চলবে)

@Transactional  → BEGIN
existsByName("চা-পাতা")?  না  → চালিয়ে যাও
new Product(...)   (entity, id এখনো null)

insert into products (category, cost_price, name, price, stock)
values (?, ?, ?, ?, ?)
→ ডেটাবেস id দিল: 42      COMMIT

ProductResponse.from(entity)  → ProductResponse[id=42, ...]
Jackson →
HTTP/1.1 201
Location: http://localhost:8080/api/v1/products/42
Content-Type: application/json
{"id":42,"name":"চা-পাতা","category":"grocery","price":120,"inStock":true}

চালু অ্যাপকে terminal থেকে curl দিয়ে চেষ্টা করা যায় (Postman-এর মতো GUI টুলেও একই কাজ)। -i দিলে header-ও দেখায়:

curl -i "http://localhost:8080/api/v1/products?category=grocery&page=0&size=2"

HTTP/1.1 200
Content-Type: application/json

{"items":[{"id":3,"name":"এলাচ ১০০ গ্রাম","category":"grocery","price":180,"inStock":true},
          {"id":42,"name":"চা-পাতা","category":"grocery","price":120,"inStock":true}],
 "page":0,"size":2,"totalItems":17,"totalPages":9}

এখানে PageResponse আমাদের নিজের একটি ছোট record (items, page, size, totalItems, totalPages). Spring Data-র Page object সরাসরি ফেরত দিলে তার JSON-এর গঠন স্থিতিশীল নয় বলে নতুন Spring Data সংস্করণ সতর্কবার্তা দেয়; নিজের DTO-ই নিরাপদ চুক্তি।

৬ · ইনপুট যাচাই আর এক জায়গায় error সামলানো

অ্যাপ বা ওয়েবসাইটের ফর্মে যাচাই থাকলেও সার্ভারে আবার যাচাই করতেই হবে। কারণ যে কেউ curl দিয়ে সরাসরি আপনার API-তে যা খুশি পাঠাতে পারে — অ্যাপের যাচাই তখন পাশ কাটানো। Java-তে এর মানক উপায় Jakarta Bean Validation: field-এর ওপর annotation দিয়ে নিয়ম লেখা, আর একটি validator (সাধারণত Hibernate Validator) সেগুলো পরীক্ষা করে। Spring Boot-এ এর জন্য spring-boot-starter-validation যোগ করতে হয় — web starter-এর সাথে নিজে থেকে আসে না।

শুধু annotation লিখলে কিছু হয় না; controller-এর parameter-এ @Valid লিখলে তবেই যাচাই চলে। যাচাই ব্যর্থ হলে Spring MethodArgumentNotValidException ছোড়ে, আর controller-এর method শুরুই হয় না।

এক জায়গায় সব error — @RestControllerAdvice আর ProblemDetail

প্রতিটি controller method-এ try-catch লিখলে কোড ঘোলা হয়, আর প্রতিটি endpoint-এর error JSON আলাদা চেহারার হয়ে যায়। তাই একটি @RestControllerAdvice class লিখুন — সব controller-এর exception এখানে আসে, আর @ExceptionHandler লেখা method ঠিক করে কোন exception কোন উত্তরে বদলাবে। উত্তরের ফরম্যাটের জন্য একটি ইন্টারনেট মান আছে: “Problem Details for HTTP APIs” — প্রথমে RFC 7807 (২০১৬), এখন তার জায়গায় RFC 9457 (২০২৩)। এতে আছে কয়েকটি নির্দিষ্ট field — type, title, status, detail, instance — আর media type application/problem+json. Spring Framework 6 (Spring Boot 3) থেকে এর জন্য তৈরি class: ProblemDetail.

public class ProductNotFoundException extends RuntimeException {
    public ProductNotFoundException(long id) { super("Product " + id + " not found"); }
}

@RestControllerAdvice
public class GlobalErrorHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ProblemDetail notFound(ProductNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("Product not found");
        pd.setType(URI.create("https://shop.example.com/problems/product-not-found"));
        return pd;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail invalid(MethodArgumentNotValidException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "ইনপুটে ভুল আছে");
        pd.setTitle("Validation failed");
        Map<String, String> errors = new TreeMap<>();
        ex.getBindingResult().getFieldErrors()
          .forEach(fe -> errors.put(fe.getField(), fe.getDefaultMessage()));
        pd.setProperty("errors", errors);
        return pd;
    }

    @ExceptionHandler(OutOfStockException.class)
    public ProblemDetail outOfStock(OutOfStockException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        pd.setTitle("Out of stock");
        pd.setProperty("available", ex.available());
        return pd;
    }
}

নিচের stepper-এ একটি ভুল ইনপুট — নাম খালি, দাম ঋণাত্মক, ফোন নম্বর ভুল — কোন পথে 400 উত্তর হয়ে ফেরে, দেখুন:

1@PostMapping2ResponseEntity<..> create(3    @Valid @RequestBody CreateProductRequest req) {4  var saved = service.create(req);5  return ResponseEntity.created(..).body(saved);6}7// ---- @RestControllerAdvice ----8@ExceptionHandler(MethodArgumentNotValidException.class)9ProblemDetail invalid(MethodArgumentNotValidException ex) {10  var pd = ProblemDetail.forStatusAndDetail(BAD_REQUEST, ..);11  pd.setProperty("errors", fieldErrors(ex));12  return pd;13}

{
  "type": "about:blank",
  "title": "Validation failed",
  "status": 400,
  "detail": "ইনপুটে ভুল আছে",
  "instance": "/api/v1/products",
  "errors": {
    "name": "নাম দিতে হবে",
    "price": "দাম শূন্যের বেশি হতে হবে",
    "supplierPhone": "সঠিক বাংলাদেশি মোবাইল নম্বর দিন"
  }
}

type না দিলে মান হয় about:blank — RFC অনুযায়ী এর মানে “status code-এর বাইরে আলাদা কোনো অর্থ নেই”। instance না দিলে Spring সাধারণত request-এর পথ বসিয়ে দেয়। errors আর available-এর মতো বাড়তি field RFC অনুমোদন করে (extension member). চাইলে spring.mvc.problemdetails.enabled=true দিয়ে Spring-এর নিজের exception-গুলোর (ভাঙা JSON, ভুল method, অসমর্থিত Content-Type) উত্তরও একই ফরম্যাটে আনা যায়।

অর্ডার — স্টক না থাকলে 409

একই নিয়মে অর্ডারের endpoint. service স্টক কম পেলে OutOfStockException ছোড়ে, advice সেটাকে 409 বানায় — ঠিক অংশ ৪-এর চালানো উদাহরণের মতো:

curl -i -X POST http://localhost:8080/api/v1/orders \
     -H "Content-Type: application/json" \
     -d '{"productId":7,"quantity":3,"customerPhone":"01712345678"}'

HTTP/1.1 409
Content-Type: application/problem+json

{"type":"about:blank","title":"Out of stock","status":409,
 "detail":"Only 1 left of product 7","instance":"/api/v1/orders","available":1}

৭ · Spring Data JPA — ডেটাবেসে রাখা আর আনা

পর্ব ৪৯-এ JDBC দিয়ে হাতে SQL লিখেছেন। JPA এক ধাপ ওপরে: Java class-কে টেবিলের সাথে মিলিয়ে দেয়, SQL-এর বেশিরভাগ নিজে তৈরি করে (Spring Boot-এ ডিফল্ট বাস্তবায়ন Hibernate). আর Spring Data JPA আরও এক ধাপ: শুধু একটি interface লিখলেই repository-র পুরো বাস্তবায়ন চলার সময় তৈরি হয়ে যায়।

@Entity
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)      // ডেটাবেস id দেবে
    private Long id;

    @Column(nullable = false, unique = true) private String name;
    @Column(nullable = false)                private String category;
    @Column(nullable = false)                private BigDecimal price;
    private int stock;
    private BigDecimal costPrice;                            // কেনা দাম — বাইরে যাবে না

    protected Product() {}                                   // JPA-র জন্য খালি constructor
    public Product(String name, String category, BigDecimal price, int stock) { ... }
    // getter, আর যেগুলো বদলানোর কথা শুধু সেগুলোর setter …
}

public interface ProductRepository extends JpaRepository<Product, Long> {
    Page<Product> findByCategory(String category, Pageable pageable);
    boolean existsByName(String name);
}

entity কেন record নয়? JPA-র দরকার একটি খালি constructor, বদলানো যায় এমন field, আর lazy loading-এর জন্য subclass বানানোর সুযোগ — record-এ এর কোনোটিই নেই। তাই entity সাধারণ class, আর DTO record. JpaRepository<Product, Long> (entity টাইপ, id-এর টাইপ) থেকে বিনা পয়সায় পাওয়া যায় save, findById, findAll(Pageable), existsById, deleteById, count. আর findByCategory-এর মতো method-এর শরীর কেউ লেখেনি — Spring Data নাম পড়ে query বানায়: find…By + field-এর নাম Category. এগুলোকে বলে derived query. নামে বানান ভুল হলে (findByCategroy) অ্যাপ চালুর সময়েই error — চলার মাঝে নয়।

ডেটাবেসের ঠিকানা থাকে application.properties-এ। শেখা আর টেস্টের জন্য মেমরির ভেতরের H2, আসল সার্ভারে PostgreSQL:

# শেখা ও টেস্ট — মেমরিতে H2 (অ্যাপ বন্ধ হলে ডেটা মুছে যায়)
spring.datasource.url=jdbc:h2:mem:shop

# আসল সার্ভার — PostgreSQL (পাসওয়ার্ড environment variable থেকে)
#spring.datasource.url=jdbc:postgresql://localhost:5432/shop
#spring.datasource.username=shop_app
#spring.datasource.password=${DB_PASSWORD}

spring.jpa.hibernate.ddl-auto=validate     # টেবিল বানাবে Flyway বা schema.sql; Hibernate শুধু মিলিয়ে দেখবে
spring.jpa.open-in-view=false              # lazy loading controller পর্যন্ত গড়াবে না
spring.mvc.problemdetails.enabled=true

service-এর ভেতরে findById ব্যবহারের প্রচলিত রূপটি ধাপে ধাপে দেখুন। findById null নয়, ফেরত দেয় Optional (পর্ব ৩৬) — “পণ্য না-ও থাকতে পারে” কথাটি টাইপেই লেখা:

1@Transactional(readOnly = true)2public ProductResponse get(long id) {3  return repo.findById(id)4      .map(ProductResponse::from)5      .orElseThrow(() -> new ProductNotFoundException(id));6}

Transaction আর pagination

service method-এ @Transactional লিখলে method-এর ভেতরের সব ডেটাবেস কাজ একটি transaction-এ যায়: সব সফল হলে COMMIT, মাঝে RuntimeException উঠলে সব ROLLBACK (পর্ব ৪৯)। অর্ডারে “স্টক কমানো” আর “অর্ডার লেখা” হয় দুটোই হবে, নয়তো কোনোটিই নয়। Spring এটা করে একটি AOP proxy দিয়ে, তাই একই class-এর ভেতর থেকে আরেকটি @Transactional method ডাকলে সেটার নিজস্ব সেটিং কাজ করে না — প্রচলিত একটি ফাঁদ। আর @Transactional controller-এ নয়, service-এ রাখুন; ব্যবসার একটি পুরো কাজ, একটি transaction.

হাজার পণ্যের তালিকা একবারে পাঠালে অ্যাপ ধীর হয়, ডেটাবেসেও চাপ পড়ে। pagination-এ client পাতা ধরে চায়: ?page=0&size=20&sort=price,asc. Spring এই query parameter থেকে নিজেই Pageable object বানায় (পাতার নম্বর ০ থেকে শুরু), আর repository ডেটাবেসে LIMIT/OFFSET-এর মতো SQL চালায়, সাথে মোট সংখ্যার জন্য একটি count query.

৮ · টেস্ট, ডকুমেন্টেশন, নিরাপত্তা আর deploy

টেস্ট — তিন মাপের

পর্ব ৪৭-এর JUnit এখানেও ভিত্তি; Spring শুধু অ্যাপের দরকারি অংশটুকু চালু করে দেয়। @WebMvcTest শুধু web স্তর চালায় — controller, advice, Jackson — ডেটাবেস ছাড়া। service-এর জায়গায় বসে একটি mock, আর MockMvc আসল সার্ভার ছাড়াই HTTP request-এর অনুকরণ করে:

@WebMvcTest(ProductController.class)
class ProductControllerTest {
    @Autowired MockMvc mvc;
    @MockitoBean ProductService service;          // Spring Boot 3.4-এর আগে: @MockBean

    @Test
    void unknownProductGives404() throws Exception {
        when(service.get(99)).thenThrow(new ProductNotFoundException(99));
        mvc.perform(get("/api/v1/products/99"))
           .andExpect(status().isNotFound())
           .andExpect(jsonPath("$.title").value("Product not found"));
    }

    @Test
    void blankNameGives400() throws Exception {
        mvc.perform(post("/api/v1/products").contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {"name":"","category":"grocery","price":120,"stock":5}
                    """))
           .andExpect(status().isBadRequest())
           .andExpect(jsonPath("$.errors.name").exists());
        verifyNoInteractions(service);             // ভুল ইনপুট service পর্যন্ত যায়নি
    }
}

@DataJpaTest শুধু JPA অংশ চালায়, সাধারণত মেমরির ডেটাবেসে — derived query সত্যিই ঠিক SQL বানাচ্ছে কি না দেখতে। আর @SpringBootTest পুরো অ্যাপ চালু করে — সবচেয়ে বাস্তব, সবচেয়ে ধীর; অল্প কয়েকটি end-to-end টেস্টে ব্যবহার করুন। আসল PostgreSQL-এ টেস্ট করতে অনেকে Testcontainers ব্যবহার করেন।

ডকুমেন্টেশন — OpenAPI আর Swagger UI

অ্যাপ বানাচ্ছেন যিনি, তাঁকে জানতে হবে কোন endpoint কী নেয়, কী দেয়। OpenAPI হলো API বর্ণনার একটি মানক ফরম্যাট। springdoc-openapi-starter-webmvc-ui লাইব্রেরি যোগ করলে springdoc আপনার controller আর DTO পড়ে নিজেই বর্ণনা বানায় (/v3/api-docs), আর /swagger-ui.html-এ একটি ওয়েব পাতা দেয়, যেখান থেকে প্রতিটি endpoint ব্রাউজারেই চেষ্টা করা যায়। validation annotation-গুলোও সেই বর্ণনায় নিয়ম হিসেবে দেখায়।

নিরাপত্তার প্রাথমিক কথা

• লগইন আর অনুমতি: Spring Security নামে আলাদা একটি বড় প্রকল্প আছে — token যাচাই, কে কোন endpoint-এ যেতে পারবে (যেমন শুধু অ্যাডমিন DELETE করতে পারবেন)। এটা নিজে একটি পুরো বিষয়; শুধু জেনে রাখুন, নিজে নিরাপত্তার কোড বানানোর চেয়ে প্রতিষ্ঠিত framework ব্যবহার করা নিরাপদ।
• শুধু DTO বাইরে: entity, পাসওয়ার্ড hash, কেনা দাম, ভেতরের id কখনো response-এ নয় (অংশ ৪)।
• CORS: ব্রাউজার নিরাপত্তার জন্য এক domain-এর পাতাকে অন্য domain-এর API ডাকতে দেয় না, যদি না API অনুমতি দেয়। shop.example.com-এর ওয়েবসাইট api.example.com ডাকলে সার্ভারে নির্দিষ্ট origin-এর অনুমতি দিন (@CrossOrigin বা global config). * দিয়ে সবাইকে খুলে দেবেন না। মোবাইল অ্যাপ ব্রাউজার নয়, তাই তার জন্য CORS প্রযোজ্য নয়।
• Rate limiting: একজন client মিনিটে কতবার ডাকতে পারবে, তার সীমা — OTP পাঠানো বা লগইনের মতো endpoint-এ অপব্যবহার ঠেকায়। সীমা পার হলে 429 Too Many Requests. সাধারণত API gateway বা আলাদা লাইব্রেরি এ কাজ করে।
• HTTPS: সাধারণ HTTP-তে token আর পাসওয়ার্ড খোলা লেখায় যায় — একই Wi-Fi-তে থাকা কেউ পড়ে ফেলতে পারে। আসল সার্ভারে শুধু HTTPS.

Deploy-এর এক ঝলক

mvn package চালালে Spring Boot একটি executable JAR বানায় — আপনার কোড, সব লাইব্রেরি আর embedded Tomcat একটি ফাইলে। যে কম্পিউটারে Java আছে, সেখানে java -jar shop.jar লিখলেই সার্ভার চালু। আজকাল প্রায়ই এটাকে Docker image-এ ভরা হয় — অ্যাপ আর তার Java runtime একসাথে একটি বাক্সে, যা যেকোনো সার্ভার বা ক্লাউডে একইভাবে চলে। একটি ন্যূনতম Dockerfile মাত্র কয়েক লাইনের:

FROM eclipse-temurin:21-jre
COPY target/shop-0.0.1-SNAPSHOT.jar /app/shop.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/shop.jar"]

অনেক request একসাথে সামলাতে Spring Boot 3.2 থেকে spring.threads.virtual.enabled=true দিয়ে প্রতিটি request-এ একটি virtual thread দেওয়া যায় — পর্ব ৪২-এর ধারণা এখানেই কাজে লাগে।

৯ · AI-এর যুগে — AI-এর লেখা API যাচাই

AI-কে “Spring Boot দিয়ে product API বানাও” বললে কয়েক সেকেন্ডে চলার মতো কোড আসে। সমস্যা হলো, “চলে” আর “ঠিক” এক নয়। AI-এর লেখা API-তে বারবার যে ভুলগুলো দেখা যায়:

AI-এর লেখা API হাতে পেলে — যাচাইয়ের চেকলিস্ট

• প্রতিটি endpoint-এর সফল ও ব্যর্থ উত্তরের status code অংশ ২-এর টেবিলের সাথে মিলিয়েছি; কোথাও “সব কিছুতে 200” নেই
• কোনো controller method entity ফেরত দেয় না বা @RequestBody-তে entity নেয় না
• curl দিয়ে খালি নাম, ঋণাত্মক দাম আর ভাঙা JSON পাঠিয়ে 400 দেখেছি
• error JSON সব endpoint-এ একই ফরম্যাটে (ProblemDetail), আর তাতে stack trace নেই
• @Transactional service-এ; তালিকার endpoint-এ pagination আছে; SQL log দেখে N+1 নেই
• সব import jakarta.* আর প্রতিটি annotation অফিশিয়াল ডকুমেন্টে খুঁজে পেয়েছি
• CORS-এ নির্দিষ্ট origin, আসল সার্ভারে HTTPS, আর গোপন তথ্য (পাসওয়ার্ড) কোডে নয়, environment variable-এ