Referência da API HSF - Enterprise Distributed Application Service: Central de Documentação do Alibaba Cloud

Pré-requisitos

Antes de começar, verifique se você tem:

O SDK do EDAS adicionado como dependência do Maven (consulte Adicionar a dependência)
Uma interface de serviço e sua classe de implementação

Adicionar a dependência

Adicione a seguinte dependência ao arquivo pom.xml:

<dependency>
    <groupId>com.alibaba.edas</groupId>
    <artifactId>edas-sdk</artifactId>
    <version>{version}</version>
</dependency>

Substitua {version} pela versão do seu SDK do EDAS.

Publicar um serviço (ProviderBean)

Um bean provedor publica a implementação de uma interface de serviço no registro HSF para que os consumidores possam descobri-la e invocá-la.

Importante

Inicialize cada HSFApiProviderBean apenas uma vez por serviço. Armazene o objeto em cache após a inicialização, pois sua criação consome muitos recursos.

Abordagem com API Java

Use com.taobao.hsf.app.api.util.HSFApiProviderBean para publicar um serviço programaticamente.

// Instantiate and configure a provider bean.
HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
hsfApiProviderBean.setServiceInterface("com.taobao.hsf.test.HelloWorldService");
hsfApiProviderBean.setTarget(target); // target is the implementation object of the interface specified by serviceInterface.
hsfApiProviderBean.setServiceVersion("1.0.0");
hsfApiProviderBean.setServiceGroup("HSF");

// Initialize the provider bean to publish the service.
hsfApiProviderBean.init();

Abordagem com Spring XML

Use com.taobao.hsf.app.spring.util.HSFSpringProviderBean em um arquivo de configuração do Spring para publicar um serviço declarativamente.

<bean id="helloWorldService" class="com.taobao.hsf.test.HelloWorldService" />

<bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
    <!-- [Required] Service interface -->
    <property name="serviceInterface" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Implementation object (Spring bean ID) -->
    <property name="target" ref="helloWorldService" />

    <!-- [Optional] Service version. Default: 1.0.0 -->
    <property name="serviceVersion" value="1.0.0" />

    <!-- [Optional] Service group. Default: HSF -->
    <property name="serviceGroup" value="HSF" />

    <!-- [Optional] Service description -->
    <property name="serviceDesc" value="HelloWorldService providered by HSF" />

    <!-- [Optional] Response timeout in milliseconds. Default: 3000 -->
    <property name="clientTimeout" value="3000"/>

    <!-- [Optional] Per-method timeout. Takes precedence over clientTimeout. -->
    <property name="methodSpecials">
        <list>
            <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
                <property name="methodName" value="sum" />
                <property name="clientTimeout" value="2000" />
            </bean>
        </list>
    </property>

    <!-- [Optional] Serialization method. Valid values: java, hessian, hessian2, json, kryo. Default: hessian2 -->
    <property name="preferSerializeType" value="hessian2"/>

    <!-- [Optional] Minimum threads in a dedicated thread pool. Default: shared HSF thread pool -->
    <property name="corePoolSize" value="10"/>

    <!-- [Optional] Maximum threads in a dedicated thread pool. Default: shared HSF thread pool -->
    <property name="maxPoolSize" value="60"/>
</bean>

Propriedades do ProviderBean

Propriedade	Tipo	Obrigatório	Padrão	Descrição
serviceInterface	String	Sim	N/A	Interface que fornece o serviço HSF. Os consumidores usam esta interface para assinar o serviço.
target	Object	Sim	N/A	Objeto de implementação da interface especificada por serviceInterface.
serviceVersion	String	Não	1.0.0	Versão do serviço. Os consumidores usam este valor para assinar uma versão específica.
serviceGroup	String	Não	HSF	Grupo do serviço. Os consumidores usam este valor para assinar um grupo específico.
serviceDesc	String	Não	N/A	Descrição do serviço para fins de gerenciamento.
clientTimeout	int	Não	3000	Tempo limite de resposta em milissegundos. Lança `HSFTimeOutException` se o provedor não responder dentro do prazo.
methodSpecials	MethodSpecial[]	Não	N/A	Substituições de tempo limite por método. Defina `MethodSpecial.methodName` com o nome do método e `MethodSpecial.clientTimout` com o valor do tempo limite em milissegundos. Esta configuração tem precedência sobre clientTimeout.
preferSerializeType	String	Não	hessian2	Protocolo de serialização para dados de requisição e resposta. Valores válidos: `java`, `hessian`, `hessian2`, `json`, `kryo`.
corePoolSize	String (valor inteiro)	Não	0	Número mínimo de threads em um pool dedicado para este serviço. Se não definido, usa-se o pool de threads compartilhado do provedor HSF.
maxPoolSize	String (valor inteiro)	Não	0	Número máximo de threads em um pool dedicado para este serviço. Se não definido, usa-se o pool de threads compartilhado do provedor HSF.

Assinar um serviço (ConsumerBean)

Um bean consumidor assina um serviço HSF publicado e fornece um objeto proxy para invocação remota.

Importante

Inicialize cada HSFApiConsumerBean apenas uma vez por serviço. Armazene em cache tanto o objeto bean quanto o proxy retornado, pois a criação de ambos consome muitos recursos.

Aviso

O HSFApiConsumerBean armazena as configurações de serviço em cache internamente. Se você configurar o mesmo serviço várias vezes, apenas a primeira configuração terá efeito.

Abordagem com API Java

Use com.taobao.hsf.app.api.util.HSFApiConsumerBean para assinar um serviço programaticamente.

// Instantiate and configure a consumer bean.
HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
hsfApiConsumerBean.setInterfaceName("com.taobao.hsf.test.HelloWorldService");
hsfApiConsumerBean.setVersion("1.0.0");
hsfApiConsumerBean.setGroup("HSF");

// Initialize the consumer bean.
// true = wait synchronously for address push (timeout: 3000 ms).
// false (default) = initialize asynchronously.
hsfApiConsumerBean.init(true);

// Get the HSF proxy object.
HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();

// Call the remote service.
String helloStr = helloWorldService.sayHello("Li Lei");

Abordagem com Spring XML

Use com.taobao.hsf.app.spring.util.HSFSpringConsumerBean em um arquivo de configuração do Spring para assinar um serviço declarativamente.

<bean id="helloWorldService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
    <!-- [Required] Service interface name -->
    <property name="interfaceName" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Service version -->
    <property name="version" value="1.0.0" />

    <!-- [Required] Service group -->
    <property name="group" value="HSF" />

    <!-- [Optional] Request timeout in milliseconds. Consumer timeout takes precedence over provider timeout. -->
    <property name="clientTimeout" value="3000" />

    <!-- [Optional] Per-method timeout. Takes precedence over clientTimeout. -->
    <property name="methodSpecials">
        <list>
            <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
                <property name="methodName" value="sum" />
                <property name="clientTimeout" value="2000" />
            </bean>
        </list>
    </property>

    <!-- [Optional] Synchronous wait time (ms) for Config Server to push a service address.
         Prevents HSFAddressNotFoundException when the service is called before the address arrives.
         Recommended: 5000 -->
    <property name="maxWaitTimeForCsAddress" value="5000"/>

    <!-- [Optional] Async call methods. Format: name:<method>;type:<future|callback>;listener:<class>
         The listener field only applies to the callback type and must implement HSFResponseCallback. -->
    <property name="asyncallMethods">
        <list>
            <value>name:sayHello;type:callback;listener:com.taobao.hsf.test.service.HelloWorldServiceCallbackHandler</value>
        </list>
    </property>

    <!-- [Optional] Proxy mode. Default: jdk. Set to javassist to block the consumer bean. -->
    <property name="proxyStyle" value="jdk" />
</bean>

Propriedades do ConsumerBean

Propriedade	Tipo	Obrigatório	Padrão	Descrição
interfaceName	String	Sim	N/A	Nome da interface a ser assinada.
version	String	Sim	N/A	Versão do serviço de destino.
group	String	Sim	N/A	Grupo do serviço de destino.
clientTimeout	int	Não	N/A	Tempo limite da requisição em milissegundos. Lança `HSFTimeOutException` se nenhuma resposta for recebida. O tempo limite do consumidor tem precedência sobre o do provedor. Se não definido, aplica-se o tempo limite do provedor.
methodSpecials	MethodSpecial[]	Não	N/A	Substituições de tempo limite por método. Defina `MethodSpecial.methodName` com o nome do método e `MethodSpecial.clientTimout` com o tempo limite em milissegundos. Este parâmetro tem precedência sobre clientTimeout.
maxWaitTimeForCsAddress	int	Não	N/A	Tempo de espera síncrona, em milissegundos, para o Config Server enviar o endereço do serviço. Evita `HSFAddressNotFoundException` quando o serviço é chamado antes da chegada do endereço. Valor recomendado: 5000.
asyncallMethods	List	Não	N/A	Métodos para chamada assíncrona. Cada entrada segue o formato `name:<method>;type:<type>;listener:<class>`. Tipos válidos: `future` (recupera o resultado com um objeto Future) e `callback` (o HSF invoca o listener após a conclusão da chamada). O campo `listener` aplica-se apenas ao tipo `callback` e deve implementar `HSFResponseCallback`.
proxyStyle	String	Não	jdk	Modo de proxy. Defina como `javassist` para bloquear o bean consumidor.

Padrões de chamada assíncrona

O HSF suporta dois padrões de chamada assíncrona para métodos consumidores, configurados pela propriedade asyncallMethods:

Padrão	Funcionamento
`future`	Retorno imediato. Recupere o resultado posteriormente com um objeto `Future`.
`callback`	Retorno imediato. O HSF invoca o listener registrado assim que a resposta chega. O listener deve implementar `HSFResponseCallback`.

Classe	Função	Abordagem
`HSFApiProviderBean`	Publicar um serviço	API Java
`HSFSpringProviderBean`	Publicar um serviço	Spring XML
`HSFApiConsumerBean`	Assinar um serviço	API Java
`HSFSpringConsumerBean`	Assinar um serviço	Spring XML