Improve WebClient.Builder::filter documentation

[membersound]

I would assume the following adds the filter after any existing filters into the chain:

@Service
public class YourService {
     //builder is injected
     public YourService (WebClient.Builder builder) {
         builder.filter(ExchangeFilterFunction.ofResponseProcessor(...)))...build();
     }
}

But in fact this adds the filter on top, so that this filter is processed first, instead of last as I would expect.

This is a problem when having a default WebClient that has already a common logging-filter (eg defined through your own company-wide framework), and now you want to add any other filter, eg an statuscode-filter:

private static ExchangeFilterFunction statuscodeFilter() {
	return ExchangeFilterFunction.ofResponseProcessor(clientResponse -> {
		HttpHeaders headers = clientResponse.headers().asHttpHeaders();
		if (headers.getFirst("customStatus").equals("400")) {
			return Mono.error(new CustomWebError());
		}
			
		return Mono.just(clientResponse);
	});
}

Of course, even in case of exceptions, you still want the logger to be executed before the statuscode filter. As otherwise you'd lose the logging functionality.

But the only way to achieve this is:

.filters(filters -> filters.add(filters.size()-1, statuscodeFilter()))

So could this be optimized? Is it worth adding a .filterFirst() or filterLast() function to directly set the new filter into a specific order? Or if you stick with the solution adding the filter within .filters(idx, filter), then maybe the docs could be more clear on this?

[poutsma]

The whole reason we have that filters(Consumer<List<ExchangeFilterFunction>>) method is to cover a whole range of scenarios, including the one you mention. If we would add a methods for adding filters first in the chain, someone else would perhaps ask for a method to remove all filters from the chain, or a similar convenience method. And for consistency's sake, we would have to take a similar approach for defaultCookies(Consumer<MultiValueMap<String, String>>), adding convenience methods there. The amount of methods would explode, and the resulting API would not be as user-friendly anymore. Having the consumer-based solution solves that by allowing users to customize the filters as they wish, without adding any noise in the WebClient.Builder.

I do agree that the documentation for filter(ExchangeFilterFunction) can be improved, so I will do that.