2.HSF快速入门

快速入门

HSF (High-speed Service Framework)，高速服务框架，是在阿里巴巴内部广泛使用的分布式 RPC 服务框架。HSF 作为阿里巴巴的基础中间件，联通不同的业务系统，解耦系统间的实现依赖。

本文将向初次使用 HSF 的用户介绍如何快速的发布一个服务，以及如何通过远程调用消费这个服务。全文共包含以下内容：

运行环境
服务的定义与实现
发布 HSF 服务
消费 HSF 服务

1. 运行环境

HSF 使用 Java 语言编写，同时也包含 C++, NodeJS 等多语言实现。本文以 Java 语言版本的 HSF 为例，向大家介绍如何通过 HSF 发布、消费分布式服务，对运行环境的要求包含：

网络环境：阿里巴巴集团办公网
操作系统：Mac OXS / Windows / Linux 等均可，只要保证支持 Java 运行环境
Java：1.6, 1.7, 1.8 均可，推荐使用 1.8
Maven: 2.x, 3.x 均可，并且配置了阿里巴巴集团 Maven 仓库

2. 服务的定义与实现

“服务” 始于接口的定义，我们首先需要根据业务逻辑定义好服务的接口。

在日常开发中，一般会将服务的接口定义在一个工程中，它会被打成一个 jar 包，发布到 maven 仓库中。服务端实现 jar 包中的接口，通过 HSF 发布对应的服务；而消费端通过依赖这个 jar 包，透过 HSF 远程调用消费到服务端的接口实现。

本文中的代码工程范例，可以在 hsf-guide 中获取。

2.1 定义服务接口

本文目的在于快速的展示 HSF 的使用方法，因此仅定义一个非常简单的 HelloWorldService 用于演示，并将它放在 hsf-guide-api 这个工程中。

public interface HelloWorldService {

    /**
     * 根据参数中指定的名字，生成问候语
     *
     * @param name 被问候的姓名
     * @return 问候语
     */
    String sayHi(String name);
}

2.2 发布服务接口

通过执行 mvn clean package 命令，我们可以将 hsf-guide-api 这个服务接口工程打包成 hsf-guide-api-1.0.0-SNAPSHOT.jar，需要调用这个接口的服务消费方，可以通过依赖这个 jar 包实现服务描述的依赖，从而完成远程调用。

通过执行 mvn clean deploy 命令将服务的接口 jar 发布到 maven 仓库后，我们可以通过 maven 坐标依赖服务的接口：

<dependency>
    <groupId>com.alibaba.middleware</groupId>
    <artifactId>hsf-guide-api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2.3 编写服务实现

在完成服务接口的定义后，服务提供方需要根据业务逻辑对接口进行实现。我们将服务 HelloWorldService 的实现类 HelloWorldServiceImpl 放在 hsf-guide-biz 工程中：

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.";
    }
}

在我们的范例中，HelloWorldService 的业务逻辑很简单：若 name 不为空，则使用 name 生成问候语并返回；否则，返回 null。

至此，我们的服务提供方实现代码就编写完成了，并且还没有涉及到 HSF。这是因为，我们希望你的服务接口（API）和业务实现可以足够的干净，只有这样一个依赖精简的本地服务才能够更加安全可靠的转换成为一个分布式服务。

3. 发布 HSF 服务

根据服务接口定义 HelloWorldService 完成本地服务 HelloWorldServiceImpl 的实现后，我们只需要将这个服务通过 HSF 发布出去，就可以让其他 HSF 客户端通过远程调用消费到当前机器的服务了。

我们将发布 HSF 服务的代码，放在 hsf-guide-server-normal 工程中，并作为 HSF 服务提供方的启动入口。

3.1 添加 HSF 依赖

为 hsf-guide-server-normal 工程增加 maven 配置，从而引入 HSF 的依赖：

<dependency>
  <groupId>com.taobao.hsf</groupId>
  <artifactId>hsf-all</artifactId>
</dependency>

3.2 配置并发布 HSF 服务

在 hsf-guide-server-normal 工程中创建 Start 类，并添加启动 main 函数。在 main 函数中通过装配 HSFApiProviderBean 将服务 HelloWorldService 发布出去：

HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();

// [设置] 发布服务的接口
hsfApiProviderBean.setServiceInterface("com.alibaba.middleware.hsf.guide.api.service.HelloWorldService");
// [设置] 服务的实现对象，target 为 HelloWorldServiceImpl 的实例
hsfApiProviderBean.setTarget(target);
// [设置] 服务的版本
hsfApiProviderBean.setServiceVersion("1.0.0");
// [设置] 服务的组别
hsfApiProviderBean.setServiceGroup("HSF");
// [设置] 服务的响应时间
hsfApiProviderBean.setClientTimeout(5000);
// [设置] 服务传输业务对象时的序列化类型
hsfApiProviderBean.setPreferSerializeType("hessian2");

// [发布] HSF服务
hsfApiProviderBean.init();

以上配置中，需要强调的是 serviceInterface, version, serviceGroup，它们三者构成了 HSF 中最为关键概念：

服务名：即 serviceInterface:version
组别：即 serviceGroup

服务名和组别唯一决定了服务的发布、订阅关系。

除了 API 的方式外，HSF 还支持 Spring XML、SpringBoot 注解等方式配置、发布服务，具体请参考用户指南 - 发布服务这一小节。

启动 Start 类的 main 函数后，可以前往 HSFOPS（HSF 控制台）的日常环境查询服务 com.alibaba.middleware.hsf.guide.api.service.HelloWorldService:1.0.0，从而验证服务是否发布成功。

service search

查询到服务后，点击 “详情” 按钮，只要在服务详情页的 “服务发布者” 列表中看到本机 IP，就表明服务发布成功了。

service detail

4. 消费 HSF 服务

现在，服务接口定义的 jar 包已经 deploy 到 maven 仓库，HSF 服务也已经发布成功了，接下来服务的客户端只需要依赖接口定义，并引入 HSF 就可以消费远程的 HelloWorldService 服务了。

4.1 添加服务接口依赖

创建 hsf-guide-client 工程，作为客户端消费服务的工程。

客户端在消费服务前，首先需要向服务提供方咨询服务接口定义 jar 包的 maven 坐标，在本文中，即 hsf-guide-api 的坐标：

<dependency>
    <groupId>com.alibaba.middleware</groupId>
    <artifactId>hsf-guide-api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

4.2 添加 HSF 依赖

为 hsf-guide-client 工程增加 maven 配置，从而引入 HSF 的依赖：

<dependency>
  <groupId>com.taobao.hsf</groupId>
  <artifactId>hsf-all</artifactId>
  <version>2.2.5.0-SNAPSHOT</version>
</dependency>

4.3 配置并消费 HSF 服务

创建 Start 类，并添加启动 main 函数。在 main 函数中通过装配 HSFApiConsumerBean 订阅服务 OrderService，并在初始化完成后，像调用本地代码一样，通过代理调用远程的 HSF 服务：

HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();

// [设置] 订阅服务的接口
hsfApiConsumerBean.setInterfaceName("com.alibaba.middleware.hsf.guide.api.service.HelloWorldService");
// [设置] 服务的版本
hsfApiConsumerBean.setVersion("1.0.0");
// [设置] 服务的组别
hsfApiConsumerBean.setGroup("HSF");

// [订阅] HSF 服务，同步等待地址推送，默认 false (异步)，同步默认超时时间 3000 毫秒
hsfApiConsumerBean.init(true);

// [代理] 获取 HSF 代理
HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();

// [调用] 像调用本地接口一样，发起 HSF 调用
String hi = helloWorldService.sayHi("xiaozi");
System.out.println(hi);

除了 API 的方式外，HSF 还支持 Spring XML、SpringBoot 注解等方式配置、消费服务，具体请参考用户指南 - 发布服务这一小节。

HSFApiConsumerBean 构建完成后，HSF 就会根据代码中设置的服务名（interfaceName:version）和组别（group）订阅服务的地址，并在发起调用时，随机选取其中的一个服务提供方执行远程调用。

在服务提供方启动的状态下，运行上述代码，将会输出：

Hi, xiaozi! Welcome to the HSF world.

至此，HelloWorldService 这个服务的发布与消费过程，就全部完成了。

5. 总结

本文以 HelloWorldService 这个简单的服务为例，介绍了如何定义、编写、发布、消费 HSF 服务的完整过程，所有的源码都可以在 hsf-guide 工程中下载到，其中涉及到的子模块如下：

服务接口定义：
    hsf-guide
           | --- hsf-guide-api

服务提供方：
    hsf-guide
           | --- hsf-guide-biz
           | --- hsf-guide-server-normal

服务消费方：
    hsf-guide
           | --- hsf-guide-client-normal