SOFAREST 快速入门 - SOFAStack 微服务

微服务（SOFAStack MicroService）主要是通过 SOFARPC 来实现服务的发布和引用，而 SOFARPC 支持 REST 协议。本文以微服务本地开发到云端发布的整体流程为框架，让您了解如何在本地实现 SOFAREST 功能，以及如何将应用发布到云端，并在云端进行服务管控。本文主要讲述 SOFAREST 的实现原理，示例工程也支持直连的方式，让您在本地体验 SOFAREST 的服务发布和服务引用。

本文主要结构如下：

本地工程开发
应用打包和云端发布
服务管控

本地工程开发

SOFAREST 工程开发流程图 REST流程图.png

SOFAREST 示例代码演示视频

前置条件

完成搭建环境。
创建 SOFABoot Web 工程，分别作为服务发布方和引用方。可采用下述任一方式：
- 自定义创建 2 个 SOFABoot Web 工程。
- 下载示例工程。下载后，请务必参考版本说明，将工程根目录下 pom.xml 中的版本号，修改为最新版本号。

本地开发流程

本地开发的主要步骤如下：

引入依赖：在 2 个本地 SOFABoot 工程 web 模块 pom.xml 中引入 SOFARPC 的 Maven 依赖。根据官网步骤所创建的工程默认已经引入该依赖。
```
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>rpc-enterprise-sofa-boot-starter</artifactId>
</dependency>
```

业务逻辑编写：主要为服务发布和服务引用。示例使用注解的方式配置 Bean，实现服务发布和引用。其它配置方式，请参考使用编程 API 及使用 XML 配置。

服务发布逻辑:

设计服务接口类：示例为 SampleRestFacade.java接口路径为：com.alipay.samples.rpc.SampleRestFacade

@Path("/sofarest")//注意该注解的继承性问题，实现类或方法中，该注解的缺失，可能会造成 SOFAREST 调用报 404 错误
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces(MediaType.APPLICATION_JSON +";charset=UTF-8")
public interface SampleRestFacade{
    /**
    * http://localhost:8341/sofarest/hello
    */
    @GET
    @Path("/hello")
    public String hello();
}

编写服务实现类：示例为 SampleRestFacadeImpl.java接口实现路径为：com.alipay.samples.rpc.impl.SampleRestFacadeImpl

@Service
@SofaService(interfaceType =SampleRestFacade.class,bindings =@SofaServiceBinding(bindingType ="rest"))
public class SampleRestFacadeImpl implements SampleRestFacade{
      private int count =0;

      public SampleRestFacadeImpl(){
          System.out.println("print start");
      }

     @Override
     public String hello(){
          return "Hello SOFARest! times = "+ count++;
     }
}

服务引用逻辑:

引用对象注入：示例采用 ReferenceHolder 类来对待引用对象进行统一管理，示例如下：

@Component
public class ReferenceHolder{
      @SofaReference(interfaceType =SampleRestFacade.class, binding =@SofaReferenceBinding(bindingType ="rest",directUrl ="127.0.0.1:8341"))
      private SampleRestFacade sampleRestFacade;
      public SampleRestFacade getSampleRestFacade(){
          return sampleRestFacade;
      }
     public void setSampleRestFacade(SampleRestFacade sampleRestFacade){
         this.sampleRestFacade = sampleRestFacade;
     }
}

说明

bindingType 为 rest 协议。直连 URL 端口为 8341，即 directUrl="127.0.0.1:8341"。

引用对象：为了方便直观使用，示例将引用服务逻辑放在了 myclient-app工程 Web 模块的 com.alipay.mytestsofa.SOFABootWebSpringApplication 中，示例如下：

@SpringBootApplication
public class SOFABootWebSpringApplication{
     private static final Logger logger =LoggerFactory.getLogger(SOFABootWebSpringApplication.class);

     public static void main(String[] args){
           //*************** 注意 ******************//
          //1. 本地同时启动 myserver-app 和 myclient-app 时，由于 tomcat 端口冲突问题，需要修改 myclient-app 的 端口号为 8084
          //2. 将 myserver-app 和 myclient-app 发布到云上环境时，由于默认健康检查端口是 8080，所以需要注释掉该行代码
         System.setProperty("server.port","8084");
         //3. 由于本地启动没有注册中心，所以使用本地直连的方式访问本地启动的 myserver-app，发布到线上的时候需要注释掉该行代码
         System.setProperty("run.mode","TEST");
         //********************************//

         SpringApplication springApplication =newSpringApplication(SOFABootWebSpringApplication.class);
         ApplicationContext applicationContext = springApplication.run(args);

          if(logger.isInfoEnabled()){
                printMsg("SofaRpc Application (myclient-app) started on 8084 port.");
          }

          ReferenceHolder referenceHolder = applicationContext.getBean(ReferenceHolder.class);
          //调用 SOFARest 服务
         final SampleRestFacade sampleRestFacade = referenceHolder.getSampleRestFacade();

          new Thread(newRunnable(){
             @Override
             public void run(){
                  while(true){
                          try{
                                   String response = sampleRestFacade.hello();
                                   printMsg("Response from myserver-app.rest: "+ response);
                          }catch(Exception e){
                                 e.printStackTrace();
                          }finally{
                                 try{
                                         TimeUnit.SECONDS.sleep(3);
                                  }catch(InterruptedException e){
                                      //ignore
                                 }
                            }
                      }
                 }
          }).start();
      }
     private static void printMsg(String msg){
          System.out.println(msg);
           if(logger.isInfoEnabled()){
                 logger.info(msg);
            }
     }
}

包扫描配置。

@SpringBootApplication(scanBasePackages ={"com.alipay.mytestsofa","com.alipay.samples.rpc"})
public class SOFABootWebSpringApplication{
...
}

本地端口处理:
- 在 myserver-app web 模块 application.properties 文件中配置 rpc.tr.port=12201。rpc.tr.port 是 TR 端口号，默认为 12200。云端发布时不需要该项配置。其中,TR = TaobaoRemoting，是 RPC 使用的底层通信框架。
- 运行 web 子模块中的 SOFABootWebSpringApplication，框架会自动进行服务的发布。为了避免端口冲突，需要在该类中指定端口。System.setProperty("server.port", "8083");
  警告
  将 myserver-app 发布至云上环境前，必须注释掉代码中对 8083 端口的配置。
- 在 myclient-app web 模块 application.properties 文件中配置 rpc.tr.port=12202。rpc.tr.port 是 TR 端口号，默认为 12200。云端发布时不需要该项配置。
在云端发布前，请务必进行 application.properties 配置。更多详情，请参考引入 SOFA 中间件。配置步骤如下：
1. 请前往 SOFAStack 控制台 > 研发效能 > 脚手架 > Step 2，示例如下：
  从中获取下述信息：
  - 实例标识：应用实例在工作空间中的唯一标识，在 application.properties 中对应的 key 为：com.alipay.instanceid。
  - AntVIP：应用通过 AntVIP 来获取各个组件的服务端地址，每个区域一个地址。在 application.properties 中对应的 key 为 com.antcloud.antvip.endpoint。不同环境的 AntVIP 地址值，见下述规定。
    - 杭州金区VPC：100.103.201.136
    - 上海非金：100.103.1.174
2. 在 脚手架 控制台，点击右上角用户图像，选择 AccessKey 管理，在跳转的页面中即可获取访问控制对应的属性值。这些属性在 application 中对应的 key 分别为：
  - Access Key（AK）：com.antcloud.mw.access
  - Access Secret Key（SK）：com.antcloud.mw.secret
    说明
    如果需要创建 AccessKey，可点击脚手架页面 > Step 2 中的获取 AK。AccessKey Secret 只在创建时显示，不提供查询，请妥善保管。更多详情，请参见创建 AccessKey。
3. 确定运行模式和运行环境，示例如下：
```
run.mode=NORMAL
com.alipay.env=shared
```
4. 将上述属性键和值，配置在 application.properties 文件中。

示例工程

下文以示例工程为例，对 SOFARPC 的实现原理进行说明，同时对业务逻辑进行示例。本部分主要包括：

示例概述
示例工程的 REST 实现

示例概述

通过 IDEA 或 Eclipse 将 rpc-demo 中的 2 个工程 myserver-app 和 myclient-app 分别打开。

示例工程关键信息

groupId: 工程组织的唯一标识，示例工程为 com.alipay.mytestsofa。
artifactId：工程的构件标识符，示例工程为 myserver-app 或 myclient-app。
version：版本号，默认为 1.0-SNAPSHOT。
package：应用包名，默认等同于 groupId，工程示例为 com.alipay.mytestsofa。

示例工程 Bean 配置

Bean 的配置分为服务发布和服务引用 2 个类型：

服务发布的示例如下：

@SofaService(interfaceType =SampleRestFacade.class,bindings =@SofaServiceBinding(bindingType ="rest"))

服务引用的示例如下：

@SofaReference(interfaceType =SampleRestFacade.class, binding =@SofaReferenceBinding(bindingType ="rest",directUrl ="127.0.0.1:8341"))
private SampleRestFacade sampleRestFacade;

说明

示例中，为了便于对所有待引用实例进行统一管理，创建了 ReferenceHolder 类，进行引用管理。

示例工程的 REST 实现

SOFAREST 的实现基于 SOFARPC，SOFARPC 的实现原理说明如下：

在 2 个工程的 endpoint 模块中相同位置，提供相同的服务接口和实现，并通过注解发现服务。2 个工程通过相同接口实现关联。一个客户端，一个服务端，如果是本地工程，在引用时，通过配置 directUrl，以直连方式发现服务；如果是服务器上部署测试，则通过 DSR（Direct Server Return）底座发现服务。
启动 myserver-app web 模块的 SOFABootWebSpringApplication，发布服务。
启动 myclient-app web 模块的 SOFABootWebSpringApplication，引用服务。

示例工程服务验证

首先，启动 myserver-app web 模块的 SOFABootWebSpringApplication 发布服务；
然后，启动 myclient-app web 模块的 SOFABootWebSpringApplication 引用服务；

引用成功后：

myclient-app 控制台将输出：

Response from myserver-app.rest:HelloSOFARest! times = xx

本地浏览器访问 http://localhost:8341/sofarest/hello，将输出访问 URL 链接那一刻,客户端的调用次数，示例如下：
```
HelloSOFARest! times = xx
```
云端发布后，可以在客户端命令行中输入命令：curl http://{服务器 IP 地址}:8341/sofarest/hello 进行验证。

您也可通过日志来查看服务引用结果。在 Web 子模块路径 src/main/resources/config/application.properties 中，可设置日志路径。默认在 /logs/myclient-app/common-default.log 中查看服务引用结果。

应用打包和云端发布

请参考编译运行中的步骤，完成本地应用的打包。
请参考下述信息，在 SOFAStack 控制台完成应用的云端发布：
- 应用整体的发布流程，请参考技术栈使用指南之 技术栈与应用发布流程。
- 应用的详细发布步骤，建议根据发布方式，参考下述文档：
  - 经典应用服务之快速入门。
  - 容器应用服务之快速入门。

服务管控

在 SOFAStack 控制台 > 中间件 > 微服务平台 > 微服务页面，可查询并管控发布的 RPC 服务。更多详情，请参见服务管控 > 服务查看及管理。服务查询