REST 服务快速入门

本地工程开发

SOFAREST 工程开发流程图

SOFAREST 示例代码演示视频

准备工作

• 搭建 SOFABoot 环境。具体操作，请参见 搭建环境。

• 通过以下任一方式生成 2 个 SOFABoot Web 工程，分别作为服务发布方和引用方。

  • 创建 2 个 SOFABoot Web 工程。具体操作，请参见 创建工程。

  • 直接下载 示例工程。下载后，请参考 版本说明 将工程根目录下 pom.xml 文件中的版本号修改为最新版本号。

本地开发流程

1. 引入依赖。

   按步骤创建的工程默认已经引入该依赖，请忽略此步骤；直接下载的示例工程需在 2 个本地 SOFABoot 工程 Web 模块 pom.xml 中引入 SOFARPC 的 Maven 依赖。

   <dependency>
       <groupId>com.alipay.sofa</groupId>
       <artifactId>rpc-enterprise-sofa-boot-starter</artifactId>
   </dependency>

2. 编写业务逻辑。

   主要为服务发布和服务引用。本示例使用注解的方式配置 Bean，实现服务发布和引用。更多详情，请参见 使用注解方式。其它配置方式，请参见 使用 XML 配置 及 使用编程 API。

   • 服务发布的业务逻辑

     • 设计服务接口类

       本示例类名称为 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){
                  //*************** 注意 ******************//
                 //本地同时启动 myserver-app 和 myclient-app 时，由于 tomcat 端口冲突问题，需要修改 myclient-app 的 端口号为 8084。
                 //将 myserver-app 和 myclient-app 发布到云上环境时，由于默认健康检查端口是 8080，所以需要注释掉该行代码。
                System.setProperty("server.port","8084");
                //由于本地启动没有注册中心，所以使用本地直连的方式访问本地启动的 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(new Runnable(){
                    @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);
                   }
            }
       }

3. 配置包扫描。

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

4. 配置本地运行的端口。

   1. 在 myserver-app Web 模块 application.properties 文件中配置 rpc.tr.port=12201。

      rpc.tr.port 是 TR 端口号，默认为 12200；TR = TaobaoRemoting 是 RPC 使用的底层通信框架。云端发布时不需要该项配置。

   2. 运行 Web 子模块中的 SOFABootWebSpringApplication。

      运行后，框架会自动进行服务的发布。为了避免端口冲突，需要在该类中指定端口。

      重要

      将 myserver-app 发布至云上环境前，必须注释掉代码中对 8083 端口的配置。

   3. 在 myclient-app Web 模块 application.properties 文件中配置 rpc.tr.port=12202。

      rpc.tr.port 是 TR 端口号，默认为 12200。云端发布时不需要该项配置。

5. 配置 application.properties 。

   1. 登录 SOFAStack 控制台。

   2. 在左侧导航栏选择 中间件 > 中间件总览。

      

      从中获取以下信息：

      • instanceld（实例标识）：应用实例在工作空间中的唯一标识。

        在 application.properties 中对应的 key 为 com.alipay.instanceid。

      • AntVIP endpoint：区域的唯一标识，每个区域一个地址。应用通过 AntVIP 寻找所在区域环境的地址。不同环境的 AntVIP 地址值如下：

        • 杭州金区：cn-hangzhou-fin-middleware-acvip-prod.cloud.alipaycs.net

        • 上海非金：cn-shanghai-middleware-acvip-prod.cloud.alipaycs.net

        • 上海金区：cn-shanghai-fin-sofastack-middleware-acvip-prod.cloud.alipaycs.net

        • 杭州非金：cn-hangzhou-middleware-acvip-prod.cloud.alipaycs.net

        在 application.properties中对应的 key 为 com.antcloud.antvip.endpoint。

      • Access Key ID：用于标识用户。单击 获取 AK 可前往 RAM 控制台获取。具体操作，请参见 创建 AccessKey。

        在 application.properties 中对应的 key 为 com.antcloud.mw.access。

      • Access Key Secret：用于验证用户。单击 获取 SK 可前往 RAM 控制台获取。具体操作，请参见 创建 AccessKey。

        在 application.properties 中对应的 key 为 com.antcloud.mw.secret。

   3. 配置运行模式和运行环境，示例如下：

      run.mode=NORMAL
      com.alipay.env=shared

   4. 将上述步骤获取的参数配置在 application.properties 文件中。

   说明

   更多信息，请参见 引入 SOFA 中间件。

示例工程

下文以示例工程为例，对 SOFARPC 的实现原理进行说明。

示例概述

通过 IDEA 或 Eclipse 分别打开 rpc-demo 中的 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 可引用服务。

示例工程服务验证

1. 启动 myserver-app Web 模块的 SOFABootWebSpringApplication 发布服务。

2. 启动 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 命令进行验证。

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

应用打包和云端发布

1. 打包本地应用。

   操作步骤，请参见 编译运行。

2. 发布应用。

   • 应用整体发布流程，请参见 技术栈与应用发布流程。

   • 应用的详细发布步骤，建议根据发布方式，参考下述文档：

     • 经典应用服务，请参见 经典应用服务快速入门。

     • 容器应用服务，请参见 容器应用服务快速入门。

服务管控

在 服务管控 页面查询并管控发布的 RPC 服务。更多详情，请参见 服务管控。