@HttpExchange — khai báo interface, Spring sinh client

TL;DR: HTTP Interface là cách Spring Framework 6 cho bạn khai báo một client HTTP bằng interface Java thuần — gắn @GetExchange/@PostExchange/@HttpExchange lên từng method, thay vì viết tay từng lời gọi RestClient. HttpServiceProxyFactory dựng một proxy lúc chạy quanh interface đó, dịch mỗi lời gọi method thành một request HTTP thật, nhưng request vẫn đi qua đúng RestClient bạn đã cấu hình timeout và xử lý lỗi ở bài trước — hành vi đó không mất đi đâu cả. Chọn declarative khi hợp đồng gọi ổn định và lặp lại nhiều lần; giữ RestClient fluent khi cần điều khiển từng request theo runtime.

TaskFlow gọi notification-service để báo cho người dùng biết task vừa đổi trạng thái. Bài trước bạn đã dựng bean RestClient với timeout và bộ dịch lỗi tường minh. Vấn đề là mỗi endpoint downstream lại cần thêm một method viết tay, và năm method đó nhìn gần như giống hệt nhau.

Bài này giải thích cơ chế đứng sau @HttpExchange — vì sao khai báo một interface lại chạy được như một client thật, và khi nào nên giữ cách viết tay thay vì chuyển hẳn sang declarative.

1. Năm method giống hệt nhau

NotificationClient của TaskFlow gọi năm endpoint trên notification-service: lấy preference, liệt kê thông báo, gửi thông báo mới, cập nhật trạng thái đã đọc, xoá thông báo. Viết bằng RestClient thủ công như bài trước, mỗi method lặp lại đúng một khung: build URI, chọn verb, retrieve(), convert kiểu trả về.

class NotificationClient {
    private final RestClient restClient; // bean cau hinh o bai truoc

    NotificationPreference getPreferences(String userId) {
        return restClient.get()
                .uri("/notifications/preferences/{userId}", userId)
                .retrieve()
                .body(NotificationPreference.class);
    }

    NotificationDto send(NotificationRequest request) {
        return restClient.post()
                .uri("/notifications")
                .body(request)
                .retrieve()
                .body(NotificationDto.class);
    }

    void delete(String id, String requestId) {
        restClient.delete()
                .uri("/notifications/{id}", id)
                .header("X-Request-Id", requestId)
                .retrieve()
                .toBodilessEntity();
    }

    // listNotifications, updateStatus: cung khung GET/PATCH, chi khac path va kieu tra ve
}

Khác nhau đúng ba chỗ: path, HTTP verb, kiểu trả về. Phần còn lại — gọi retrieve(), convert body — lặp lại y hệt ở cả năm method. Khi một pattern lặp lại đều đặn thế này, đó là dấu hiệu nên khai báo thay vì viết tay từng lần: nói cho framework biết "tôi cần method này gọi tới endpoint kia", để nó tự sinh phần khung lặp lại.

2. HTTP Interface là gì?

HTTP Interface là một interface Java thuần, mỗi method gắn annotation @HttpExchange (mức method hoặc mức type) hoặc các biến thể theo verb: @GetExchange, @PostExchange, @PatchExchange, @DeleteExchange. Interface không có thân method — bạn chỉ khai báo chữ ký, Spring Framework (từ bản 6.0) sinh ra implementation lúc chạy và tự gọi HTTP thật khi method được invoke.

Đây chính là ý tưởng bạn đã gặp ở khoá trước với Spring Data repository: khai báo interface, framework sinh thân. Spring Data sinh implementation truy vấn database; HTTP Interface sinh implementation gọi HTTP. Cùng cơ chế "khai báo hợp đồng, để framework lo phần lặp lại", chỉ khác đích đến.

Thử tự viết method còn thiếu trước khi xem đáp án — hai method đầu đã có sẵn:

public interface NotificationClient {

    @GetExchange("/notifications/preferences/{userId}")
    NotificationPreference getPreferences(@PathVariable String userId);

    @PostExchange("/notifications")
    NotificationDto send(@RequestBody NotificationRequest request);

    // TODO: viet method cho GET /notifications?userId=..&page=..&size=..
    // tra ve Page<NotificationDto>
}

Đáp án:

@GetExchange("/notifications")
Page<NotificationDto> listNotifications(
        @RequestParam String userId,
        @RequestParam int page,
        @RequestParam int size);

Hai method còn lại (updateStatus, delete) theo đúng khuôn đó — @PatchExchange với @PathVariable cộng @RequestBody, @DeleteExchange với @PathVariable cộng @RequestHeader cho header tuỳ biến:

@PatchExchange("/notifications/{id}/status")
void updateStatus(@PathVariable String id, @RequestBody NotificationStatusUpdate update);

@DeleteExchange("/notifications/{id}")
void delete(@PathVariable String id, @RequestHeader("X-Request-Id") String requestId);

Từ năm method viết tay với năm khối RestClient gần như giống nhau, giờ còn lại một interface với năm khai báo method — phần khung lặp lại (retrieve(), convert body) không còn hiện diện trong code bạn viết nữa.

3. Cơ chế bên dưới: proxy quanh RestClient

Interface không có thân method thì ai thực thi khi bạn gọi notificationClient.send(request)? Câu trả lời là một proxy — object được tạo lúc chạy, implement NotificationClient, và mỗi method của nó dịch lời gọi thành một request HTTP thật rồi giao cho RestClient gửi đi. Đây là đúng kỹ thuật JDK dynamic proxy bạn đã gặp ở AOP của spring-core, chỉ khác mục đích: AOP proxy chèn logic cross-cutting (log, transaction) quanh method có sẵn; proxy của HTTP Interface là toàn bộ implementation — method vốn không có thân, proxy tự dựng nó từ annotation.

Dựng proxy đó cần hai lớp trung gian:

• RestClientAdapter — bọc một RestClient đã cấu hình sẵn, biến nó thành cầu nối mà HttpServiceProxyFactory hiểu được.
• HttpServiceProxyFactory — đọc annotation trên interface, sinh proxy, và implement method bằng cách gọi qua RestClientAdapter đó.

@Bean
NotificationClient notificationClient(RestClient notificationRestClient) {
    RestClientAdapter adapter = RestClientAdapter.create(notificationRestClient);
    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();
    return factory.createClient(NotificationClient.class);
}

Điểm mấu chốt: notificationRestClient tiêm vào đây đúng là bean bạn đã dựng ở bài trước, với connectTimeout/readTimeout khai tay và bộ onStatus dịch lỗi downstream sang exception nghiệp vụ. Proxy không thay thế RestClient đó — nó chỉ dịch method call thành request rồi giao lại toàn bộ việc gửi/nhận cho đúng RestClient đã cấu hình. Timeout vẫn áp dụng, lỗi downstream vẫn bị dịch đúng như trước; bạn chỉ bớt phải gõ tay phần lặp lại.

flowchart LR
    A[NotificationClient interface] --> B[HttpServiceProxyFactory]
    B --> C[proxy runtime]
    C --> D[RestClientAdapter]
    D --> E["RestClient bean bai 04<br/>timeout + onStatus"]
    E --> F[HTTP request that toi notification-service]

4. Ánh xạ tham số — chiều đọc ngược nhau

Bốn annotation tham số ở HTTP Interface trùng tên với annotation bạn đã dùng ở @RestController: @PathVariable, @RequestParam, @RequestBody, @RequestHeader. Trùng tên nhưng đọc ngược chiều nhau, vì một bên nhận request đến, một bên tạo request đi.

flowchart TB
    subgraph Server["Server - RestController"]
        S1["@PathVariable doc tu URL toi"]
        S2["@RequestBody parse JSON toi"]
    end
    subgraph Client["Client - HTTP Interface"]
        C1["@PathVariable dien vao URL di"]
        C2["@RequestBody serialize JSON di"]
    end
    HTTP["HTTP request"]
    HTTP --> S1
    HTTP --> S2
    C1 --> HTTP
    C2 --> HTTP

Chốt một câu để không nhầm: cùng annotation, nhưng ở @RestController nó đọc từ request vừa tới, còn ở HTTP Interface nó ghi vào request sắp gửi đi.

5. Khi nào declarative, khi nào fluent

Trục quyết định: hợp đồng có ổn định và lặp lại nhiều lần không, hay bạn cần điều khiển từng request theo tình huống lúc chạy. NotificationClient hợp declarative vì năm endpoint cố định — path, verb, kiểu trả về không đổi theo request.

Nhưng interface chỉ có chữ ký method cố định lúc biên dịch, không có chỗ viết logic động. Ba tình huống sau vẫn cần giữ RestClient fluent:

• Header đổi theo runtime theo điều kiện phức tạp — ví dụ chọn giữa nhiều token tuỳ role, tuỳ feature flag. HTTP Interface vẫn nhận @RequestHeader làm tham số, nhưng nếu logic chọn giá trị phức tạp hơn một tham số đơn thuần, viết bằng fluent rõ ràng hơn.
• Xử lý response phân nhánh theo status code cụ thể — ví dụ 404 trả về Optional.empty() thay vì ném exception, còn 5xx thì retry. RestClient cho bạn onStatus/exchange() để rẽ nhánh ngay tại chỗ gọi; HTTP Interface trả thẳng object hoặc ném exception, không có chỗ để chèn nhánh xử lý riêng cho từng method.
• Streaming response — đọc dữ liệu theo luồng (chunked, Server-Sent Events) cần giữ control trên InputStream/Flux, việc mà method interface trả T cố định không diễn đạt được gọn.

Không có cách nào tốt hơn tuyệt đối. TaskFlow vẫn giữ RestClient bean gốc bên cạnh NotificationClient — dùng interface cho năm endpoint cố định, và gọi thẳng RestClient khi cần một request đặc biệt ngoài khuôn đó.

Pitfall thường gặp

❌ Nhầm 1 — tưởng chuyển sang interface thì bỏ được bean RestClient ở bài trước:

// SAI: RestClient.create() mac dinh, mat het timeout + onStatus da cau hinh
RestClientAdapter.create(RestClient.create());

✅ Luôn tiêm đúng bean RestClient đã cấu hình ở bài trước vào RestClientAdapter — interface chỉ thay phần khung gọi, không thay cấu hình mạng.

❌ Nhầm 2 — dùng sai annotation cho tham số path:

// SAI: @RequestParam cho o von la path segment
@GetExchange("/notifications/preferences/{userId}")
NotificationPreference getPreferences(@RequestParam String userId);

✅ Chỉ @PathVariable điền được {userId} trong path template. Dùng nhầm @RequestParam khiến {userId} không được thay thế — request thật gửi đi nguyên chuỗi /notifications/preferences/{userId}, downstream trả 404 vì đó không phải path hợp lệ.

❌ Nhầm 3 — khai interface xong quên đăng ký bean:

Chỉ viết interface NotificationClient với annotation mà không có @Bean gọi factory.createClient(...) thì Spring không tự biết cần tạo proxy nào — nơi khác @Autowired NotificationClient sẽ nhận lỗi "No qualifying bean of type". Interface tự nó chỉ là khai báo; bước đăng ký ở mục 3 là bắt buộc, không tự động.

Đào sâu

Liên hệ các bài khác

• Bài 04 — RestClient — bean RestClient, timeout, và bộ dịch lỗi bạn vừa tái sử dụng nguyên vẹn qua RestClientAdapter ở bài này.
• Bài 06 — Sealed type cho kết quả nghiệp vụ — sau khi có client gọi downstream gọn, bài tiếp theo model kết quả trả về (thành công/lỗi) bằng sealed type thay vì ném exception rải rác.

Tóm tắt

• HTTP Interface là interface Java gắn @GetExchange/@PostExchange/@HttpExchange; không viết thân method, Spring sinh implementation lúc chạy.
• HttpServiceProxyFactory dựng proxy bằng JDK dynamic proxy quanh RestClientAdapter bọc RestClient đã cấu hình — đó là lý do interface bắt buộc phải là interface, không dùng được cho class cụ thể.
• Timeout và bộ dịch lỗi cấu hình ở bài trước không mất đi khi chuyển sang interface — chúng sống trong RestClient được bọc, proxy chỉ dịch method call thành request.
• Bốn annotation tham số trùng tên với @RestController nhưng đọc ngược chiều: server đọc từ request tới, client ghi vào request đi.
• Declarative hợp khi hợp đồng ổn định và lặp lại; giữ RestClient fluent khi cần rẽ nhánh theo status code, header động phức tạp, hoặc streaming.

Tự kiểm tra

Bài tiếp theo: Sealed type cho kết quả nghiệp vụ