How To Write A Custom Zuul Filter In Spring Cloud

This tutorial is going to cover how to write a custom Zuul filter in Spring Cloud.

1. Zuul Filter Overview

Zuul provides a framework to dynamically read, compile, and run a series filters that are capable of performing a range of actions during the routing of HTTP requests and responses.

1.1. Key Characteristics of a Zuul Filter

A Zuul filter has following key characteristics:

  • Type: most often defines the stage during the routing flow when the Filter will be applied.
  • Execution Order: applied within the Type, defines the order of execution across multiple Filters.
  • Criteria: the conditions required in order for the Filter to be executed.
  • Action: the action to be executed if the Criteria is met.

Zuul filters do not communicate with each other directly – instead they share state through a RequestContext which is unique to each request.

1.2. Filter Types

There are several standard Filter types that correspond to the typical lifecycle of a request:

  • PRE: Filters execute before routing to the origin. For example: request authentication, logging debug info
  • ROUTING: Filters handle routing the request to an origin.
  • POST: Filters execute after the request has been routed to the origin.
  • ERROR: Filters execute when an error occurs during one of the other phases.

2. Write A Custom Zuul Filter

2.1. Filter Interface

Filters must extend ZuulFilter and implement the following methods correspond to the key characteristics of a Zuul filter:

  • filterType():

Define the filter’s type, values can be “pre“, “routing“, and “post” which map with Zuul’s primary request lifecycle phases.

  • filterOrder():

The method filterOrder() returns an int describing the order that the Filter should run in relative to other filters.

  • shouldFilter()

The method shouldFilter() returns a boolean indicating if the Filter should run or not.

  • run()

Define the actions to be executed.

2.2. Custom Zuul Filter Example

Now, let’s write a custom Zuul filter which simply log the request information before routing¬† the request to an origin.

  • filterType(): this method returns “pre” because we want all request information will be logged before routing it.
  • filterOrder(): currently we set 1 as value (we have just one filter of this type right now)
  • shouldFilter(): return true. This filter will be applied for all requests.
  • run(): simply log the request method, request URL before routing.

Next, let’s declare our filter as a Spring bean:


3. Conclusion

The tutorial has illustrated how to write a custom Zuul filter in Spring Cloud. We can see that it’s pretty easy to create our custom Zuul filters for our application. Beside some built-in support filters from Zuul, Spring Cloud does support a lot of filters which can be considered to use or reference. You can find them on Spring Cloud project repository.

The sample source code can be found on my Github project. This is a Maven-based project, so it should be easy to import into IDEs such as Eclipse, Intellij and run as it is.