Olga Maciaszek-Sharma
Declarative Clients in Spring
Copyright © 2020 VMware, Inc. or its affiliates.

About Olga
Software Engineer in Spring Cloud team
Spring Cloud LoadBalancer, Spring Cloud OpenFeign, Spring
Cloud Netflix, Spring Cloud Contract, Spring Cloud Square,
RSocket HTTP Bridge
TT/ Mastodon: @olga_maciaszek

What is a declarative client?

Sample applications
Customer Service Verification Service
HTTP POST /verify
Customer Verification Result

Direct use of HTTP client

Client interface

Implementation

Implementation with helper methods

Client interface usage

What if we could just create an annotated
interface and have a library/ framework
translate it into actual HTTP client requests?

Declarative/ interface client
Client interface
method calls
HTTP calls
Proxy

Feign

OpenFeign/Feign

Feign
Java to HTTP client binder
● Core part of a former Spring Cloud Netflix module, passed over to the community
● Supports various HTTP clients, including Apache HTTP, Apache HC5, Ok HTTP
● Contracts - support for custom annotations and argument resolution
● Support for a broad range of encoders/ decoders, including Jackson and GSON
● Metrics, including Micrometer support

Spring Cloud OpenFeign

Spring Cloud OpenFeign
Spring MVC and Spring Cloud support for OpenFeign
● Spring MVC annotations support
● Auto-configurations for Feign-specific beans
● Spring Cloud LoadBalancer support
● Spring Cloud CircuitBreaker support
● Tracing support

A declarative/ interface client

A declarative/ interface client use

Spring Cloud OpenFeign Demo
Applications communicating over HTTP
Customer Service
SC OpenFeign Client
SC LoadBalancer
SC Sleuth
Verification Service
POST /verify
Customer Verification Result
Eureka Service Registry

Spring Cloud OpenFeign - popularity
Highly-readable interface clients with robust integrations
● 906 GitHub stars
● 8670549 Maven downloads in 2021
● Nearly flat learning curve for Spring MVC users

Spring Cloud OpenFeign - issues
● Issues with reusing client interfaces as controllers
○ @RequestMapping at class level user issues (GH-547, GH-678)
○ CVE-2021-22044
● Maintenance issues caused by dependence on third party upstream project
● Lack of non-blocking support

Spring Cloud Square
Spring Boot and Spring Cloud support for Retrofit and OkHttp
● WebClient support for Retrofit interface clients
● Auto-configurations
● Load-balancing
● Tracing
● Only Retrofit annotations
● Incubator project

RetroSocket
Interface client for RSocket
● Incubator project

HTTP & RSocket Interface Clients
in Spring Framework 6.0

Interface clients are not new in
the Spring Framework
Same mechanism, different protocols

Why HTTP and RSocket now?
Discussions with Spring Cloud around
OpenFeign, Retrofit, and RSocket integrations

Spring Framework 6.0 already had plans
for RSocket interface client

Old request for HTTP, deferred to…
Spring Cloud OpenFeign

Old request for HTTP, deferred to…
Spring Cloud OpenFeign

Opportunity to revisit
Underlying mechanism is not specific to Spring Cloud
Cloud features are extensions on top

Some issues can only be addressed
in Spring Framework
programming model vs reusing @RequestMapping

Decided to explore
for Spring Framework 6.0

HTTP interface client programming model
Relationship to server @RequestMapping?

Two goals
Define a single request (no wildcards of any kind!)
Avoid outright server-specific

@RequestMapping attributes
For mapping of 1..N requests
Any HTTP method Any URL path

@RequestMapping method parameters
ServletRequest
HttpMethod
@RequestHeader
@RequestParam
@RequestBody
@RequestAttribute
@ModelAttribute
…

@RequestMapping return values
ResponseEntity
HttpHeaders
Body
void
Model
View
SseEmitter
…

New method annotation
to declare rather than map requests
@RequestMapping
@HttpExchange

@HttpExchange attributes
url
method
contentType
accept

@HttpExchange method parameters
Subset of those for @RequestMapping
i.e. reusing method parameter annotations

@HttpExchange method parameters
URI
HttpMethod
@RequestHeader
@PathVariable
@RequestBody
@RequestParam
@CookieValue

@HttpExchange return values
Subset of those for @RequestMapping
i.e. also using return value types

Blocking

Reactive

status, headers, body

headers

execute only

Spring Interface Clients Demo
Applications communicating over HTTP
Customer Service
Spring HTTP Interface Client
SC LoadBalancer
Verification Service
POST /verify
Customer Verification Result
Eureka Service Registry

RSocket interface client
@RSocketExchange

@RSocketExchange attributes
value

@RSocketExchange method parameters
@DestinationVariable
@Payload
Object, if followed by MimeType
MimeType

@RSocketExchange return values
concrete values
producer of values

Blocking

Reactive

Demo

Resources
● Demo code - reactive HTTP client
● Demo code - non-reactive HTTP client with load-balancing
● Demo-code - RSocket client
● Spring Cloud OpenFeign
● Spring Framework documentation for HTTP interface client
● Spring Framework documentation for RSocket interface client
● Spring Cloud Square
● RetroSocket

Thank you
Twitter: @olga_maciaszek
© 2020 Spring. A VMware-backed project.