spring-cloud-openfeign: feature complete, with Spring's own successor already chosen

The README opens with a warning, deliberately

The first substantive thing in this repository's README is not a feature list, it is a status notice, and it is placed above everything else deliberately.

The README states that as announced in the Spring Cloud 2022.0.0 release blog entry, the project is now being treated as feature-complete. Only bugfixes and possibly some small community feature pull requests are going to be added, and the suggestion is to migrate over to Spring HTTP Service Clients instead.

That is unusual, and it is worth pausing on what it means. A library that is feature complete still gets bug fixes, so it still works. What it does not get is new capability: no new HTTP client features as the underlying libraries evolve, no new integration options, and no adaptation to whatever the next generation of Spring brings.

The pattern here is the standard Spring Cloud one. A component proves itself, becomes widely depended upon, and then is retired in favour of something that solves the same problem inside the framework itself rather than alongside it. Spring Cloud Netflix was retired the same way, and the Netflix components that were kept, like Eureka and Zuul, all went through the same treatment.

So the correct reading of this README is not that the project is abandoned. It is that the project is done, and the team has told you where to go next.

What Feign actually generates for you

The Features section is one sentence: Declarative REST Client, where Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations.

That is the whole mechanism, and it is more useful than it first sounds. You write an interface, and each method is a request.

The proxy is generated at startup, and the annotations on the interface become the request. The call site looks like an ordinary method call on an ordinary object, so the calling code has no HTTP in it at all.

The two annotation families in the description matter. JAX-RS annotations, meaning javax or jakarta.ws.rs, and Spring MVC annotations, meaning the @RequestMapping family. Supporting both means the same interface style works whether the project came from a JAX-RS background or a Spring one, which is a large part of why the library found its audience.

The benefit is not brevity so much as consistency. A typed method signature is a typed method signature, and the compiler catches a wrong argument type and a missing path variable. The trade is that the request is described in an interface rather than in code, so anything that needs to be computed at call time rather than declared has to be expressed in the annotation, and the usual escape hatch is falling back to a lower level client for that one call.

Three modules, and what each one is for

The repository layout separates the project into the pieces you would actually depend on.

There is spring-cloud-openfeign-core/, which is the implementation, and spring-cloud-starter-openfeign/, which is the starter that pulls in the core and the autoconfiguration so a service can use it with a dependency and little else. There is spring-cloud-openfeign-dependencies/, a bill of materials for the versions of the OpenFeign artifacts themselves, which is what lets a whole Spring Cloud deployment align on one version without pinning each one.

That three-part split is the Spring Cloud convention and it is worth understanding because it determines what your application should depend on. In almost every case the answer is the starter, and the dependencies module belongs in a parent or a dependency management section rather than in a service.

The rest of the tree is build infrastructure. There is a pom.xml at the root, the Maven wrapper mvnw and mvnw.cmd, a .mvn/ directory for wrapper configuration, a .settings.xml that provides the Spring repository declarations the build needs, a .sdkmanrc for SDKMAN users, and a .java-version file. The .java-version and the JDK 17 requirement in the build section agree with each other, and the JDK number is the one thing in this README you should note down before cloning.

There is also a release-train-settings.xml, which is the file that ties this project to the Spring Cloud release train, and a Guardfile, which is a Ruby tool used to enforce conventions on the commit history.

Building it, and the Maven profile you will need

The build section is short and the JDK requirement is stated first: to build the source you will need to install JDK 17.

Spring Cloud uses Maven for most build-related activities, and the README says you should be able to get off the ground quite quickly by cloning the project and typing:

$ ./mvnw install

The wrapper is used in preference to a system Maven, and the README notes that you can also install Maven, version 3.3.3 or better, yourself and run mvn in place of ./mvnw. If you do that you might need to add the -P spring profile if your local Maven settings do not contain repository declarations for spring pre-release artifacts.

That warning about the spring profile is the one that bites people, and the project has a whole section devoted to it. Spring Cloud projects require the spring Maven profile to be activated to resolve the spring milestone and snapshot repositories, and you should set the profile active in your IDE or you will experience build errors.

There is also a memory note. You might need to increase the amount of memory available to Maven by setting MAVEN_OPTS with a value like -Xmx512m -XX:MaxPermSize=128m, though the project says it tries to cover this in the .mvn configuration and asks you to raise a ticket if a build fails because of it.

Tests that need middleware, such as Redis, require a local instance of Docker to be installed and running.

The documentation has its own build path. The spring-cloud-build module has a docs profile, and switching it on builds the asciidoc sources using Antora from modules/ROOT/. The docs site itself is generated with:

$ ./mvnw -pl docs -P docs antora:antora

The README in this repository is itself generated, and says so at the top. The file starts with a do not edit notice, explaining that manual changes will be lost, and that the source lives in the src/main/asciidoc/ directory. That is a detail worth knowing before anyone opens the README to fix a typo.

The IDE guidance, and the two ways into Eclipse

There is a Working with the code section, and it is more specific than most project READMs manage to be.

If you have no IDE preference, the recommendation is Spring Tools Suite or Eclipse. The project uses the m2eclipse plugin for Maven support, and other IDEs and tools should work without issue as long as they use Maven 3.3.3 or better.

The detail that takes up the most space is the m2eclipse configuration, and the reason is version drift. Older versions of m2e do not support Maven 3.3, so once the projects are imported into Eclipse you also need to tell m2eclipse to use the right profile for the projects. If you see many different errors related to the POMs, the first thing to check is whether your m2e installation is up to date, and if you cannot upgrade it you can add the spring profile to your settings.xml, or copy the repository settings from the spring profile of the parent pom into your settings.xml.

If you prefer not to use m2eclipse at all, there is a fallback. You can generate the Eclipse project metadata with:

$ ./mvnw eclipse:eclipse

The generated Eclipse projects can then be imported by selecting import existing projects from the file menu.

This is old-school advice and the old m2e incompatibility note is dated, but the underlying shape is the same: the spring profile has to be active somewhere, whether in the IDE, in settings.xml, or on the command line, or the build will not resolve Spring artifacts.

What a feature-complete project leaves you with

The honest assessment of this library is about timing rather than quality.

What you get is a mature, declarative HTTP client that is part of the Spring Cloud ecosystem, with a starter that handles autoconfiguration, a dependencies module for version alignment, and an interface-based programming model that many teams already have in their codebase. If your service is already running OpenFeign, the library is not going to break. The bug fix commitment means security and compatibility fixes continue.

What you do not get is a future. The successor, Spring HTTP Service Clients, is the direction the Spring team has chosen, and it is part of Spring Framework rather than a separate Spring Cloud project. An organisation that starts a new service on OpenFeign today is writing code against an API that has a planned replacement, and the migration is a rewrite of every client interface rather than a configuration change.

The repository also shows the project maintaining its documentation through the Antora pipeline described earlier, with the docs/ directory at the root and a src/ directory holding the asciidoc sources. The documentation site for the project is separate from the Spring Framework reference that now documents the successor.

The project is licensed under the Apache 2.0, described as non-restrictive, and the licence file is LICENSE.txt at the root. The Spring Cloud release train means this artifact's version is tied to a train, so a new OpenFeign version arrives when the train does, which is one more reason to check what your train already ships before pinning anything.

Editorial conclusion

Spring Cloud OpenFeign still suits an application already on it that has Feign clients working and no reason to churn, because the generated client code is stable and the only work planned is bug fixes. It is the wrong choice for a new project, since the project is formally feature complete and Spring has published a successor in Spring HTTP Service Clients, so anything new would start on the old API and migrate later. Before you adopt it, read the feature-complete announcement linked in the README and check whether your Spring Boot version already ships the successor, because that decision is the whole reason this library's future is settled.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. spring-cloud/spring-cloud-openfeign on GitHub