背景信息

在 HSF 面向用户的 API 中,最为关键的就是与创建 ProviderBean 和 ConsumerBean 相关的 API 了。根据用户使用的场景不同,主要分为 4 个关键的类。
  • com.taobao.hsf.app.api.util.HSFApiProviderBean: 通过 API 编程的方式创建 Provider Bean
  • com.taobao.hsf.app.api.util.HSFApiConsumerBean: 通过 API 编程的方式创建 Consumer Bean
  • com.taobao.hsf.app.spring.util.HSFSpringProviderBean: 通过 Spirng 配置的方式创建 Provider Bean
  • com.taobao.hsf.app.spring.util.HSFSpringConsumerBean: 通过 Spirng 配置的方式创建 Consumer Bean

其中,HSFSpringXxxBean 的配置属性与 HSFApiXxxBean 的 setter 方法相对应。接下来就分别以 ProviderBean 和 ConsumerBean 的视角介绍这 4 个类的 API。

ProviderBean

  • API 编程方式 - HSFApiProviderBean

    通过配置并初始化 com.taobao.hsf.app.api.util.HSFApiProviderBean 即可完成 HSF 服务的发布。

    对于一个服务,该过程只需要做一次。此外,考虑到 HSFApiProviderBean 对象比较重,建议缓存起来。

    • 范例代码:
      // 实例化并配置 Provider Bean
      HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
      hsfApiProviderBean.setServiceInterface("com.taobao.hsf.test.HelloWorldService");
      hsfApiProviderBean.setTarget(target); // target 为 serviceInterface 指定接口的实现对象
      hsfApiProviderBean.setServiceVersion("1.0.0");
      hsfApiProviderBean.setServiceGroup("HSF");
      
      // 初始化 Provider Bean,发布服务
      hsfApiProviderBean.init();
    • 可配置属性表:

      除上述范例代码中设置的属性,HSFApiProviderBean 还包含许多其他可配置的属性,均可通过对应的 setter 方法进行设置。

      属性名 类型 是否必选 默认值 含义
      serviceInterface String 设置 HSF 服务对外提供的业务接口。 客户端通过此属性进行订阅。
      target Object 设置 serviceInterface 指定接口的服务实现对象。
      serviceVersion String 1.0.0 设置服务的版本号。 客户端通过此属性进行订阅。
      serviceGroup String HSF 设置服务的组别。 客户端通过此属性进行订阅。
      serviceDesc String null 设置服务的描述,从而方便管理。
      clientTimeout int 3000 设置响应超时时间(单位:毫秒)。如果服务端在设置的时间内没有返回,则抛出 HSFTimeOutException。
      methodSpecials MethodSpecial[] 设置服务中某些方法的响应超时时间。通过设置 MethodSpecial.methodName 指定方法名,通过设置 MethodSpecial.clientTimout 指定当前方法的超时时间,优先级高于当前服务端的 clientTimeout。
      preferSerializeType String hessian2 针对 HSF2,设置服务的请求参数和响应结果的序列化方式。可选值有:java,hessian,hessian2,json,kryo。
      corePoolSize 值为整型的 String 0 配置服务单独的线程池,并指定最小活跃线程数量。若不设置该属性,则默认使用 HSF 服务端的公共线程池。
      maxPoolSize 值为整型的 String 0 配置服务单独的线程池,并指定最大活跃线程数量。若不设置该属性,则默认使用 HSF 服务端的公共线程池。
  • Spring 配置方式 - HSFSpringProviderBean

    通过在 Spring 配置文件中,配置一个 class 为 com.taobao.hsf.app.spring.util.HSFSpringProviderBean 的 bean,即可完成 HSF 服务的发布。

    示例代码

    <bean id="helloWorldService" class="com.taobao.hsf.test.HelloWorldService" />
    
    <bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
        <!-- [必选] 设置 HSF 服务对外提供的业务接口 -->
        <property name="serviceInterface" value="com.taobao.hsf.test.HelloWorldService" />
    
        <!-- [必选] 设置 serviceInterface 指定接口的服务实现对象,即需要发布为 HSF 服务的 spring bean id -->
        <property name="target" ref="helloWorldService" />
    
        <!-- [可选] 设置服务的版本号,默认为 1.0.0 -->
        <property name="serviceVersion" value="1.0.0" />
    
        <!-- [可选] 设置服务的组别,默认为 HSF -->
        <property name="serviceGroup" value="HSF" />
    
        <!-- [可选] 设置服务的描述,从而方便管理,默认为 null -->
        <property name="serviceDesc" value="HelloWorldService providered by HSF" />
    
        <!-- [可选] 设置响应超时时间(单位:毫秒)。如果服务端在设置的时间内没有返回,则抛出 HSFTimeOutException -->
        <!-- 默认为 3000 ms -->
        <property name="clientTimeout" value="3000"/>
    
        <!-- [可选] 设置服务中某些方法的响应超时时间。优先级高于上面的 clientTimeout -->
        <!-- 通过设置 MethodSpecial.methodName 指定方法名,MethodSpecial.clientTimout 指定方法的超时时间 -->
        <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>
    
        <!-- [可选] 设置服务的请求参数和响应结果的序列化方式。可选值有:java,hessian,hessian2,json,kryo -->
        <!-- 默认为 hessian2 -->
        <property name="preferSerializeType" value="hessian2"/>
    
        <!-- [可选] 配置服务单独的线程池,并指定最小活跃线程数量。若不设置该属性,则默认使用 HSF 服务端的公共线程池 -->
        <property name="corePoolSize" value="10"/>
    
        <!-- [可选] 配置服务单独的线程池,并指定最大活跃线程数量。若不设置该属性,则默认使用 HSF 服务端的公共线程池 -->
        <property name="maxPoolSize" value="60"/>
    </bean>

ConsumerBean

  • API 配置方式 - HSFApiConsumerBean

    通过配置并初始化 com.taobao.hsf.app.api.util.HSFApiConsumerBean 完成 HSF 服务的订阅。

    对于同一个服务,com.taobao.hsf.app.api.util.HSFApiConsumerBean的配置及初始化过程只需配置一次。

    由于 HSFApiConsumerBean 对象内容多,建议将该对象以及获取到的 HSF 代理进行缓存。
    说明 在 HSF 内部 HSFApiConsumerBean 对服务的配置是缓存起来的。即如果对某个订阅的服务进行了多次配置,只有第一次的配置生效。
    • 范例代码
      // 实例化并配置 Consumer Bean
      HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
      hsfApiConsumerBean.setInterfaceName("com.taobao.hsf.test.HelloWorldService");
      hsfApiConsumerBean.setVersion("1.0.0");
      hsfApiConsumerBean.setGroup("HSF");
      
      // 初始化 Consumer Bean,订阅服务
      // true 表示等待地址推送(超时时间为 3000 毫秒),默认为 false(异步)
      hsfApiConsumerBean.init(true);
      
      // 获取 HSF 代理
      HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();
      
      // 发起 HSF 调用
      String helloStr = helloWorldService.sayHello("Li Lei");
    • 可配置属性表

      除上述范例代码中设置的属性,,HSFApiConsumerBean 还包含许多其他可配置的属性,均可通过对应的 setter 方法进行设置。

      属性名 类型 是否必选 默认值 含义
      interfaceName String 设置需要订阅服务的接口名。 客户端通过此属性进行订阅。
      version String 设置需要订阅服务的版本号。 客户端通过此属性进行订阅。
      group String 设置需要订阅服务的组别。 客户端通过此属性进行订阅。
      clientTimeout int 设置请求超时时间(单位:毫秒)。如果客户端在设置的时间内没有收到服务端响应,则抛出 HSFTimeOutException。 若客户端设置了 clientTimeout,则优先级高于服务端设置的 clientTimeout。否则,在服务的远程调用过程中,使用服务端设置的 clientTimeout。
      methodSpecials MethodSpecial[] 设置服务中某些方法的请求超时时间。通过设置 MethodSpecial.methodName 指定方法名,通过设置 MethodSpecial.clientTimout 指定当前方法的超时时间,优先级高于当前客户端的 clientTimeout。
      maxWaitTimeForCsAddress int 设置同步等待 ConfigServer 推送地址的时间(单位:毫秒),从而避免因地址还未推送到就发起服务调用造成的 HSFAddressNotFoundException。一般建议设置为 5000 毫秒,即可满足推送等待时间。
      asyncallMethods List null 设置需要异步调用的方法列表。List 中的每一个字符串的格式为 name: 方法名;type: 异步调用类型;listener: 监听器,其中 listener 只对 callback 类型的异步调用生效。 type 的类型有:future: 通过 Future 的方式去获取请求执行的结果 callback: 当远程服务的调用完成后,HSF 会使用响应结果回调此处配置的 listener,该 listener 需要实现 HSFResponseCallback 接口
      proxyStyle String jdk 设置服务的代理模式,一般不用配置。如果要拦截这个 consumer bean,需要配置成 javassist。
  • Spring 配置方式 - HSFSpringProviderBean

    通过在 Spring 配置文件中,配置一个 class 为 com.taobao.hsf.app.api.util.HSFSpringConsumerBean 的 bean,即可实现服务的订阅。

    示例代码

    <bean id="helloWorldService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
        <!-- [必选] 设置需要订阅服务的接口名 -->
        <property name="interfaceName" value="com.taobao.hsf.test.HelloWorldService" />
    
        <!-- [必选] 设置需要订阅服务的版本号 -->
        <property name="version" value="1.0.0" />
    
        <!-- [必选] 设置需要订阅服务的组别 -->
        <property name="group" value="HSF" />
    
        <!-- [可选] 设置请求超时时间(单位:毫秒)。如果客户端在设置的时间内没有收到服务端响应,则抛出 HSFTimeOutException -->
        <!-- 若客户端设置了 clientTimeout,则优先级高于服务端设置的 clientTimeout。否则,在服务的远程调用过程中,使用服务端设置的 clientTimeout。-->
        <property name="clientTimeout" value="3000" />
    
        <!-- [可选] 设置服务中某些方法的请求超时时间,优先级高于当前客户端的 clientTimeout -->
        <!-- 通过设置 MethodSpecial.methodName 指定方法名,通过设置 MethodSpecial.clientTimout 指定当前方法的超时时间 -->
        <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>
    
        <!-- [可选] 设置同步等待 ConfigServer 推送地址的时间(单位:毫秒)-->
        <!-- 从而避免因地址还未推送到就发起服务调用造成的 HSFAddressNotFoundException。-->
        <!-- 一般建议设置为 5000 毫秒,即可满足推送等待时间。 -->
        <property name="maxWaitTimeForCsAddress"  value="5000"/>
    
        <!-- [可选] 设置需要异步调用的方法列表。List 中的每一个字符串的格式为:name: 方法名;type: 异步调用类型;listener: 监听器 -->
        <!-- 其中,listener 只对 callback 类型的异步调用生效。type 的类型有:-->
        <!-- future: 通过 Future 的方式去获取请求执行的结果 -->
        <!-- callback: 当远程服务的调用完成后,HSF 会使用响应结果回调此处配置的 listener,该 listener 需要实现 HSFResponseCallback 接口 -->
        <property name="asyncallMethods">
            <list>
                <value>name:sayHello;type:callback;listener:com.taobao.hsf.test.service.HelloWorldServiceCallbackHandler</value>
            </list>
        </property>
    
        <!-- [可选] 设置服务的代理模式,一般不用配置。如果要拦截这个 consumer bean,需要配置成 javassist -->
        <property name="proxyStyle" value="jdk" />
    </bean>