全部产品

SOFAREST 快速入门

更新时间:2020-08-28 09:58:13

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

本文主要结构如下:

本地工程开发

前置条件

本地开发流程

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

  1. 引入依赖: 在 2 个本地 SOFABoot 工程 web 模块 pom.xml 中引入 SOFARPC 的 Maven 依赖。根据官网步骤所创建的工程默认已经引入该依赖。
    1. <dependency>
    2. <groupId>com.alipay.sofa</groupId>
    3. <artifactId>rpc-enterprise-sofa-boot-starter</artifactId>
    4. </dependency>
  2. 业务逻辑编写:主要为服务发布和服务引用。示例使用注解的方式配置 Bean,实现服务发布和引用。其它配置方式,请参考 使用编程 API使用 XML 配置

  3. 包扫描配置。

  4. 配置 application.properties 文件。在本地体验时,无需配置。在云端发布前,请务必参考服务发布之 配置步骤 完成下述属性的配置。相关属性汇总如下:
    • run.mode=NORMAL
    • com.alipay.env=shared
    • com.alipay.instanceid=
    • com.antcloud.antvip.endpoint=
    • com.antcloud.mw.access=
    • com.antcloud.mw.secret=

示例工程

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

示例概述

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

示例工程关键信息

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

示例工程 Bean 配置

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

  • 服务发布,示例如下:
    1. @SofaService(interfaceType = SampleRestFacade.class,bindings = @SofaServiceBinding(bindingType = "rest"))
  • 服务引用,示例如下:
    1. @SofaReference(interfaceType = SampleRestFacade.class, binding = @SofaReferenceBinding(bindingType = "rest",directUrl = "127.0.0.1:8341"))
    2. private SampleRestFacade sampleRestFacade;

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

示例工程 RPC 实现原理

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 控制台将输出:

    1. Response from myserver-app.rest: Hello SOFARest! times = xx
  • 本地浏览器访问 http://localhost:8341/sofarest/hello,将输出访问 URL 链接那一刻,客户端的调用次数,示例如下:

    1. Hello SOFARest! times = xx
  • 云端发布后,可以在客户端命令行中输入命令:curl http://{服务器 IP 地址}:8341/sofarest/hello 进行验证。

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

示例工程的 REST 实现

服务发布

服务发布包含下述几个步骤:

  1. 设计服务接口类:示例为 SampleRestFacade.java
    接口路径为:com.alipay.samples.rpc.SampleRestFacade
    1. @Path("/sofarest") //注意该注解的继承性问题,实现类或方法中,该注解的缺失,可能会造成 SOFAREST 调用报 404 错误
    2. @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    3. @Produces(MediaType.APPLICATION_JSON + ";charset=UTF-8")
    4. public interface SampleRestFacade {
    5. /**
    6. * http://localhost:8341/sofarest/hello
    7. */
    8. @GET
    9. @Path("/hello")
    10. public String hello();
    11. }
  2. 编写服务实现类:示例为 SampleRestFacadeImpl.java
    接口实现路径为:com.alipay.samples.rpc.impl.SampleRestFacadeImpl

    1. @Service
    2. @SofaService(interfaceType = SampleRestFacade.class,bindings = @SofaServiceBinding(bindingType = "rest"))
    3. public class SampleRestFacadeImpl implements SampleRestFacade {
    4. private int count = 0;
    5. public SampleRestFacadeImpl(){
    6. System.out.println("print start");
    7. }
    8. @Override
    9. public String hello() {
    10. return "Hello SOFARest! times = " + count++;
    11. }
    12. }
  3. 包扫描
    1. @SpringBootApplication(scanBasePackages = {"com.alipay.mytestsofa","com.alipay.samples.rpc"})
    2. public class SOFABootWebSpringApplication {
    3. ...
    4. }
  4. 本地运行时的端口处理
    • 在 myserver-app web 模块 application.properties 文件中配置 rpc.tr.port=12201rpc.tr.port 是 TR 端口号,默认为 12200。云端发布时不需要该项配置。
    • 运行 web 子模块中的 SOFABootWebSpringApplication,框架会自动进行服务的发布。为了避免端口冲突,需要在该类中指定端口。System.setProperty("server.port", "8083");

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

  5. 在云端发布前,请务必进行 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 Management,在跳转的页面中即可获取访问控制对应的属性值。 这些属性在 application.properties 中对应的 key 分别为:

      • Access Key IDcom.antcloud.mw.access
      • Access Secretcom.antcloud.mw.secret

        说明:如果需要创建 AccessKey,可点击 获取 AK。更多详情,请参见 创建 AccessKey

    3. 配置运行模式和运行环境,示例如下:

      1. run.mode=NORMAL
      2. com.alipay.env=shared
    4. 将上述属性键和值,配置在 application.properties 文件中。

服务引用

通过注解方式实现对象注入和引用。更多详情,请参见 使用注解方式在示例工程 myclient-app 中,服务引用逻辑如下:

  1. 引用对象注入:示例采用 ReferenceHolder 类来对待引用对象进行统一管理,示例如下:

    1. @Component
    2. public class ReferenceHolder {
    3. @SofaReference(interfaceType = SampleRestFacade.class, binding = @SofaReferenceBinding(bindingType = "rest",directUrl = "127.0.0.1:8341"))
    4. private SampleRestFacade sampleRestFacade;
    5. public SampleRestFacade getSampleRestFacade() {
    6. return sampleRestFacade;
    7. }
    8. public void setSampleRestFacade(SampleRestFacade sampleRestFacade) {
    9. this.sampleRestFacade = sampleRestFacade;
    10. }
    11. }

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

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

    1. @SpringBootApplication
    2. public class SOFABootWebSpringApplication {
    3. private static final Logger logger = LoggerFactory.getLogger(SOFABootWebSpringApplication.class);
    4. public static void main(String[] args) {
    5. //*************** 注意 ******************//
    6. //1. 本地同时启动 myserver-app 和 myclient-app 时,由于 tomcat 端口冲突问题,需要修改 myclient-app 的 端口号为 8084
    7. //2. 将 myserver-app 和 myclient-app 发布到云上环境时,由于默认健康检查端口是 8080,所以需要注释掉该行代码
    8. System.setProperty("server.port", "8084");
    9. //3. 由于本地启动没有注册中心,所以使用本地直连的方式访问本地启动的 myserver-app,发布到线上的时候需要注释掉该行代码
    10. System.setProperty("run.mode", "TEST");
    11. //********************************//
    12. SpringApplication springApplication = new SpringApplication(SOFABootWebSpringApplication.class);
    13. ApplicationContext applicationContext = springApplication.run(args);
    14. if (logger.isInfoEnabled()) {
    15. printMsg("SofaRpc Application (myclient-app) started on 8084 port.");
    16. }
    17. ReferenceHolder referenceHolder = applicationContext.getBean(ReferenceHolder.class);
    18. //调用 SOFARest 服务
    19. final SampleRestFacade sampleRestFacade = referenceHolder.getSampleRestFacade();
    20. new Thread(new Runnable() {
    21. @Override
    22. public void run() {
    23. while (true) {
    24. try {
    25. String response = sampleRestFacade.hello();
    26. printMsg("Response from myserver-app.rest: " + response);
    27. } catch (Exception e) {
    28. e.printStackTrace();
    29. } finally {
    30. try {
    31. TimeUnit.SECONDS.sleep(3);
    32. } catch (InterruptedException e) {
    33. //ignore
    34. }
    35. }
    36. }
    37. }
    38. }).start();
    39. }
    40. private static void printMsg(String msg) {
    41. System.out.println(msg);
    42. if (logger.isInfoEnabled()) {
    43. logger.info(msg);
    44. }
    45. }
    46. }
  3. 本地运行时的端口处理:在 myclient-app web 模块 application.properties 文件中配置 rpc.tr.port=12202rpc.tr.port 是 TR 端口号,默认为 12200。云端发布时不需要该项配置。

  4. 在云端发布前,请务必进行 application.properties 配置。具体步骤请参考服务发布之 配置步骤

应用打包和云端发布

  • 请参考 编译运行 中的步骤,完成本地应用的打包。
  • 请参考下述信息,在 SOFAStack 控制台 完成应用的云端发布:
    • 应用整体的发布流程,请参考 技术栈使用指南技术栈与应用发布流程
    • 应用的详细发布步骤,建议参考 经典应用服务 下的 快速入门

云端管控

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