sb.route()
  .methods(HttpMethod.GET)
  .path("/get")
  .produces(MediaType.PLAIN_TEXT)
  .matchesParams("name")
  .build((ctx, req) -> HttpResponse.of("Hello, " + ctx.path()));

This will only match GET requests that are able to accept text/plain responses and, which have a query parameter of name. We’ll also automatically get the correct errors when an incoming request doesn’t match – HTTP 405 Method Not Allowed if the request wasn’t a GET request, and HTTP 406 Not Acceptable if the request couldn’t accept text/plain responses.

5. Annotated Handlers

As we’ve seen, in addition to adding handlers directly, Armeria allows us to provide an arbitrary class with appropriately annotated methods and automatically map these methods to handlers. This can make writing complex servers much easier to manage.

These handlers are mounted using the ServerBuilder.annotatedService() method, providing an instance of our handler:

sb.annotatedService(new AnnotatedHandler());

Exactly how we construct this is up to us, meaning we can provide it with any dependencies necessary for it to work.

Within this class, we must have methods annotated with @Get, @Post, @Put, @Delete or any of the other appropriate annotations. These annotations take as a parameter the URL mapping to use – following the exact same rules as before – and indicate that the annotated method is our handler:

@Get("/handler")
public String handler() {
    return "Hello, World!";
}

Note that we don’t have to follow the same method signature here as we did before. Instead, we can require arbitrary method parameters to be mapped onto the incoming request, and the response type will be mapped into an HttpResponse type.

5.1. Handler Parameters

Any parameters to our method of types ServiceRequestContext, HttpRequest, RequestHeaders, QueryParams or Cookies will be automatically provided from the request. This allows us to get access to details from the request in the same way as normal handlers:

@Get("/handler")
public String handler(ServiceRequestContext ctx) {
    return "Hello, " + ctx.path();
}

However, we can make this even easier. Armeria allows us to have arbitrary parameters annotated with @Param and these will automatically be populated from the request as appropriate:

@Get("/handler/{name}")
public String handler(@Param String name) {
    return "Hello, " + name;
}

If we compile our code with the -parameters flag, the name used will be derived from the parameter name. If not, or if we want a different name, we can provide it as a value to the annotation.

This annotation will provide our method with both path and query parameters. If the name used matches a path parameter, then this is the value provided. If not, a query parameter is used instead.

By default, all parameters are mandatory. If they can’t be provided from the request, then the handler won’t match. We can change this by using an Optional<> for the parameter, or else by annotating it with @Nullable or @Default.

5.2. Request Bodies

In addition to providing path and query parameters to our handler, we can also receive the request body. Armeria has a few ways to manage this, depending on what we need.

Any parameters of type byte[] or HttpData will be provided with the full, unmodified request body that we can do with as we wish:

@Post("/byte-body")
public String byteBody(byte[] body) {
    return "Length: " + body.length;
}

Alternatively, any String or CharSequence parameter that isn’t annotated to be used in some other way will be provided with the full request body, but in this case, it will have been decoded based on the appropriate character encoding:

@Post("/string-body")
public String stringBody(String body) {
    return "Hello: " + body;
}

Finally, if the request has a JSON-compatible content type then any parameter that’s not a byte[], HttpData, String, AsciiString, CharSequence or directly of type Object, and isn’t annotated to be used in some other way will have the request body deserialized into it using Jackson.

@Post("/json-body")
public String jsonBody(JsonBody body) {
    return body.name + " = " + body.score;
}

record JsonBody(String name, int score) {}

However, we can go a step further than this. Armeria gives us the option to write custom request converters. These are classes that implement the RequestConverterFunction interface:

public class UppercasingRequestConverter implements RequestConverterFunction {
    @Override
    public Object convertRequest(ServiceRequestContext ctx, AggregatedHttpRequest request,
        Class<?> expectedResultType, ParameterizedType expectedParameterizedResultType)
        throws Exception {

        if (expectedResultType.isAssignableFrom(String.class)) {
            return request.content(StandardCharsets.UTF_8).toUpperCase();
        }

        return RequestConverterFunction.fallthrough();
    }
}

Our converter can then do anything it needs to with full access to the incoming request to produce the desired value. If we can’t do this—because the request doesn’t match the parameter, for example—then we return RequestConverterFunction.fallthrough() to cause Armeria to carry on with the default processing.

We then need to ensure the request converter is used. This is done using the @RequestConverter annotation, attached to either the handler class, handler method, or the parameter in question:

@Post("/uppercase-body")
@RequestConverter(UppercasingRequestConverter.class)
public String uppercaseBody(String body) {
    return "Hello: " + body;
}

5.3. Responses

In much the same way as requests, we can also return arbitrary values from our handler function to be used as the HTTP response.

If we directly return an HttpResponse object, then this will be the complete response. If not, Armeria will convert the actual return value into the correct type.

By standard, Armeria is capable of a number of standard conversions:

• null as an empty response body with an HTTP 204 No Content status code.
• byte[] or HttpData as raw bytes with an application/octet-stream content type.
• Anything implementing CharSequence – which includes String – as UTF-8 text content with a text/plain content type.
• Anything implementing JsonNode from Jackson as JSON with an application/json content type.

In addition, if the handler method is annotated with @ProducesJson or @Produces(“application/json”) then any return value will be converted to JSON using Jackson:

@Get("/json-response")
@ProducesJson
public JsonBody jsonResponse() {
    return new JsonBody("Baeldung", 42);
}

However, we can also write custom response converters similar to how we wrote our custom request converter. These implement the ResponseConverterFunction interface. This is called with the return value from our handler function and must return an HttpResponse object:

public class UppercasingResponseConverter implements ResponseConverterFunction {
    @Override
    public HttpResponse handleException(ServiceRequestContext ctx, HttpRequest req, Throwable cause) {
        if (cause instanceof IllegalStateException) {
            return HttpResponse.of(HttpStatus.CONFLICT);
        }

        return ResponseConverterFunction.fallthrough();
    }
}

As before, we can do anything we need to produce the desired response or return ExceptionHandlerFunction.fallthrough() to fall back to the standard processing.

And, as before, we need to annotate our function with @ResponseConverter to tell it to use our new response converter:

@Post("/uppercase-response")
@ResponseConverter(UppercasingResponseConverter.class)
public String uppercaseResponse(String body) {
    return "Hello: " + body;
}

We can apply this to either the handler method or the class as a whole

5.4. Exceptions

In addition to being able to convert arbitrary responses to an appropriate HTTP response, we can also handle exceptions however we wish.

By default, Armeria will handle a few well-known exceptions. IllegalArgumentException produces an HTTP 400 Bad Request, and HttpStatusException and HttpResponseException are converted into the HTTP response they represent. Anything else will produce an HTTP 500 Internal Server Error response.

However, as with return values from our handler function, we can also write converters for exceptions. These implement the ExceptionHandlerFunction, which takes the thrown exception as input and returns the HTTP response for the client:

public class ConflictExceptionHandler implements ExceptionHandlerFunction {
    @Override
    public HttpResponse handleException(ServiceRequestContext ctx, HttpRequest req, Throwable cause) {
        if (cause instanceof IllegalStateException) {
            return HttpResponse.of(HttpStatus.CONFLICT);
        }

        return ResponseConverterFunction.fallthrough();
    }
}

As before, we can do anything we need to produce the correct response or return ExceptionHandlerFunction.fallthrough() to fall back to the standard handling.

And, as before, we need to annotate our function with @ExceptionHandler to tell it to handle the exception:

@Get("/exception")
@ExceptionHandler(ConflictExceptionHandler.class)
public String exception() {
    throw new IllegalStateException();
}

6. GraphQL

到目前為止，我們已經研究瞭如何使用 Armeria 設置 RESTful 處理程序。但是，它能做的事情遠不止這些，包括 GraphQL、Thrift 和 gRPC。

為了使用這些額外的協議，我們需要添加一些額外的依賴項。例如，添加 GraphQL 處理程序需要將 com.linecorp.armeria:armeria-graphql 依賴項添加到我們的項目中：

    com.linecorp.armeria
    armeria-graphql

一旦我們完成了這些，我們就可以使用 Armeria 通過使用 GraphqlService 來暴露 GraphQL 模式：

sb.service("/graphql",
  GraphqlService.builder().graphql(buildSchema()).build());

這會從 GraphQL java 庫中獲取一個 GraphQL 實例，我們可以以我們想要的方式構建它，並在指定的端點上暴露它。