Feign – Tạo ứng dụng Java RESTful Client

Trong các bài viết trước chúng ta sử dụng thư viện Jersey client, OkHttp, Retrofit để gọi các RESTful API. Trong bài này, tôi sẽ giới thiệu với các bạn thư viện khác là Feign. Thư viện này giúp chúng ta dễ dàng hơn nữa trong phát triển ứng dụng Rest Client.

1. Giới thiệu Feign

Feign là một HTTP client cho Java, được phát triển bởi Netflix. Mục tiêu của Fiegn là giúp đơn giản hóa HTTP API Client.

Tương tự với các thư viện khác, Feign giúp bạn dễ dàng xử lý dữ liệu JSON hoặc XML sau đó phân tích cú pháp thành Plain Old Java Objects (POJOs). Tất cả các yêu cầu GETPOSTPUT, và DELETE đều có thể được thực thi.

Feign được xây dựng dựa trên một số thư viện mạnh mẽ và công cụ khác để xử lý các request/ response trên mạng bao gồm OkHttp, JAX-RS, Gson, Jackson, JAXB, Ribbon, Hystrix, SOAP, … Các bạn xem thêm các thư viện khác: https://mvnrepository.com/artifact/io.github.openfeign

Feign hỗ trợ một số tính năng mạnh mẽ khác như: Error Handling, Retry, hỗ rợ default method, static method với interface trong java 8.

2. Sử dụng Feign

Ý tưởng của Feign tương tự như Retrofit là sử dụng interface và các annotation để định nghĩa các phương thức request đến API. Với Retrofit, chúng ta còn gặp một chút phiền phức khi phải gọi xử lý Call<Respone>. Sử dụng Feign chúng ta sẽ không thấy sự khác biệt giữa call các method trong interface thông thường và call thông qua Feign.

Để sử dụng Feign chúng ta thực hiện các bước sau:

  • Một class object tương ứng với JSON/ XML data.
  • Một interface dùng để định nghĩa các các phương thức request đến API.
  • Sử dụng Annotations để mô tả yêu cầu HTTP.
  • Tạo một Feign.builder() để khởi tạo các phương thức trong interface đã được định nghĩa.

3. Các Annotations để mô tả yêu cầu HTTP

Request method

Mỗi phương thức phải có Annotation HTTP cung cấp request method và URL. Feign sử dụng @RequestLine để mô tả các thông tin này.

@RequestLine("GET /api/v1/users?sort=desc")
List<User> getUsers();

3.2. Header manipulation

Chúng ta có thể set thông tin static header bằng cách sử dụng annotation @Header ở mức method.

@Headers({
    "Cache-Control: max-age=640000",
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@RequestLine("GET /api/v1/users?sort=desc")
List<User> getUsers();
 
@RequestLine("DELETE /api/v1/users/{id}")
@Headers("Authentication: Bearer {token}")
void deleteUser(@Param("id") int id, @Param("token") String token);

Đối với các kết hợp tham số truy vấn phức tạp, có thể sử dụng @HeaderMap.

@RequestLine("GET /api/v1/users?sort=desc")
List<User> getUsers(@HeaderMap Map<String, String> headers);

3.3. Url manipulation

URL request có thể được cập nhật tự động bằng cách sử dụng các khối thay thế và tham số trên phương thức.

Chúng ta có thể sử dụng URL 1 cách động dựa vào biến truyền vào, bằng cách sử dụng anotation @Path.

@RequestLine("GET /api/v1/users/{id}")
User getUser(@Path("id") int userId);

Đối với các kết hợp tham số truy vấn phức tạp, có thể sử dụng @QueryMap.

@RequestLine("GET /api/v1/users?page=1&limit=10&sortBy=createdAt&order=desc")
List<User> getUsers(@QueryMap Map<String, String> options);

3.4. Request body

Một đối tượng có thể được chỉ định để sử dụng làm phần thân yêu cầu HTTP với Annotation @Body.

@RequestLine("POST /api/v1/users")
@Headers("Content-Type: application/json")
@Body("%7B\"username\": \"{gpcoder}\", \"password\": \"{gpcoder}\"%7D")
Call<User> createUser(@Body User user);

3.5. Form encoded and Multipart

Để gửi dữ liệu form: application/x-www-form-urlencoded và multipart/form-data chúng ta cần sử dụng thêm thư viện feign-form.

Chúng ta cần cung cấp Content-Type trong @Headers và field name trong @Field.

@RequestLine("POST /api/v1/auth")
@Headers("Content-Type: application/x-www-form-urlencoded")
Call<String> getToken(@Field("username") String username, @Field("password") String password);

Các yêu cầu multipart được sử dụng khi @Multipart xuất hiện trên phương thức. Các phần được khai báo bằng cách sử dụng @Part. @Multipart thường được sử dụng để truyền tải file.

@Multipart
@POST("/api/v1/files/upload")
Call<String> uploadFile(@Part("uploadFile") RequestBody uploadFile, @Part("description") RequestBody description);
 
@RequestLine("POST /send_photo")
Headers("Content-Type: multipart/form-data")
void sendPhoto (@Param("isPublic") Boolean isPublic, @Param("photo") FormData photo);

4. Ví dụ CRUD Restful Client với Feign

4.1. Tạo project

Tạo maven project và khai báo dependency sau trong file pom.xml.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>
 
    <groupid>com.maixuanviet</groupid>
    <artifactid>RestfulClientWithFeignExample</artifactid>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
 
    <name>RestfulClientWithFeignExample</name>
    <url>http://maven.apache.org</url>
 
    <properties>
        <project.build.sourceencoding>UTF-8</project.build.sourceencoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <lombok.version>1.16.20</lombok.version>
    </properties>
 
    <dependencies>
        <!-- https://mvnrepository.com/artifact/io.github.openfeign/feign-okhttp -->
        <dependency>
            <groupid>io.github.openfeign</groupid>
            <artifactid>feign-okhttp</artifactid>
            <version>10.2.3</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/io.github.openfeign/feign-gson -->
        <dependency>
            <groupid>io.github.openfeign</groupid>
            <artifactid>feign-gson</artifactid>
            <version>10.2.3</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/io.github.openfeign/feign-slf4j -->
        <dependency>
            <groupid>io.github.openfeign</groupid>
            <artifactid>feign-slf4j</artifactid>
            <version>10.2.3</version>
        </dependency>
 
        <!-- Support for encoding application/x-www-form-urlencoded and multipart/form-data form -->
        <!-- https://mvnrepository.com/artifact/io.github.openfeign.form/feign-form -->
        <dependency>
            <groupid>io.github.openfeign.form</groupid>
            <artifactid>feign-form</artifactid>
            <version>3.8.0</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
        <dependency>
            <groupid>org.projectlombok</groupid>
            <artifactid>lombok</artifactid>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
 
    </dependencies>
</project>

Trong project này, tôi sử dụng thư viện gson để convert request/ response data giữa client và server.

4.2. Tạo CRUD Restful Client với Feign

Trong ví dụ này, chúng ta sẽ gọi lại các Restful API chúng ta đã tạo ở bài viết trước “JWT – Token-based Authentication trong Jersey 2.x“.

Đầu tiên, chúng ta cần gọi API /auth để lấy token và sau đó chúng ta sẽ attach token này vào mỗi request để truy cập resource.

AuthService.java

package com.maixuanviet.service;
 
import feign.Headers;
import feign.Param;
import feign.RequestLine;
 
public interface AuthService {
 
    @RequestLine("POST /auth")
    @Headers({ 
        "Accept: application/json; charset=utf-8", 
        "Content-Type: application/x-www-form-urlencoded" })
    String getToken(@Param("username") String username, @Param("password") String password);
}

OrderService.java

package com.maixuanviet.service;
 
import java.util.ArrayList;
import java.util.List;
 
import com.maixuanviet.model.Order;
 
import feign.Headers;
import feign.Param;
import feign.RequestLine;
 
@Headers({
    "Accept: application/json; charset=utf-8",
    "Content-Type: application/json" })
public interface OrderService {
 
    @RequestLine("GET /orders/{id}")
    String getOrder(@Param("id") int id);
 
    @RequestLine("POST /orders")
    String createOrder(Order order);
 
    @RequestLine("PUT /orders")
    String updateOrder(Order order);
 
    @RequestLine("DELETE /orders/{id}")
    String deleteOrder(@Param("id") int id);
 
    default List<String> getOrders(int... ids) {
        List<String> orders = new ArrayList<>();
        for (int id : ids) {
            orders.add(this.getOrder(id));
        }
        return orders;
    }
}

Tương tự Retrofit, chúng ta có thể sử dụng Interceptor – một tính năng của OkHttp để tự động thêm Authentication Token vào mỗi request, chúng ta không cần thêm nó một cách thủ công trong từng request.

Có một vài cách để gửi Authentication Header token lên server: sử dụng @Header, tạo custom Target, sử dụng Interceptor của Feign, sử dụng Interceptor của OkHttp.

Ví dụ bên dưới sử dụng 2 Interceptor:

  • AuthInterceptor : thêm Token vào mỗi request.
  • LoggingInterceptor : log trước khi gửi request và sau khi nhận response.

AuthInterceptor.java

package com.maixuanviet.interceptor;
 
import java.io.IOException;
 
import com.maixuanviet.helper.FeignClientCreator;
import com.maixuanviet.service.AuthService;
 
import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;
 
public class AuthInterceptor implements Interceptor {
     
    private static String token = null;
 
    @Override
    public Response intercept(Chain chain) throws IOException {
        /*
         * chain.request() returns original request that you can work with(modify,
         * rewrite)
         */
        Request originalRequest = chain.request();
 
        // Here we can rewrite the request
        // We add an Authorization header if the request is not an authorize request and already had a token
        Request authRequest = originalRequest;
        if (!originalRequest.url().toString().contains("/auth") &amp;&amp; getToken() != null) {
            authRequest = originalRequest.newBuilder()
                    .header("Authorization", "Bearer " + getToken())
                    .build();
        }
         
        /*
         * chain.proceed(request) is the call which will initiate the HTTP work. This
         * call invokes the request and returns the response as per the request.
         */
        Response response = chain.proceed(authRequest);
         
        // Here we can rewrite/modify the response
         
        return response;
    }
 
    private String getToken() throws IOException {
        if (token != null) {
            return token;
        }
 
        // Create an implementation of the API endpoints defined by the service interface
        AuthService authService = FeignClientCreator.getService(AuthService.class);
 
        // Sends a request to a webserver and return its response
        return authService.getToken("maixuanviet", "maixuanviet");
    }
}

Tương tự chúng ta sẽ tạo LoggingInterceptor:

LoggingInterceptor.java

package com.maixuanviet.interceptor;
 
import java.io.IOException;
 
import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;
 
public class LoggingInterceptor implements Interceptor {
    @Override
    public Response intercept(Interceptor.Chain chain) throws IOException {
        Request request = chain.request();
 
        long t1 = System.nanoTime();
        System.out.println(
                String.format("Sending request %s on %s%n%s", request.url(), chain.connection(), request.headers()));
 
        Response response = chain.proceed(request);
 
        long t2 = System.nanoTime();
        System.out.println(String.format("Received response for %s in %.1fms%n%s", response.request().url(),
                (t2 - t1) / 1e6d, response.headers()));
 
        return response;
    }
}

Để sử dụng Interceptor, chúng ta cần đăng ký với Client thông qua phương thức addInterceptor() hoặc addNetworkInterceptor(). Chương trình bên dưới, tôi đăng ký AuthInterceptor ở mức Application và LoggingInterceptor cho cả 2 mức Application và Network.

Chúng ta sẽ tạo một lớp hỗ trợ cấu hình Feign, đăng ký các Interceptor và tạo instance của Feign service.

FeignClientCreator.java

package com.maixuanviet.helper;
 
import com.maixuanviet.interceptor.AuthInterceptor;
import com.maixuanviet.interceptor.LoggingInterceptor;
import com.maixuanviet.service.OrderService;
 
import feign.Feign;
import feign.Logger;
import feign.form.FormEncoder;
import feign.gson.GsonDecoder;
import feign.gson.GsonEncoder;
import feign.okhttp.OkHttpClient;
import feign.slf4j.Slf4jLogger;
 
public class FeignClientCreator {
 
    public static final String BASE_URL = "http://localhost:8080/RestfulWebServiceExample/rest/";
     
    public static <T> T getService(Class<T> clazz) {    
        okhttp3.OkHttpClient okHttpClient = new okhttp3.OkHttpClient.Builder()
                .addInterceptor(new LoggingInterceptor())
                .addInterceptor(new AuthInterceptor())
                .addNetworkInterceptor(new LoggingInterceptor())
                .build();
         
        OkHttpClient feignOkHttp = new OkHttpClient(okHttpClient);
         
        return Feign.builder()
                  .client(feignOkHttp)
                  .encoder(new FormEncoder(new GsonEncoder()))
                  .decoder(new GsonDecoder())
                  .logger(new Slf4jLogger(clazz))
                  .logLevel(Logger.Level.FULL)
                  .target(clazz, BASE_URL);
    }
}

Tiếp theo chúng ta sẽ sử dụng Feign service để call các API.

FeignClientExample.java

package com.maixuanviet;
 
import java.io.IOException;
 
import com.maixuanviet.helper.FeignClientCreator;
import com.maixuanviet.model.Order;
import com.maixuanviet.service.OrderService;
 
public class FeignClientExample {
 
    private static OrderService orderService;
 
    public static void main(String[] args) throws IOException {
        orderService = FeignClientCreator.getOrderService(OrderService.class);
 
        createOrder();
        retrieveOrder();
        updateOrder();
        deleteOrder();
        retrieveOrders();
    }
 
    /**
     * @POST http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void createOrder() throws IOException {
        System.out.println("createOrder: " + orderService.createOrder(new Order()));
    }
 
    /**
     * @GET http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void retrieveOrder() throws IOException {
        System.out.println("retrieveOrder: " + orderService.getOrder(1));
    }
 
    /**
     * @PUT http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void updateOrder() throws IOException {
        System.out.println("updateOrder: " + orderService.updateOrder(new Order()));
    }
 
    /**
     * @DELETE http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void deleteOrder() throws IOException {
        System.out.println("deleteOrder: " + orderService.deleteOrder(1));
    }
 
    private static void retrieveOrders() {
        System.out.println("retrieveOrders: " + orderService.getOrders(1, 2));
    }
}

Như bạn thấy, Feign là một thư viện rất mạnh mẽ nhưng rất đơn giản để sử dụng. Hy vọng bài viết giúp ích cho các bạn, hẹn gặp lại ở các bài viết tiếp theo.

Related posts:

An Intro to Spring Cloud Security
Hướng dẫn sử dụng lớp Console trong java
Predicate trong Java 8
Java Program to Generate a Random UnDirected Graph for a Given Number of Edges
Java 8 – Powerful Comparison with Lambdas
Inject Parameters into JUnit Jupiter Unit Tests
Java Program to Represent Graph Using Adjacency List
4 tính chất của lập trình hướng đối tượng trong Java
Java Program to Implement a Binary Search Tree using Linked Lists
Tips for dealing with HTTP-related problems
Java Program to Implement the Program Used in grep/egrep/fgrep
Lập trình đa luồng với CompletableFuture trong Java 8
Validations for Enum Types
REST Web service: Basic Authentication trong Jersey 2.x
Guava Collections Cookbook
Notify User of Login From New Device or Location
Build a REST API with Spring and Java Config
Hướng dẫn Java Design Pattern – State
Java Program to Implement Warshall Algorithm
Converting a Stack Trace to a String in Java
JUnit 5 @Test Annotation
Hướng dẫn sử dụng Lớp FilePermission trong java
Java Program to Implement Traveling Salesman Problem using Nearest neighbour Algorithm
How to Change the Default Port in Spring Boot
How to Get the Last Element of a Stream in Java?
Java Program to Find Maximum Element in an Array using Binary Search
Java Program to Implement Bubble Sort
Java Program to Perform Searching Using Self-Organizing Lists
Java Program to Implement Euler Circuit Problem
Phân biệt JVM, JRE, JDK
Guide to Guava Multimap
Testing in Spring Boot