本篇介绍 HSF 框架的开发应用。

HSF 应用开发

启动轻量级配置及注册中心

使用 Ali-Tomcat 开发应用

• Ali-Tomcat 概述
• 安装及开发环境配置
• 开发 HSF 应用（SDK）

使用 Pandora Boot 开发应用

• Pandora Boot 概述
• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 开发 HSF 应用（Pandora Boot）
• 开发 RESTful 应用（不推荐）
• 将 Dubbo 应用迁移到 HSF（不推荐）

将应用从 HSF 架构迁移到 Dubbo（Ali-Tomcat）

一次调用过程

HSF 的一次调用过程是从服务消费方发起，经过网络抵达服务提供方，再将服务提供方的结果通过网络携带返回，最终返回给用户。该过程涉及多线程交互，同时也涉及 HSF 中的不同领域对象。

HSF 的一次调用过程如下图所示：

过程	说明
1	在客户端线程中将用户的请求参数即请求对象进行序列化，并将序列后的内容存放在请求通信的对象中。 说明 请求通信对象对应的是 HSF 协议，包括了请求 ID 等多个与请求对象无关的内容。
2	系统将请求通信对象递交给 I/O 线程，并在 I/O 线程中完成编码。
3	编码完成后，将内容传递到服务提供方的 I/O 线程。客户端线程会等待结果返回。
4	服务提供方的 I/O 线程接收到二进制内容，解码后生成通信请求对象，并将其递交给 HSF 服务端线程。
5	在 HSF 服务端线程完成反序列化还原成请求对象。
6	发起反射调用，并得到结果，即响应对象。
7	响应对象会在 HSF 服务端线程中完成序列化，并存储在通信响应对象中。
8	HSF 服务端线程将通信响应对象递交给 I/O 线程，在 I/O 线程中完成编码。
9	服务提供方将 I/O 线程中完成编码，发送回服务消费方。
10	服务消费方收到二进制内容，在 I/O 线程中完成解码，生成响应通信对象，并唤醒客户端线程。
11	客户端线程根据响应通信对象中的内容进行反序列化，用户收到响应对象，一次远程调用结束。

异步调用

前提条件

在开发应用前，您已经完成以下工作：

• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 启动轻量级配置及注册中心

同步调用

HSF 的 IO 操作是异步操作，客户端同步调用的本质是执行future.get（timeout）操作，等待服务端的结果返回，这里的 timeout 就是客户端生效的超时时间 （默认 3000 ms）。同步调用时序图如下所示：

对于客户端来说，并不是所有的 HSF 服务都是需要同步等待服务端返回结果的，对于这些服务，HSF 提供异步调用的形式，让客户端不必同步阻塞在 HSF 操作上。 异步调用在发起调用时，HSF 服务的调用结果都是返回值的默认值，例如返回类型是 int，则会返回 0，返回类型是 Object，则会返回 null。而真正的结果，是在 HSFResponseFuture 或者回调函数（callback）中获得的。

Future 异步调用

HSF 发起调用后，用户可以在上下文中获取跟返回结果关联的HSFFuture对象，获取对象后调用 HSFFuture.getResponse(timeout) 获取服务端的返回结果。Future 异步调用的时序图如下所示：

• API 形式配置 HSF 服务

  HSF 提供了方法级别的异步调用配置，格式为name:${methodName};type:future，由于只用方法名字来标识方法，所以并不区分重载的方法。同名的方法都会被设置为同样的调用方式。

  HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
  hsfApiConsumerBean.setInterfaceName("com.alibaba.middleware.hsf.guide.api.service.OrderService");
  hsfApiConsumerBean.setVersion("1.0.0");
  hsfApiConsumerBean.setGroup("HSF");
  // [设置] 异步future调用
  List<String> asyncallMethods = new ArrayList<String>();
  // 格式：name:{methodName};type:future
  asyncallMethods.add("name:queryOrder;type:future");
  hsfApiConsumerBean.setAsyncallMethods(asyncallMethods);
  
  hsfApiConsumerBean.init(true);
  
  // [代理] 获取HSF代理
  OrderService orderService = (OrderService) hsfApiConsumerBean.getObject();
  // ---------------------- 调用 -----------------------//
  // [调用] 发起HSF异步调用, 返回null
  OrderModel orderModel = orderService.queryOrder(1L);
  // 及时在当前调用上下文中，获取future对象；因为该对象是放在ThreadLocal中，同一线程中后续调用会覆盖future对象，所以要及时取出
  HSFFuture hsfFuture = HSFResponseFuture.getFuture();
  
  // do something else
  
  // 这里才真正地获取结果，如果调用还未完成，将阻塞等待结果，5000ms是等待结果的最大时间
  try {
      System.out.println(hsfFuture.getResponse(5000));
  } catch (InterruptedException e) {
      e.printStackTrace();
  }

  HSF 默认的超时配置是 3000ms，如果过了超时时间，业务对象未返回，这时调用 HSFFuture.getResponse 会抛出超时异常；HSFFuture.getResponse(timeout)，如果这里的 timeout 时间内，业务结果没有返回，也没有超时，可以调用多次执行 getResponse 去获取结果。

• Spring 配置 HSF 服务

  Spring 框架在应用中广泛使用，如果不想以 API 的形式配置 HSF 服务，您可以使用 Spring XML 的形式进行配置，上述例子中 API 配置等同于如下 XML 配置。

  <bean id="orderService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
      <property name="interfaceName" value="com.alibaba.middleware.hsf.guide.api.service.OrderService"/>
      <property name="version" value="1.0.0"/>
      <property name="group" value="HSF"/>
      <!--[设置] 订阅服务的接口 -->
      <property name="asyncallMethods">
          <list>
              <value>name:queryOrder;type:future</value>
          </list>
       </property>
  </bean>

• 注解配置 HSF 服务

  SpringBoot 广泛使用的今天，使用注解装配 SpringBean 也成为一种选择，HSF 也支持使用注解进行配置，用来订阅服务。

  在项目中增加依赖 starter。

  <dependency>
      <groupId>com.alibaba.boot</groupId>
      <artifactId>pandora-hsf-spring-boot-starter</artifactId>
  </dependency>

  通常一个 HSF Consumer 会在多个地方使用，但并不需要在每次使用的地方都用 @HSFConsumer 来标记。只需要写一个统一个 Config 类，然后在其它需要使用的地方，直接 @Autowired 注入即可。上述例子中的 API 配置等同于如下注解配置。

  @Configuration
  public class HsfConfig {
      @HSFConsumer(serviceVersion = "1.0.0", serviceGroup = "HSF", futureMethods = "sayHelloInFuture")
      OrderService orderService;
  }

  在使用时直接注入即可。

  @Autowired
  OrderService orderService;

Callback 异步调用

客户端配置为 callback 方式调用时，需要配置一个实现了 HSFResponseCallback 接口的 listener，结果返回之后，HSF 会调用 HSFResponseCallback 中的方法。时序图如下所示：

• API 形式配置 HSF 服务

  callback 的调用上下文

  用户在调用前还可以通过 CallbackInvocationContext.setContext(Object obj)，来设置一个关于本次调用的上下文信息，该信息存放在 threadlocal 中。在 listener 的回调函数中，可以通过 CallbackInvocationContext.getContext() 来获取该对象。

  回调函数示例

  public class CallbackHandler implements HSFResponseCallback {
  
      // 业务异常时会触发
      @Override
      public void onAppException(Throwable t) {
          t.printStackTrace();
      }
  
      // 业务返回结果
      @Override
      public void onAppResponse(Object result) {
          // 取callback调用时设置的上下文
          Object context = CallbackInvocationContext.getContext();
          System.out.println(result.toString() + context);
      }
      //HSF异常
      @Override
      public void onHSFException(HSFException e) {
          e.printStackTrace();
      }
  }

  接口 callback 方法配置

  HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
  hsfApiConsumerBean.setInterfaceName("com.alibaba.middleware.hsf.guide.api.service.OrderService");
  hsfApiConsumerBean.setVersion("1.0.0");
  hsfApiConsumerBean.setGroup("HSF");
  // [设置] 异步callback调用
  List<String> asyncallMethods = new ArrayList<String>();
  asyncallMethods.add("name:queryOrder;type:callback;listener:com.alibaba.middleware.hsf.CallbackHandler");
  hsfApiConsumerBean.setAsyncallMethods(asyncallMethods);
  hsfApiConsumerBean.init(true);
  // [代理] 获取HSF代理
  OrderService orderService = (OrderService) hsfApiConsumerBean.getObject();
  // 可选步骤，设置上下文。CallbackHandler中通过api可以获取到CallbackInvocationContext.setContext("in callback");
  // 发起调用
  orderService.queryOrder(1L); // 这里返回的其实是 null
  // 清理上下文
  CallbackInvocationContext.setContext(null);
  // do something else

  在调用线程中可以设置上下文，然后在 listener 中获取使用。相对于 Future 异步调用，callback 会立即知晓结果的返回。

• Spring 配置 HSF 服务

  <bean id="CallHelloWorld" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
      <!--[设置] 订阅服务的接口 -->
      <property name="interfaceName" value="com.alibaba.middleware.hsf.guide.api.service.OrderService"/>
      <!--[设置] 服务的版本 -->
      <property name="version" value="1.0.0"/>
      <!--[设置] 服务的归组 -->
      <property name="group" value="HSF"/>
      <property name="asyncallMethods">
          <list>
              <!--future的含义为通过Future的方式去获取请求执行的结果，例如先调用下远程的接口，接着在同一线程继续做别的事情，然后再在同一线程中通过Future来获取结果 -->
              <!--name:methodName;type:future|callback-->
              <value>name:queryOrder;type:callback;listener:com.alibaba.middleware.hsf.CallbackHandler</value>
          </list>
       </property>
  </bean>

• 注解配置 HSF 接口方法为 callback 调用

  @AsyncOn(interfaceName = OrderService.class, methodName = "queryOrder")
  public class CallbackHandler implements HSFResponseCallback {
  
      @Override
      public void onAppException(Throwable t) {
          t.printStackTrace();
      }
  
      @Override
      public void onAppResponse(Object result) {
          // 取callback调用时设置的上下文
          Object context = CallbackInvocationContext.getContext();
          System.out.println(result.toString() + context);
      }
  
      @Override
      public void onHSFException(HSFException e) {
          e.printStackTrace();
      }
  }

  注意 回调函数是由单独的线程池（ LinkedBlockingQueue 无限队列）来调用的，不要做太费时间的操作，避免影响其他请求的 onAppResponse 回调。callback 线程默认的 corePoolSize、maxPoolSize 是实例 CPU 数目。 下面的 -D 参数可以去自定义配置。

  • CALLBACK 线程池最小配置：-Dhsf.callback.min.poolsize
  • CALLBACK 线程池最大配置：-Dhsf.callback.max.poolsize

泛化调用

相对于需要依赖业务客户端 JAR 包的正常调用，泛化调用不需要依赖二方包，使用其特定的 GenericService 接口，传入需要调用的方法名、方法签名和参数值进行调用服务。 泛化调用适用于一些网关应用（没办法依赖所有服务的二方包），其中 hsfops 服务测试也是依赖泛化调用功能。

前提条件

在开发应用前，您已经完成以下工作：

• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 启动轻量级配置及注册中心

API 形式配置 HSF 服务

将 HSFConsumerBean 配置 generic 为 true，HSF 客户端将忽略加载不到接口的异常。

HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
hsfApiConsumerBean.setInterfaceName("com.alibaba.middleware.hsf.guide.api.service.OrderService");
hsfApiConsumerBean.setVersion("1.0.0");
hsfApiConsumerBean.setGroup("HSF");
// [设置] 泛化配置
hsfApiConsumerBean.setGeneric("true");
hsfApiConsumerBean.init(true);

// 使用泛化接口获取代理
GenericService genericOrderService = (GenericService) hsfApiConsumerBean.getObject();
// ---------------------- 调用 -----------------------//
// [调用] 发起HSF泛化调用, 返回map类型的result
Map orderModelMap = (Map) genericOrderService.$invoke("queryOrder",
                            // 方法入参类型数组（xxx.getClass().getName())
                            new String[] { Long.class.getName() },
                            // 参数，如果是pojo，则需要转成Map
                            new Object[] { 1L});

GenericService 提供的 $invoke 方法包含了真实调用的方法名、入参类型和参数，以便服务端找到该方法。由于没有依赖服务端的 API JAR 包，传入的参数如果是自定义的 DTO，需要转成客户端可以序列化的 Map 类型。

调用方法和参数说明

• 方法没有入参，可以只传 methodName: service.$invoke("sayHello", null, null)。

• 方法类型有泛型的，列如 List<String>，只需要传 java.util.List，即 List.class.getName() 的值，不要传成 java.util.List<String>，否则会出现方法找不到的错误。

• 调用方法在不确定格式的情况下，可以写个单元测试，测试时依赖需要泛化调用的二方包，使用 HSF 提供的工具类 com.taobao.hsf.util.PojoUtils 的 generalize() 方法来生成一个 pojo Bean 的 Map 描述格式。

  Map pojoMap = (Map) PojoUtils.generalize(new OrderModel());

• 传递参数为 pojo 的 demo。

  class User {
     private String name;
     private int age;
     // 需要是标准的pojo格式，这里省略getter setter
    }
    
    // 直接使用map去构造pojo对应的泛化参数
    Map param = new HashMap<String, Object>();
    param.put("age", 11);
    param.put("name","Miles");
    // 当传递的参数是声明参数类型的子类时，需要传入class字段，标明该pojo的真实类型（服务端需要有该类型）
    param.put("class", "com.taobao.User");

Spring 配置 HSF 服务

Spring 框架是在应用中广泛使用的组件，如果不想通过 API 的形式配置 HSF 服务，可以使用 Spring XML 的形式进行配置，上述例子中的 API 配置等同于如下 XML 配置。

<bean id="CallHelloWorld" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
    <!--[设置] 订阅服务的接口 -->
    <property name="interfaceName" value="com.alibaba.middleware.hsf.guide.api.service.OrderService"/>
    <!--[设置] 服务的版本 -->
    <property name="version" value="1.0.0"/>
    <!--[设置] 服务的归组 -->
    <property name="group" value="HSF"/>
    <property name="generic" value="true"/>
</bean>

注意事项

• 泛化调用，如果客户端没有接口类，路由规则默认不生效。

• 泛化调用性能会比正常调用差。

• 配置

  -D hsf.generic.throw.exception=true （默认是false, 把异常泛化成map返回）

  抛出业务异常。

  本地存在异常类，如果不是 RuntimeException 类型或其子类，则会抛出 UndeclaredThrowableException，这是由于 com.taobao.hsf.remoting.service.GenericService 上没有声明该异常，可以通过 getCause 获取真实异。

  本地没有该异常类，则抛出 com.taobao.hsf.util.GenericInvocationException。

调用上下文

请求上下文包括一次调用相关的属性，例如调用的地址，调用方的应用名，超时时间等属性和用户在接口定义的参数之外传递自定义的数据。

设置和获取本次调用上下文

com.taobao.hsf.util.RequestCtxUtil 提供设置和获取调用上下文的静态方法，基于 ThreadLocal 工作， getXXX 操作会将 XXX 属性从当前 ThreadLocal 变量中 remove，仅作用于当前线程的单次调用。

具体属性的设置和获取如下：

• 客户端

  方法	说明
  setRequestTimeout()	设置单次调用的超时时间。
  setUserId()	设置本次调用的单元化服务的 User ID（泛化调用中需要通过此方法配置）。
  getProviderIp()	获取最近一次调用的服务端的 IP。
  setTargetServerIp(String ip)	设置当前线程下一次调用的目标服务器 IP（此 IP 必须包含在内存已提供服务的地址列表里）。
  setDirectTargetServerIp(String targetIp)	设置当前线程下一次调用的目标服务器 IP（绕过注册中心，忽略内存里的地址列表）。

• 服务端

  方法	说明
  getClientIp()	服务端获取调用方 IP。
  getAppNameOfClient()	服务端获取调用方的应用名。
  isHttpRequest()	是否是 HTTP 调用。
  getHttpHeader(String key)	获取 HTTP 请求的 Header 属性。

传递自定义请求上下文

RpcContext 提供一种不修改接口，向服务端额外传递数据的方式。参数可以是自定义的 DO 或者基本类型。要保证对端也有该对应的类型，并且可以能够被序列化。

• 客户端发起调用前，设置上下文。

  //setup context before rpc call
  RPCContext rpcContext = RPCContext.getClientContext();
  rpcContext.putAttachment("tetantId", "123");
  
  //rpc call，context 也会传到远端
  orderService.queryOrder(1L);

• 服务端业务方法内，获取上下文。

  //get context data
  RPCContext rpcContext = RPCContext.getServerContext();
  String myContext = (String)rpcContext.getAttachment("tetantId");

序列化方式选择

序列化的过程是将 Java 对象转成 byte 数组在网络中传输，反序列化会将 byte 数组转成 Java 对象。

简介

序列化的选择需要考虑兼容性，性能等因素，HSF 的序列化方式支持 Java、hessian2，默认是 hessian2。序列化方式的对比和配置（只在服务端配置 HSFApiProviderBean）如下表所示。

序列化方式	Maven依赖	配置	兼容性	性能
hessian2	hsf-io-serialize-hessian2	setPreferSerializeType("hessian2")	好	好
java	hsf-io-serialize-java	setPreferSerializeType("java")	佳	一般

前提条件

在开发应用前，您已经完成以下工作：

• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 启动轻量级配置及注册中心

API 形式配置 HSF 服务

HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
hsfApiProviderBean.setPreferSerializeType("hessian2");

Spring 配置 HSF 服务

Spring 框架是在应用中广泛使用的组件，如果不想通过 API 的形式配置 HSF 服务，可以使用 Spring XML 的形式进行配置，上述例子中的 API 配置等同于如下 XML 配置。

<bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
    <!--[设置] 发布服务的接口 -->
    <property name="serviceInterface" value="com.alibaba.middleware.hsf.guide.api.service.OrderService"/>
    <!--[设置] 服务的实现对象target必须配置 [ref]，为需要发布为HSF服务的spring bean id-->
    <property name="target" ref="引用的BeanId"/>
    <!--[设置] 服务的版本 -->
    <property name="serviceVersion" value="1.0.0"/>
    <!--[设置] 服务的归组 -->
    <property name="serviceGroup" value="HSF"/>
    <!--[设置] 服务的响应时间 -->
    <property name="clientTimeout" value="3000"/>
    <!--[设置]  服务传输业务对象时的序列化类型 -->
    <property name="preferSerializeType" value="hessian2"/>
</bean>

超时配置

本文介绍开发 HSF 应用过程中如何进行超时配置。

前提条件

在开发应用前，您已经完成以下工作：

• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 启动轻量级配置及注册中心

背景信息

有关网络调用的请求，都需要配置超时，HSF 的默认超时时间是 3000ms。客户端和服务端都可以设置超时，默认优先采用客户端的配置，如果客户端没有配置，使用服务端的超时配置。 在服务端设置超时时，需要考虑到业务本身的执行耗时，加上序列化和网络通讯的时间。所以推荐服务端给每个服务都配置个默认的时间。当然客户端也可以根据自己的业务场景配置超时时间，例如一些前端应用，需要用户快速看到结果，可以把超时时间设置小一些。

配置的作用范围、作用域，按照优先级由高到低如下表所示。

优先级	API	范围	作用域
0	com.taobao.hsf.util.RequestCtxUtil#setRequestTimeout	客户端	单次调用
1	HSFApiConsumerBean#setMethodSpecials	客户端	方法
2	HSFApiConsumerBean#setClientTimeout	客户端	接口
3	-D defaultHsfClientTimeout	客户端	所有接口
4	HSFApiProviderBean#setMethodSpecials	服务端	方法
5	HSFApiProviderBean#setClientTimeout	服务端	接口

说明 客户端配置优先于服务端，方法优先于接口。

客户端超时配置

• API 形式配置 HSF 服务。

  配置 HSFApiConsumerBean 的 clientTimeout 属性，单位是 ms，我们把接口的超时配置为 1000ms，方法 queryOrder 配置为 100ms，代码如下。

  HSFApiConsumerBean consumerBean = new HSFApiConsumerBean();
  // 接口级别超时配置
  consumerBean.setClientTimeout(1000);
  //xxx
  MethodSpecial methodSpecial = new MethodSpecial();
  methodSpecial.setMethodName("queryOrder");
  // 方法级别超时配置，优先于接口超时配置
  methodSpecial.setClientTimeout(100);
  consumerBean.setMethodSpecials(new MethodSpecial[]{methodSpecial});

• Spring 配置 HSF 服务。

  Spring 框架是在应用中广泛使用的组件，如果不想通过 API 的形式配置 HSF 服务，可以使用 Spring XML 的形式进行配置，上述例子中的 API 配置等同于如下 XML 配置。

  <bean id="CallHelloWorld" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
      ...
      <property name="clientTimeout" value="1000" />
      <property name="methodSpecials">
        <list>
          <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
            <property name="methodName" value="queryOrder" />
            <property name="clientTimeout" value="100" />
          </bean>
        </list>
      </property>
      ...
  </bean>

• 注解配置。

  SpringBoot 广泛使用的今天，使用注解装配 SpringBean 也成为一种选择，HSF 也支持使用注解进行配置，用来订阅服务。

  1. 在项目中增加依赖 starter。

     <dependency>
         <groupId>com.alibaba.boot</groupId>
         <artifactId>pandora-hsf-spring-boot-starter</artifactId>
     </dependency>

  2. 在代码中注解配置。

     通常一个 HSF Consumer 需要在多个地方使用，但并不需要在每次使用的地方都用 @HSFConsumer 来标记。只需要写一个统一个 Config 类，然后在其它需要使用的地方，直接 @Autowired 注入即可上述例子中的 API 配置等同于如下注解配置。

     @HSFConsumer(clientTimeout = 1000, methodSpecials = @HSFConsumer.ConsumerMethodSpecial(methodName = "queryOrder", clientTimeout = "100"))
     private OderService orderService;

• 客户端全局接口超时配置。

  • 在启动参数中添加 -D defaultHsfClientTimeout=100
  • 在代码中添加 System.setProperty("defaultHsfClientTimeout", “100”)

服务端方法超时配置

• API 配置 HSF 服务。

  配置 HSFApiProviderBean 的 clientTimeout 属性，单位是 ms，代码如下。

  HSFApiProviderBean providerBean = new HSFApiProviderBean();
  // 接口级别超时配置
  providerBean.setClientTimeout(1000);
  // xxx
  MethodSpecial methodSpecial = new MethodSpecial();
  methodSpecial.setMethodName("queryOrder");
  // 方法级别超时配置，优先于接口超时配置
  methodSpecial.setClientTimeout(100);
  providerBean.setMethodSpecials(new MethodSpecial[]{methodSpecial});

• Spring 配置 HSF 服务。

  Spring 框架是在应用中广泛使用的组件，如果不想通过 API 的形式配置 HSF 服务，可以使用 Spring XML 的形式进行配置，上述例子中的 API 配置等同于如下 XML 配置。

  <bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
      ...
      <property name="clientTimeout" value="1000" />
      <property name="methodSpecials">
        <list>
          <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
            <property name="methodName" value="queryOrder" />
            <property name="clientTimeout" value="2000" />
          </bean>
        </list>
      </property>
      ...
  </bean>

• 注解配置 HSF 服务。

  注入即可上述例子中的 API 配置等同于如下注解配置。

  @HSFProvider(serviceInterface = OrderService.class, clientTimeout = 3000)
  public class OrderServiceImpl implements OrderService {
      @Autowired
      private OrderDAO orderDAO;
  
      @Override
      public OrderModel queryOrder(Long id) {
          return orderDAO.queryOrder(id);
      }
  }

服务端线程池配置

本文介绍开发 HSF 应用过程中如何进行服务端线程池配置。

前提条件

在开发应用前，您已经完成以下工作：

• 配置 EDAS 的私服地址和轻量级配置及注册中心
• 启动轻量级配置及注册中心

服务线程池业务示意图

HSF 服务端线程池主要分为 IO 线程和业务线程，其中 IO 线程模型就是 netty reactor 网络模型中使用的。我们主要讨论业务线程池的配置。业务线程池分为默认业务线程池和服务线程池，其中服务线程池是从默认线程池中分割出来的。

默认线程池配置

服务端线程池是用来执行业务逻辑的线程池，线程池默认的 core size 是 50，max size 是 720，keepAliveTime 500s。队列使用的是 SynchronousQueue，没有缓存队列，不会堆积用户请求。 当服务端线程池所有线程（720）都在处理请求时，对于新的请求，会立即拒绝，返回 Thread pool is full 异常。可以使用下面 VM 参数（-D 参数）进行配置。

• 线程池最小配置：-D hsf.server.min.poolsize
• 线程池最大配置：-D hsf.server.max.poolsize
• 线程收敛的存活时间：-D hsf.server.thread.keepalive

服务线程池配置

对于一些慢服务、并发高，可以为其单独配置线程池，以免占用过多的业务线程，影响应用的其他服务的调用。

• API 形式配置 HSF 服务

  HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
  //...
  hsfApiProviderBean.setCorePoolSize("50");
  hsfApiProviderBean.setMaxPoolSize("200");

• Spring 配置 HSF 服务

  Spring 框架是在应用中广泛使用的组件，如果不想通过 API 的形式配置 HSF 服务，可以使用 Spring XML 的形式进行配置，上述例子中的 API 配置等同于如下 XML 配置。

  <bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
      <!--[设置] 发布服务的接口 -->
      <property name="serviceInterface" value="com.alibaba.middleware.hsf.guide.api.service.OrderService"/>
      <property name="corePoolSize" value="50" />
      <property name="maxPoolSize" value="200" />
  </bean>

• 注解配置 HSF 服务

  SpringBoot 广泛使用的今天，使用注解装配 SpringBean 也成为一种选择，HSF 也支持使用注解进行配置，用来发布服务。

  1. 在项目中增加依赖 starter。

     <dependency>
         <groupId>com.alibaba.boot</groupId>
         <artifactId>pandora-hsf-spring-boot-starter</artifactId>
     </dependency>

  2. 将 @HSFProvider 配置到实现的类型。

     上述例子中的 API 配置等同于如下注解配置。

     @HSFProvider(serviceInterface = OrderService.class, corePoolSize = 50, maxPoolSize = 200)
     public class OrderServiceImpl implements OrderService {
         @Autowired
         private OrderDAO orderDAO;
     
         @Override
         public OrderModel queryOrder(Long id) {
             return orderDAO.queryOrder(id);
         }
     }

API 手册

在 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: 通过 Spring 配置的方式创建 Provider Bean。
• com.taobao.hsf.app.spring.util.HSFSpringConsumerBean: 通过 Spring 配置的方式创建 Consumer Bean。

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

ProviderBean

• API 编程方式 - HSFApiProviderBean

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

  对于一个服务，com.taobao.hsf.app.api.util.HSFApiProviderBean 的配置及初始化过程只需配置一次。此外，考虑到 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 配置方式 - HSFSpringConsumerBean

  通过在 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>

JVM -D 启动配置参数

本文介绍 HSF 应用开发时 JVM -D 启动参数的配置信息。

-D hsf.server.port

指定 HSF 的启动服务绑定端口，默认为 12200。如果在本地启动多个 HSF Provider，则需要修改此端口。

-D hsf.server.max.poolsize

指定 HSF 的服务端最大线程池大小，默认值为720。

-D hsf.server.min.poolsize

指定 HSF 的服务端最小线程池大小，默认值为50。

-D hsf.client.localcall

打开或者关闭本地优先调用，默认值为true。

-D pandora.qos.port

指定 Pandora 监控端口，默认值为12201。如果在本地启动多个 HSF Provider，则需要修改此端口。

-D hsf.http.enable

是否开启 HTTP 端口，默认为 true。

-D hsf.http.port

指定 HSF 暴露的 HTTP 接口，默认值为12220。如果在本地启动多个 HSF Provider，则需要修改此端口。

-D hsf.run.mode

指定 HSF 客户端是否指定 target 进行调用，即绕开 ConfigServer。值为1，表示不允许指定 target 调用；值为0，表示允许指定 target 调用。默认值为1时，不推荐指定为0。

-D hsf.shuthook.wait

HSF 优雅关闭的等待时间，单位是 ms，默认是10000。

-D hsf.publish.delayed

是否所有的服务都需要延迟发布，默认是false，不需要延迟发布 。

-D hsf.server.ip

指定需要绑定的 IP 地址。在多网卡情况下默认绑定第一个网卡，通过该参数指定需要绑定的 IP。

-D HsfBindHost

指定需要绑定的 Host。在多网卡情况下默认绑定和上报给地址注册中心第一个网卡的IP地址，通过该参数可以指定需要绑定的 Host，列如-DHsfBindHost=0.0.0.0将 HSF Server 端口绑定本机所有网卡。

-D hsf.publish.interval=400

指定发布服务之间的时间间隔。HSF 服务发布时会瞬间暴露出去，在应用启动时如果承受不住压力，可以配置该参数。默认值是 400，单位 ms。

-D hsf.client.low.water.mark=32 -D hsf.client.high.water.mark=64 -D hsf.server.low.water.mark=32 -D hsf.server.high.water.mark=64

指定客户端或者服务端的每个 channel 写缓冲的限制。

• 客户端每个 channel 的写缓冲的限制，单位为 KB，一旦超过高水位，channel 禁写，新的请求放弃写出，直接报错。禁写之后，等到缓冲区低于低水位才能恢复。
• 服务端每个 channel 的写缓冲的限制，单位为 KB，超过高水位时，新的响应放弃写出，客户端收不到响应会超时。缓冲区低于低水位时才能恢复写。
• 高低水位需成对设置，并且需要高水位大于低水位。

-D hsf.generic.remove.class=true

获取泛化调用的结果，但不输出class字段信息。

-D defaultHsfClientTimeout

全局的客户端超时配置。

-D hsf.invocation.timeout.sensitive

hsf.invocation.timeout.sensitive 默认值设置为 false，决定 HSF 调用时间是否包含创建连接、选址等耗时逻辑。

打赏