HSF (High‑speed Service Framework) Overview and Usage Guide

Background

Monolithic applications suffer from tight coupling between business modules, which hinders rapid business evolution. Splitting a monolith into multiple services requires a reliable, high‑performance RPC framework to enable remote calls.

What is HSF?

HSF (High‑speed Service Framework) is Alibaba’s primary SOA solution. It acts as a bridge between heterogeneous business systems, decoupling implementation dependencies. Its high performance stems from non‑blocking I/O and an efficient serialization mechanism, supporting both synchronous and asynchronous calls.

Key Service‑Governance Capabilities

Easy service discovery – query providers and consumers.

Quick service testing – simple, efficient test interfaces.

Dynamic routing – runtime routing based on service name, version, etc.

Automatic service grouping – organize services by machine resources.

Basic Structure

HSF consists of six components: Service Consumer, Service Provider, Address Registry, Persistent Config Center, Metadata Store, and the HSF Management Console. The first three are mandatory.

Call Process

The client serializes the request object, wraps it in an HSF protocol message, and sends it via an I/O thread. The server decodes, deserializes, invokes the target method via reflection, serializes the response, and sends it back. The client decodes the response and returns the result to the original thread.

Service Interface Definition

public interface HelloWorldService {
    /**
     * Generate a greeting based on the given name.
     * @param name the name to greet
     * @return greeting string
     */
    String sayHi(String name);
}

Service Implementation

public class HelloWorldServiceImpl implements HelloWorldService {
    @Override
    public String sayHi(String name) {
        if (name == null || name.length() == 0) {
            return null;
        }
        return "Hi, " + name + "! Welcome to the HSF world.";
    }
}

Service Publishing

API style

Object target = new HelloWorldServiceImpl();
HSFApiProviderBean provider = new HSFApiProviderBean();
provider.setServiceInterface("com.alibaba.middleware.hsf.guide.api.service.HelloWorldService");
provider.setTarget(target);
provider.setServiceVersion("1.0.0");
provider.setServiceGroup("HSF");
provider.setClientTimeout(3000);
provider.setSerializeType("hessian2");
provider.init();

Annotation style

@HSFProvider(serviceInterface = HelloWorldService.class,
            serviceGroup = "HSF",
            serviceVersion = "1.0.0",
            clientTimeout = 3000,
            serializeType = "hessian2")
public class HelloWorldServiceImpl implements HelloWorldService {
    // same implementation as above
}

Service Invocation

API consumer

HSFApiConsumerBean consumer = new HSFApiConsumerBean();
consumer.setInterfaceName("com.alibaba.middleware.hsf.guide.api.service.HelloWorldService");
consumer.setVersion("1.0.0");
consumer.setGroup("HSF");
consumer.init(true);
HelloWorldService hello = (HelloWorldService) consumer.getObject();
String hi = hello.sayHi("Alice");
System.out.println(hi);

Future asynchronous call

List
asyncMethods = new ArrayList<>();
asyncMethods.add("name:sayHi;type:future");
consumer.setAsyncallMethods(asyncMethods);
consumer.init(true);
HelloWorldService hello = (HelloWorldService) consumer.getObject();
String hi = hello.sayHi("Bob"); // returns null immediately
HSFFuture future = HSFResponseFuture.getFuture();
System.out.println(future.getResponse(3000));

Callback asynchronous call

public class MyCallbackHandler implements HSFResponseCallback {
    @Override
    public void onAppException(Throwable t) { t.printStackTrace(); }
    @Override
    public void onAppResponse(Object o) {
        Object ctx = CallbackInvocationContext.getContext();
        System.out.println(o.toString() + ctx);
    }
    @Override
    public void onHSFException(HSFException e) { e.printStackTrace(); }
}

List
asyncMethods = new ArrayList<>();
asyncMethods.add("name:sayHi;type:callback;listener:com.alibaba.middleware.hsf.guide.client.handler.CallbackHandler");
consumer.setAsyncallMethods(asyncMethods);
consumer.init(true);
CallbackInvocationContext.setContext(" in callback");
hello.sayHi("Carol");
CallbackInvocationContext.setContext(null);

Generic invocation (no API jar needed)

consumer.setGeneric("true");
consumer.init(true);
GenericService generic = (GenericService) consumer.getObject();
String result = (String) generic.$invoke("sayHi",
        new String[]{String.class.getName()},
        new Object[]{"Dave"});
System.out.println(result);

Configuration Highlights

Serialization – supported types: java, hessian, hessian2 (default), json, kryo. Kryo offers the best performance, while java provides the best compatibility.

Timeout – client timeout overrides server timeout; default is 3000 ms. Configure per‑service according to business latency requirements.

Server Thread Pool – configurable via JVM parameters or code; default values are shown in the original diagrams.

Routing Rules – stored in Diamond. Rules can be interface‑level, method‑level, or parameter‑level. They are written in Groovy scripts and applied during the consumer’s address selection phase.

Grouping Rules – also stored in Diamond (XML format). They assign services to logical groups, enabling group‑based clustering.

Same‑Room Rule – prefers providers in the same data‑center based on IP subnet. Disabled by default; enable by appending the rule to existing routing configuration.

Design Patterns Used in HSF

Chain of Responsibility – HSF builds a protocol interceptor chain where each interceptor can process or forward the request. Interceptors are ordered by @Order annotation.

Protocol protocol = HSFServiceContainer.getInstance(Protocol.class);
List
handlers = HSFServiceContainer.getInstances(ProtocolInterceptor.class);
Protocol last = protocol;
for (int i = handlers.size() - 1; i >= 0; i--) {
    handlers.get(i).setProtocol(last);
    last = handlers.get(i);
}
return last;

Proxy Pattern – client side creates a dynamic proxy that implements the service interface (or a decorated interface) and forwards method calls to the remote provider.

Object proxy = proxyFactory.getProxy(metadata, decorateInterfaces);
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    ConsumerMethodModel methodModel = serviceMetadata.getConsumerServiceModel().getMethodModel(method);
    return InvocationUtil.invoke(methodModel, args);
}

Observer Pattern – routing rule listeners are registered with the event bus; when a rule changes, all listeners are notified to refresh their local cache.

public void registerListener(Object listener) {
    synchronized (eventBus) {
        if (lastRule != null) {
            eventBusHelp.register(listener);
            eventBusHelp.post(lastRule);
            eventBusHelp.unregister(listener);
        }
        eventBus.register(listener);
    }
}

Decorator Pattern – the proxy can be decorated with additional interfaces (e.g., for metrics, tracing) before being generated.

@Shared
@Scope(Scope.Option.SINGLETON)
public interface ProxyDecorator {
    Class
decorate(ServiceMetadata serviceMetadata);
}

ProxyDecoratorGenerator generator = HSFServiceContainer.getInstance(ProxyDecoratorGenerator.class);
Class
[] decorateInterfaces = generator.getDecorateInterfaces(metadata);
Object proxy = proxyFactory.getProxy(metadata, decorateInterfaces);

Team Introduction

The authors belong to the Marketing & Platform Strategy Technology team of the Taobao Group. They support large‑scale promotional activities (Double 11, 618, etc.) and daily sales platforms such as Taobao Good Price, Billion‑Subsidy, and Juhuasuan. Their culture emphasizes simplicity, openness, and self‑drive.