Support “Interface-as-Contract, Service-Name-as-Target” Declarative Client (e.g., `@ServiceClient`) for Protocol-Agnostic Service Invocation

[seal90]

Type: Enhancement

With the increasing service-ification of infrastructure (e.g., SaaS, DBaaS, STaaS) and the widespread adoption of microservices exposing capabilities via gRPC/Protobuf or HTTP/REST, invoking services by logical name—whether inside or outside the cluster—has become a natural and widely accepted pattern.

The service provider inherently owns the most authoritative contract: a Java interface with annotations.
Ideally, consumers should be able to:

• Reuse that exact interface directly,
• Invoke methods using only a logical service name (e.g., "user-service"),
• Enjoy local-method-like syntax without worrying about protocols, serialization, service discovery, or networking details.

This ideal centers on two core principles:
✅ Interface as Contract
✅ Service Name as Target

However, the current Spring Boot ecosystem lacks native support for this paradigm:

Protocol	Current Solution	Gap vs. Ideal Paradigm
HTTP	RestTemplate / WebClient	Manual URI/method/error handling; no interface reuse
HTTP	@HttpExchange + WebClient	Supports interfaces but requires explicit proxy creation
HTTP	@ImportHttpServices	Groups clients by service—closer to the ideal
HTTP	OpenFeign	Widely used, but forces consumers to duplicate interface definitions, violating "single source of truth"
gRPC	@ImportGrpcClients	Similar to @ImportHttpServices, but protocol-specific

Despite protocol differences, all scenarios point to the same need:

Let providers publish a Java interface; let consumers inject it via @ServiceClient("service-name")—no extra config, no duplication.

✨ Ideal usage example:

// Interface published by user-service (e.g., via shared library)
public interface UserClient {
    @GetMapping("/users/{id}")
    User getUser(@PathVariable String id);
}

// Consumer simply injects by logical service name
@Service
public class OrderService {

    @ServiceClient("user-service") // ← Resolved to actual endpoint automatically
    private final UserClient userClient;

    public void processOrder() {
        User user = userClient.getUser("123"); // Transparent remote call
    }
}

This pattern has already proven valuable in several ecosystems:

• gRPC: grpc-spring enables interface reuse and service-name binding via @GrpcClient("service-name").
• OpenFeign: Though it requires interface duplication, it demonstrates strong demand for declarative service clients.

I've built a working prototype (see #https://github.com/seal90/service-client-spring/).

Proposal

Could Spring Boot provide an official, lightweight, declarative service client abstraction (e.g., @ServiceClient) that supports the “interface reuse + service-name-as-target” paradigm?

It should offer:

1. Contract Reuse: Use the provider's published Java interface directly—no duplication.
2. Service-Name Driven: Resolve endpoints by logical name (e.g., "payment-service") and integrate with Spring Cloud LoadBalancer.
3. Protocol Agnostic: Start with HTTP support; extensible to gRPC, RSocket, etc.
4. Zero-Config Experience: Seamlessly integrate with Spring Boot observability (Micrometer), health checks, config refresh, and auto-configuration.

Adopting a “single source of truth + declarative invocation” model would dramatically reduce boilerplate and cognitive load for service-to-service communication.

[bclozel]

The core feature lives in Framework. Moving this issue to consider this there first.

[rstoyanchev]

Reading through the proposal it's difficult to find anything that HTTP Service Groups don't support. The one exception is the proposal to support multiple protocols, but I disagree with that.

For a start, HTTP vs HTTP OpenFeign is not a good example. We introduced HTTP Interfaces as an alternative to OpenFeign, and Spring Cloud OpenFeign actively encourages migrating.

The "service" and "channelName" come from gRPC, but don't map well to HTTP where we just need one name to group HTTP service interfaces that can share the same client instance (typically same target host), and the actual endpoint within the host is determined by the request path. The group name corresponds to the serviceId in Spring Cloud, and Spring Cloud already supports HTTP Service Groups that way.

Putting the annotation on a field is possibly also influenced by gRPC where interfaces are generated, and shouldn't be changed. To inject the same in two different places, I would need to duplicate the annotation and its attributes, and even then I probably won't get the same instance because there is no easy way to do that.

To put configuration attributes on annotation like that means there is no longer a concept of a centrally defined group that allows multiple interfaces to share the same client instance. We would have to look across all annotations to derive groups by detecting those with identical interface and annotation attributes. So for HTTP it would just be easier then to have 1 client per annotation, and that's not an outcome we want.

During the development of the HTTP Service Groups feature, we worked closely with Spring gRPC, Spring Cloud, and Spring Boot over many months. We knew we had a similar challenge with creating many beans for interface proxies in gRPC and in HTTP, but we only saw the need for alignment, not for a shared mechanism. There are sufficient differences to make that a stretch.