Principle:Apache Dolphinscheduler RPC Service Contract Definition
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Systems, RPC |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
An annotation-driven contract definition pattern that uses Java interfaces with @RpcService and @RpcMethod annotations to declare remote procedure call contracts between distributed services.
Description
The RPC Service Contract Definition principle establishes a clean separation between service interface and implementation in DolphinScheduler's distributed architecture. Service contracts are defined as Java interfaces annotated with @RpcService at the class level, with each remote method annotated with @RpcMethod specifying optional timeout and retry strategies. These interfaces serve as the single source of truth for both client-side proxy generation and server-side method registration.
This approach solves the problem of maintaining consistent APIs across distributed services without code duplication. Both the RPC client proxy factory and the server-side handler use the same interface for method identification, serialization, and routing.
Usage
Define a service contract when creating a new inter-service communication channel in DolphinScheduler. Place the interface in a shared dolphinscheduler-extract-{module} module so both client and server can reference it. Use @RpcMethod to configure per-method timeouts and retry behavior.
Theoretical Basis
The RPC Service Contract pattern applies Contract-First Design principles:
- Interface as Contract: The Java interface defines the complete API surface
- Annotation Metadata: @RpcService and @RpcMethod provide framework-level configuration
- Shared Module: Contract interfaces live in extract modules accessible by both client and server
- Method Identification: Methods are identified by fully-qualified name for routing
// Contract definition pattern
@RpcService
interface IMyService {
@RpcMethod(timeout = 5000)
ResponseType operation(RequestType request);
}
// Both client proxy and server handler derive behavior from this contract:
// Client: proxy.operation(request) -> serialize & send via Netty
// Server: handler.invoke("IMyService.operation", request) -> execute & return