Armeria: Improve the usability of `WebClient`

[trustin]

From an internal feed back:

What would the ideal API for building an HTTP request look like? Do you have some imaginary ideal example?

Using method chains like Spring WebClient is easy for me to write http request. Annotation pattern like Retrofit is also easy for me.I prefer the Spring WebClient way to annotation pattern.

 What is the library/API you think Armeria team should benchmark?

Spring WebClient

 What other features would you like to see in Armeria?

Prepare a method which maps HttpResponse to Java Object, like bodyToMono<T>

[trustin]

Related: #2148

[trustin]

https://www.reddit.com/r/java/comments/gcctln/which_http_client_framework_do_people_personally/

[ikhoon]

https://www.reddit.com/r/java/comments/gy8vi2/which_openfeign_client_is_the_best/

[trustin]

https://stackoverflow.com/questions/63660975/armeria-http-client-how-to-add-query-string-parameters#comment112614741_63664409

It may be useful if we can build/execute an HttpRequest fluently, so that, for example, add a query parameter easily.

// Not the final form - just an idea
HttpRequest req =
    HttpRequest.builder(HttpMethod.GET, "/foo")
               .queryParam("bar", "2")
               .cookie(...)
               .build();
webClient.execute(req);

// and/or:
webClient.prepare(HttpMethod.GET, "/foo")
         .queryParam("bar", "2")
         .cookie(...)
         .execute(); // or .execute(String.class) for automatic conversion

[trustin]

@ptrthomas wrote:

understood! maybe you should just accept an instance of QueryParams for e.g. webClient.post("/upload", qp, "{ \"foo\": \"bar\" }"), yes it is extra clunky, but it will help those new to the framework to be "aware" of this helper. a compromise would be to add queryParam() to RequestHeadersBuilder.

[tumile]

I'd love to take a stab. An idea on how the HttpRequestBuilder may look like

HttpRequestBuilder.[get,post,put,..]  // shortcut for method(HttpMethod.*)
                  .method(HttpMethod)
                  .path(String)
                  .mediaType(MediaType)
                  .headers(HttpHeaders)
                  .content(CharSequence|String|byte[]|HttpData)
                  .pathParams(Map<String, String>)
                  .queryParams(QueryParams)
                  .cookies(Cookies)
                  .timeout(long)

There may also be queryParam or cookie (singular) to add a single value. Then we can delegate all HttpRequest.of to builder. I think we can even deprecate the more complex ones in favor of builder pattern.

I'm still thinking on how webClient.prepare()...execute() would work. Maybe having another class (WebClientRequestBuilder?) that extends HttpRequestBuilder with an execute?

[trustin]

Yeah, having a class like WebClientRequestBuilder would be nice. We could extract the common methods in HttpRequestBuilder into some common interface or abstract class. What do you think, @tumile ?

[ikhoon]

https://www.mocklab.io/blog/which-java-http-client-should-i-use-in-2020/