阿里云首页 金融分布式架构 SOFAStack

快速入门

本文将向您描述如何使用 SOFABoot 框架创建一个Web 工程,实现本地运行或部署到云端运行,以及如何引入中间件服务。

主要步骤如下:

说明

Core 工程Web 工程类似,具体步骤详见 创建工程

创建 Web 工程

前置条件

为执行本文代码示例,您需要首先搭建 SOFABoot 的运行环境。具体步骤详见 搭建环境

创建步骤

SOFABoot Web 工程的创建,主要分为 2 个步骤:

  1. 创建本地工程

  2. 配置关键属性

具体操作步骤如下:

创建本地工程

注意

本文档仅支持 SOFABoot ≥ 3.3.0 版本的创建,如需升级,请参考 SOFABoot 升级说明

  1. 打开命令行工具,输入并执行以下语句:

    mvn archetype:generate -DarchetypeGroupId=com.alipay.sofa -DarchetypeArtifactId=sofaboot-web-archetype -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeCatalog=internal
  2. 在执行过程中,根据系统提示输入以下 Maven 坐标信息:

    • groupId:是 Maven 仓库中的唯一标识,一般为公司域名或组织域名的反写。作为示例,可填为 com.alipay.sofa

    • artifactId:表示项目名称或应用名称。作为示例,可填为 web-app

    • version:版本号,默认为 1.0-SNAPSHOT。SNAPSHOT 意为快照,说明该项目还在开发中,是不稳定的版本。作为示例,此处可维持默认值。

    • package:应用包名,默认等同于 groupId。

      # 示例
      Define value forproperty'groupId': com.alipay.sofa
      Define value forproperty'artifactId': web-app
      Define value forproperty'version'1.0-SNAPSHOT::
      Define value forproperty'package' com.alipay.sofa::
  3. 确认输入的 Maven 坐标信息。

    • 如果信息无误,输入 Y 确认,则工程继续创建。

    • 如需修改信息,输入 N 重新定义工程属性。

      # 示例
      Confirm properties configuration:
      groupId: com.alipay.sofa
      artifactId: web-app
      version:1.0-SNAPSHOT
      package: com.alipay.sofa
      Y::
  4. 工程创建完成。命令行提示以下信息。您可以在当前路径下的 ./web 文件夹找到创建的工程文件。

    [INFO]Project created fromArchetypein dir:{current_dir}/web
    [INFO]------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO]------------------------------------------------------------------------
    [INFO]Total time:28.298 s
    [INFO]Finished at:2018-01-10T23:36:19+08:00
    [INFO]FinalMemory:15M/163M
    [INFO]------------------------------------------------------------------------

  5. 请移步 版本说明,查看最新的 SOFABoot 版本,然后在工程根目录下的主 pom.xml 中,修改 <parent>标签的版本号,示例如下:

    版本号

配置关键属性

在云端发布前,请务必进行 application.properties 配置。更多详情,请参考 引入 SOFA 中间件。配置步骤如下:

  1. 请前往 SOFAStack 控制台 > 研发效能 > 脚手架 > Step 2,示例如下:

    脚手架截图

    从中获取下述信息:

    • 实例标识:应用实例在工作空间中的唯一标识,在 application 中对应的 key 为:com.alipay.instanceid

    • AntVIP:应用通过 AntVIP 来获取各个组件的服务端地址,每个区域一个地址。在 application 中对应的 key 为 com.antcloud.antvip.endpoint。不同环境的 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

  2. 脚手架 控制台,单击右上角用户图像,选择 AccessKey Management,在跳转的页面中即可获取访问控制对应的属性值。 这些属性在 application 中对应的 key 分别为:

    • Access Key IDcom.antcloud.mw.access

    • Access Secretcom.antcloud.mw.secret

      说明

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

  3. 确定运行模式和运行环境,示例如下:

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

对于有关 SOFABoot 框架的整体配置、工程依赖的配置,以及中间件服务的配置,请参见:

将 Web 工程导入 IDE

SOFABoot 工程是标准的 Maven 工程。您可以使用经典的 Java 开发工具(如 IntelliJ IDEA 、Eclipse 等)对其进行开发。请遵照以下步骤将 SOFABoot 工程导入相应的 IDE 工具中:

IntelliJ IDEA

  1. 打开 IntelliJ IDEA 程序。

  2. 导入之前创建的工程目录。

    • 如果您是首次使用,或者之前关闭了所有工程,程序会跳出欢迎界面。在该界面中,单击 Open > 选择之前创建的工程目录 > OK

    • 如果 IntelliJ IDEA 自动为您载入了上次未关闭的工程,您可以单击 File > Open > 选择之前创建的工程目录 > OK

  3. 配置 Maven:

    1. 单击 File > Settings,打开设置窗口,并通过以下任一方式定位到 Maven 配置页面:

      • 依次单击 Build, Execution, Deployment > Build tools > Maven

      • 搜索关键字 Maven

    2. Maven home directory 项配置为本地 Maven 安装目录。

    3. User Settings file 项配置为本地 Maven 的 settings.xml 文件路径。

    4. 单击 OK 关闭设置窗口。

导入完成后,您可以在工程文件目录中查看工程结构与内容。

Eclipse

  1. 打开 Eclipse 程序。

  2. 配置 Maven:

    1. 单击 Window > Preferences,打开首选项窗口,并搜索关键字 Maven 定位到 Maven 配置页面。

    2. Maven 下,选择 Installations 并配置 Maven 目录。

      • 如果 Installations 列表中已有本地 Maven 安装目录选项,直接勾选该选项。

      • 如果列表中没有本地 Maven 安装目录选项,单击 Add。在新窗口中,将 Installation home 配置为本地 Maven 安装目录,单击 Finish 返回并勾选新添加的目录选项。

    3. 单击 Apply,保存配置。

    4. Maven 下,选择 User Settings 并将 User Settings 项配置为本地 Maven 的 settings.xml 文件路径。

    5. 单击 Apply and Close 保存配置并关闭首选项窗口。

  3. 单击 File > Import > Maven > Existing Maven Projects > Next > 选择之前创建的工程目录 > Finish

本地编译运行

主要操作步骤如下:

  1. 通过下述任一方式启动本地工程:

    • 命令行方式启动

      • 通过 cd 命令,进入工程根目录。

      • 执行 mvn clean install 命令。

    • 通过 IDE 方式启动:运行 Web 模块下的 main 函数。

  2. 成功运行后,在浏览器中访问 http://localhost:8080/index.html,您可以看到以下静态页面信息:

     the static page inSOFABoot based on spring-boot
    说明

    SOFABoot Core 工程是没有页面的工程,因此无法在本地进行效果预览。但可以通过http://localhost:8080/actuator/readiness 进行健康检查。如果 status 为 UP,表示创建成功。

    更多本地编译运行 SOFABoot 工程的方法,请参阅 本地编译运行

云端运行

  • 应用整体的发布流程,请参考 技术栈使用指南 中的 技术栈与应用发布流程

  • 应用的详细发布步骤,建议参考 经典应用服务 下的 快速入门

引入中间件服务

在成功创建 SOFABoot 工程后,通过在主 pom 文件中引入 starter,即可实现使用中间件服务。

  • 中间件服务类别,以及对应 starter 版本信息的说明,请参考 引入 SOFA 中间件

  • 对于各中间件服务的示例 demo,请参考对应产品的快速入门。