原文地址:Unicomplex & Cube
Bootstrapping

squbs支持Scala的ScalaTest 3.X,TestNG和Java测试框架的JUnit。

原文地址:Unicomplex Actor Hierarchy

Unicomplex和Cube的引导

squbs默认自带一个org.squbs.unicomplex.Bootstrap的引导类。它可以通过IDE、命令行、sbt、Maven启动。引导类扫描类加载器,并在每个加载的jar包资源中查找META-INF/squbs-meta.<ext&gt。如果squbs的元数据是有效的,jar包将被当做squbs的cube或扩展,并通过元数据的声明进行初始化。引导(Bootstrap)会首先初始化扩展程序、cubes,然后服务处理器,而不是他们在classpath中的先后顺序。

在正常情况下,引导细节没有太大的意义。然而,有种情况可能需要通过不同方式的编程来引导squbs。这在在进行测试用例(需要自定义配置和并发运行)时特别常见。更多信息可以参见Testing
squbs
Applications。引导squbs的语法如下:
Option 1) 用户自定义启动配置

UnicomplexBoot(customConfig)  
    .createUsing {(name, config) => ActorSystem(name, config)}  
    .scanResources() 
    .initExtensions  
    .stopJVMOnExit  
    .start()

Option 2) 使用默认配置启动

UnicomplexBoot {(name, config) => ActorSystem(name, config)}
  .scanResources()
  .initExtensions
  .stopJVMOnExit
  .start() 

让我们来看看每个部分:

  1. 创建UnicomplexBoot (boot)
    对象。它可以通过传递一个自定义的配置文件或是actor系统创建者的闭包
    UnicomplexBoot.apply()来完成。

  2. 在例子中展示的customConfig即为配置对象
    。这是一个从Typesafe配置类库解析函数中获取的配置对象。此配置对象尚未与application.conf
    合并。

  3. ActorSystem创建者通过传递一个函数或者闭包来创建ActorSystem。这个实际的创建在开始阶段(条目7)。默认的函数是{(name, config) => ActorSystem(name, config)}。其中输入的name是从配置项中读取的ActorSystem的名称。这个config将会在其他所有配置项合并之后再进行加载。大多是用例都希望以这种方式创建ActorSystem,因此并不需要提供该函数。
    createUsing 完全可以避免使用。

  4. 通过scanResources()函数扫描cubes,服务,扩展等组件。这个是强制默认的,否则将没有组件被启动。如果没有参数传入,suqbs引导将会扫描它的类加载器。测试用例可能希望仅扫描其中某些组件。通过传递附加的配置文件squbs-meta.conf将可以实现(作为参数的方式传入scanResources),例如:scanResources("component1/META-INF/squbs-meta.conf", "component2/META-INF/squbs-meta.conf")。它将扫描你的类路径和附加的资源文件路径。如果你不想让类路径被扫描,在资源列表前传入withClassPath = false
    或仅仅false即可:.scanResources(withClassPath = false, "component1/META-INF/squbs-meta.conf", "component2/META-INF/squbs-meta.conf")

  5. 使用
    initExtension函数初始化扩展。它会初始化扫描到的扩展。在ActorSystem创建前,扩展将会完成初始化。在多重Unicomplex用例中(多个ActorSystem),同样的扩展至多初始化一次。一个扩展只能用在一个测试用例中。在一些测试用例中,我们根本不想初始化扩展,并且不会调用initExtension

  6. 在退出的时候停止JVM。调用 stopJVMOnExit
    这个函数启动该功能。这个选项通常不会在测试用例里面使用。它被用在squbs引导中以保证subqs正常的关闭与退出。

  7. 调用start()方法启动Unicomplex。这个是强制性的步骤。如果没有这个ActorSystem将不会启动,并且Actor也不可运行。该启动调用在完全启动并运行或者超时前会处于阻塞。如果启动超时,某些组件可能依然在初始化,从而使系统处于Initializing
    状态,但是,任何单个组件故障将在超时时将系统状态转变为 Failed
    。这将允许类似系统组件的系统诊断执行和结束。默认的启动超时时间为60秒。对于期望超时的测试,可以设置一个较低的超时时间作为参数传递给
    start() 函数,如start(Timeout(5 seconds))
    ,或者通过如start(5 seconds)隐式转换的方式设置超时时间。

依赖

要使用文档中提到的测试工具,只需简单的添加如下依赖在你的build.sbt文件或者Scala构建脚本:

"org.squbs" %% "squbs-testkit" % squbsVersion

此外,你还应当根据测试是否需要添加如下依赖:

// Testing RouteDefinition...
"com.typesafe.akka" %% "akka-http-testkit" % akkaHttpVersion % "test",

// Using JUnit...
"junit" % "junit" % junitV % "test",
"com.novocode" % "junit-interface" % junitInterfaceV % "test->default",

// Using TestNG
"org.testng" % "testng" % testngV % "test",

ca88会员入口 1

配置解决方案

squbs选择一个应用配置,并将classpath中聚合的application.conf
、reference.conf进行合并。这个应用配置以下面这个顺序进行合并:

  1. 如果在创建引导对象的时候已经提供了这个配置,则选择这个配置。这就是上面例子中的customConfig字段。

  2. 如果在外部的配置目录中提供了application.conf文件,这个application.conf文件将被选择。外部的配置文件目录可以通过配置squbs.external-config-dir参数设置,默认为squbsconfig。不是那样的话,设置的目录将不会被提供的目录或外部配置文件改变和覆盖(因为目录本身是使用config属性确定的)。

  3. 其他情况下,将使用应用程序提供的application.conf。最后使用reference.conf

CustomTestKit

CustomTestKit用于启动一个完整的squbs实例以便测试零碎的应用。CustomTestKit使用简单,默认情况下不需要配置,但允许自定义和灵活的测试。通过CustomTestKit,可以使用不同配置启动任意数量的ActorSystem和Unicomplex实例(一个ActorSystem一个)——都在相同的JVM。一些特性如下:

  • 它自动将actor系统名称设置为 “规范/测试类名称”, 以确保 ActorSystem
    实例不发生冲突。但是, 它还允许在构- 造函数中传递actor系统名称。
  • 继承CustomTestKit的测试可以在同一 JVM 中并行运行。
  • 自动启动和关闭squbs。
  • 默认启动在src/main/resources/META-INF/squbs-meta.confsrc/test/resources/META-INF/squbs-meta.conf中的well-known
    actor和服务。但是, 允许传递资源给构造函数。
  • 允许传递自定义配置给构造器。

以下是 CustomTestKit 在 Scala测试中的应用实例:

import org.squbs.testkit.CustomTestKit

class SampleSpec extends CustomTestKit with FlatSpecLike with Matchers {
   it should "start the system" in {
      system.startTime should be > 0L
   }
}

TestNG和JUnit用于Java用户:

import org.squbs.testkit.japi.CustomTestKit

public class SampleTest extends CustomTestKit {

    @Test
    public void testSystemStartTime() {
        Assert.assertTrue(system().startTime() > 0L);
    }
}

如上图所示,squbs设置actor和组件的层次结构,用来支持在squbs系统中actors和服务的模块化运行。

插件模块化系统

squbs将应用划分成称为cube的模块。squbs中的模块在平行的类路径中隔离运行。模块化意在达到模块之间的松耦合,而不会导致发生任何依赖关系引起的类路径冲突。

当前的实现是从一个平面(flat)类路径进行引导。在引导下,squb会自动检测classpath下扫描的模块。扫描到的cubes将会自动被检测和启动。

传递配置给CustomTestKit

如果你想要自定义actor系统配置,你可以传递一个Config对象给CustomTestKit:

object SampleSpec {
  val config = ConfigFactory.parseString {
      """
        |akka {
        |  loglevel = "DEBUG"
        |}
      """.stripMargin
  }
}

class SampleSpec extends CustomTestKit(SampleSpec.config) with FlatSpecLike with Matchers {

  it should "set akka log level to the value defined in config" in {
    system.settings.config.getString("akka.loglevel") shouldEqual "DEBUG"
  }
}
  • ActorSystem
    这是一个Actor系统。一个squbs系统使用一个actor系统来支持所有的服务和立方体。这将保证我们有一个单点控制squbs系统中的调度员(dispatchers).这个Actor系统的名称默认为squbs,不过我们可以通过复写application.conf文件中的设置覆盖该配置。
  • Unicomplex
    这个核心单例角色控制squbs系统。它注册了所有的立方体,与web服务actor和cube管理通讯,以进行系统生命周期的管理。他同时还负责web服务和服务注册者actor的启动。应用或系统组件可以通过
    Unicomplex 中的ActorRef 调用 Unicomplex()
  • Listeners – 监听器是与Spray中的IO绑定的。在reference.conf
    或者
    application.conf中包含着配置的监听器的名称。默认情况下,默认监听器绑定的是0.0.0.0地址上的8080端口,也没有使用https。然而,这个可以通过application.conf文件进行覆盖。额外的监听可以在分别在类库或者应用中通过
    application.conf或者reference.conf配置。
  • RouteDefinition/FlowDefinitionRouteDefinition
    FlowDefinition都是不同形式的服务定义, RouteDefinition
    定义了服务的路由FlowDefinition定义了服务的
    。针对HTTP请求,两者有着不同的处理方式。 RouteDefinition
    FlowDefinition自身都不是actors,真正的actors是一些继承它们各自特征的类。它们由其各自的服务注册,并由其相应的actos托管。
  • Route/Flow actors
    CubeSupervisor创建的类型为org.squbs.unicomplex.streaming.RouteActor
    org.squbs.unicomplex.streaming.FlowActor
    来托管每个相应的RouteDefinition or
    FlowDefinition.因此,他们成为由他们各自所属的CubeSupervisor
    监管的children。他们请求的处理程序会自动注册到所有他们所绑定的监听,从而允许监听器的请求分配到各自的请求处理程序上。
  • Request handler actors
    开发者可以选择使用低级API工作,而不是使用
    RouteDefinition/FlowDefinition
    来注册请求处理程序。避免高级路由API通常可以消耗更少的资源并且允许流请求,但是在编码上的难度会大于路由DSL。
  • CubeSupervisorsCubeSupervisors
    直接从actor系统中创建并注册到Unicomplex。每一个cube注册一个CubeSupervisor实例。它们主要扮演服务程序和已注册actor的监管者,并且可以通过名称查找、错误处理、重启这些actors。它们对它们的children的生命周期负责。需要初始化的well-known
    actors要在squbs-meta.conf文件中做相应的声明。它们将会和他们的parent进行通讯以便获取其初始化状态。CubeSupervisor会再次向Unicomplex传达生命周期状态和初始化更新,以保障整个系统的生命周期状态。有关于cube和squbs-meta.conf
    文件服务配置具体条目的信息可以参考Bootstraping
    ,有关于cube的生命周期和生命周期的更新可以参照Runtime Lifecycle &
    API 。另外,cube结构还为well-know
    actors提供了命名空间的功能,用来防止由于不同cube造成的actors的冲突,RouteActorFlowActor在技术上等同于well-know
    actor。
  • Well-known actors
    这些actor是由CubeSupervisor启动的已注册的actor。他们注册和提供基本的启动信息,如routers通过squbs-meta.conf配置文件。更多关于cube的详细配置信息可以参照Bootstrapping
    。关于 reference.conf
    application.conf的规范和细节可以参照Typesafe Config

Cube Jars

所有的cube通过一个顶级jar文件和cube本身呈现。所有的cube必须在文件META-INF/squbs-meta.<ext>.中有元数据。支持.conf、.json和.properties的扩展名。关于格式可以参考Typesafe
config

cube的元数据至多配置唯一的cube和版本定义,并且申明和配置多个以下元素:

Actor: 定义squbs自动启动的well known actor。

Service: 定义一个squbs服务

Extension:
定义一个squbs框架扩展。这个扩展入口必须继承org.squbs.lifecycle.ExtensionLifecycle特性。

用CustomTestKit启动well-known actor和服务

CustomTestKit
自动启动src/test/resources/META-INF/squbs-meta.conf中配置的well-known
actor和服务。然而,你想要提供不同的资源路径,你可以传递一个资源的Seq()给构造器。withClassPath控制是否扫描META-INF/squbs-meta.conf整个测试路径。

object SampleSpec {
    val resources = Seq(getClass.getClassLoader.getResource("").getPath + "/SampleSpec/META-INF/squbs-meta.conf")
}

class SampleSpec extends CustomTestKit(SampleSpec.resources, withClassPath = false)
  with FlatSpecLike with Matchers {

  // Write tests here   
}

请注意,CustomTestKit允许一起传递configresources

配置解决方案

当多个cube尝试提供它们内部的 application.conf文件时,为cube提供
application.conf配置文件可能出现问题。合并这些配置文件的优先级规则未被定义。推荐cube仅提供reference.conf
并且可以在部署时可以被外部的application.conf覆盖。

测试中的端口绑定

启动服务需要端口绑定。为了防止端口冲突,应当让系统挑选端口,通过设置监听器的bind-port到0,例如default-listener.bind-port
= 0
CustomTestKit如果使用默认配置,对所有监听器设置bind-port =
0
)。squbs-testkit来于名为PortGetter的特质,允许提取系统选取端口。CustomTestKit已经混入了PortGetter,所以可以使用port值。

class SampleSpec extends CustomTestKit(SampleSpec.resources)

  "PortGetter" should "retrieve the port" in {
    port should be > 0
  }
}

默认,PortGetter返回default-listener的端口,最常见的一个。如果你需要提取其它监听器绑定的端口,可以覆盖listener方法或者传递监听器名称给port方法:

class SampleSpec extends CustomTestKit(SampleSpec.resources)

  override def listener = "my-listener"

  "PortGetter" should "return the specified listener's port" in {
    port should not equal port("default-listener")
    port shouldEqual port("my-listener")
  }
}

Well Known Actors

Well known actors 是仅仅指的是在Akka
documentation中定义的
Akka
actors。它们通过每个cube中的主管actor启动。主管的名称从cube中而来。因此任何well
known
actor有一个/<CubeName>/<ActorName>的路径,并且可以通过调用ActorSelection查找/user/<CubeName>/<ActorName>。

一个well known
actor可以启动为一个单例actor或一个router。为了申明一个well known
actor为一个router,加上:
with-router = true
在actor声明中。well knwon
actor如路由(Router)、调度员(dispatcher)、邮箱配置(mailbox
configuration)根据Akka文档通过reference.conf或application.conf 配置。

以下是一个cube的例子,配置在 META-INF/squbs-meta.conf下的一个well known
actor:

cube-name = org.squbs.bottlecubecube-version = "0.0.2"
squbs-actors = [
  {
    class-name = org.squbs.bottlecube.LyricsDispatcher
    name = lyrics
    with-router = false  # Optional, defaults to false
    init-required = false # Optional
  }
]

参数init-required用于actors是否需要返回它们完全启动后的状态给系统,以便将其视为初始化完成。有关启动/初始化钩子完整的讨论,可以参照Startup
Hooks
中的Runtime Lifecycles & API

如果一个actor被配置了with-router (with-router =
true)和一个非默认的调度员(dispatcher),那么通常是在非默认调度员(non-default
dispatcher)上调度actor(routee)。路由(router)将承担well known
actor的名称,而不是routee(你实现的actor)。一个路由(router)上设置的调度员(dispatcher)将仅影响当前路由(router),而不是routee。为了影响routee,你需要为了routee创建单独的配置,并将”/*”附加到名称上。接下来,您将要在下面的例子中,在routee部分设置调度员(dispatcher)

akka.actor.deployment {
  # Router configuration
  /bottlecube/lyrics {
    router = round-robin-pool
    resizer {
      lower-bound = 1
      upper-bound = 10
    }
  }
  # Routee configuration. Since it has a '*', the name has to be quoted.
  "/bottlecube/lyrics/*" {
    # Configure the dispatcher on the routee.
    dispatcher = blocking-dispatcher
  }

路由的概念、例子、配置都被记录在Akka
documentation。

手工UnicomplexBoot初始化

CustomTestKit也允许传入一个UnicomplexBoot实例。这允许引导的完整自定义。请看squbs引导章节查看详细信息。

object SampleSpec {
  val config = ConfigFactory.parseString(
    s"""
       |squbs {
       |  actorsystem-name = SampleSpec # should be unique to prevent collision with other tests running in parallel
       |  ${JMX.prefixConfig} = true # to prevent JMX name collision, if you are doing any JMX testing
       |}
    """.stripMargin
  )

  val resource = getClass.getClassLoader.getResource("").getPath + "/SampleSpec/META-INF/squbs-meta.conf"   

  val boot = UnicomplexBoot(config)
    .createUsing {(name, config) => ActorSystem(name, config)}
    .scanResources(resource)
    .initExtensions.start()
}

class SampleSpec extends CustomTestKit(SampleSpec.boot) with FunSpecLike with Matchers {

  // Write your tests here.
}

服务(Services)

有关于服务所有的细节在 Implementing HTTP(S)
Services会有描述。在
META-INF/squbs-meta.conf 中声明的服务元数据,如下所示:

cube-name = org.squbs.bottlesvc
cube-version = "0.0.2"
squbs-services = [
  {
    class-name = org.squbs.bottlesvc.BottleSvc
    web-context = bottles # 例如,你还可以指定bottles/v1

    # 监听的条目是可选的,默认为'default-listener'
    listeners = [ default-listener, my-listener ]

    # 可选,默认为一个默认的pipeline
    pipeline = some-pipeline

    # 可选,如果设置为false则禁用默认pipeline
    defaultPipelineOn = true

    # 可选,仅适用于actor
    init-required = false
  }
]

完整的描述可以参见Service
Registration

关闭

对于具有多个并行运行的 CustomTestKit 实例的大型测试,
在测试后正确关机很重要。关机机制取决于测试框架以及如何构造
CustomTestKit, 如下所示:

对于ScalaTest
CustomTestKit自动关闭,除非你覆盖了afterAll()
方法。不需要采取进一步的行动。

扩展

squbs中的扩展是为环境所启动的低等级设备。扩展初始化需要继承org.squbs.lifecycle.ExtensionLifecycle特性同时复写回调参数。一个扩展有很大的能力来反思系统,并且提供额外的squbs未提供的功能。在同一个cube中,一个扩展不可以与一个actor或service组合。

使用Akka Http TestKit测试Akka Http路由

为了测试路由,akka-http-testkit需要添加到依赖中。请增加如下依赖:

"com.typesafe.akka" %% "akka-http-testkit" % akkaHttpV % "test"

squbs
testkit提供工具从RouteDefinition特质构造路由并且有工具有独立的和整个系统模式,在这里基础结构和cube可以提出一部分来测试。

TestRoute用于从RouteDefinition构造和获得路由。为了使用它,仅需将RouteDefinition作为一个类型参数传递给TestRoute。这将为测试
DSL 获得一个完全配置和功能的路由, 如下面的示例所示。

指定RouteDefinition

import org.squbs.unicomplex.RouteDefinition

class MyRoute extends RouteDefinition {

  val route =
    path("ping") {
      get {
        complete {
          "pong"
        }
      }
    }
}

实现测试,从TestRoute[MyRoute]获取路由:

import akka.http.scaladsl.testkit.ScalatestRouteTest
import org.scalatest.{Matchers, FlatSpecLike}
import org.squbs.testkit.TestRoute

class MyRouteTest extends FlatSpecLike with Matchers with ScalatestRouteTest {

  val route = TestRoute[MyRoute]

  it should "return pong on a ping" in {
    Get("/ping") ~> route ~> check {
      responseAs[String] should be ("pong")
    }
  }
}

或者, 你也可能希望将 web 上下文传递到你的路由。这可以通过将其传递给
TestRoute, 如下所示:

val route = TestRoute[MyRoute](webContext = "mycontext")

或者仅传递”mycontext”不带参数名称。没有参数的 TestRoute
签名等同于传递根上下文 “”。

扩展按照顺序一个一个加载的。扩展的生成者可以在扩展声明中通过指定:sequence

[number]来为扩展启动提供序列号。如果序列号没有被指定,它默认为Int.maxValue。这代表着它将会在所有标有序列号的扩展启动之后启动。如果存在多个扩展没有指定序列号或者制定了相同的序列号,那么他们之间启动顺序是不确定的。关闭写顺序和启动的顺序相反。

使用 TestRoute 与 CustomTestKit

在使用 TestRoute 测试时, 可能会出现对引导 Unicomplex 的需求,
如以下情况:

  • 一个 squbs 的well-known actor参与了请求处理。
  • 在请求处理时使用了Actor注册。

将Akka的 TestKit 与 ScalatestRouteTest 一起使用可能会很棘手,
因为它们初始化冲突。squbs提供了名为CustomRouteTestKit
的测试工具解决这个问题。CustomRouteTestKit支持由CustomTestKit提供的所有API。下面是通过CustomRouteTestKit使用TestRoute的例子:

class MyRouteTest extends CustomRouteTestKit with FlatSpecLike with Matchers {

  it should "return response from well-known actor" in {
    val route = TestRoute[ReverserRoute]
    Get("/msg/hello") ~> route ~> check {
      responseAs[String] should be ("hello".reverse)
    }
  }
}

class ReverserRoute extends RouteDefinition {
  import akka.pattern.ask
  import Timeouts._
  import context.dispatcher

  val route =
    path("msg" / Segment) { msg =>
      get {
        onComplete((context.actorSelection("/user/mycube/reverser") ? msg).mapTo[String]) {
          case Success(value) => complete(value)
          case Failure(ex)    => complete(s"An error occurred: ${ex.getMessage}")
        }
      }
    }
}

关闭squbs

运行中的squbs可以通过向Unicomplex()发送一个 GracefulStop
消息关闭。
默认的启动main方法,org.squbs.unicomplex.Bootstrap,注册一个JVM关闭挂钩(hook),可以发送GracefulStop
消息至
Unicomplex。另外,如果一个squbs应用通过默认的main方法启动,当JVM接收到SIGTERM消息时,系统将会优雅的关闭。

如果有其他监控进程负责关闭app,例如JSW,可以设置org.squbs.unicomplex.Shutdown的main方法优雅的关闭关闭系统。同样的,Shutdown中的main方法发送一条
GracefulStop 消息至Unicomplex

在某些情况下,期望对关闭添加延迟。例如,如果一个负载均衡的健康每5s检测一次,但app在健康监测的1s后关闭,这个应用将保持在未来的4s中继续处理请求,直到下一次健康检测;但是,它无法提供这些请求。如果你使用上面的其中一个方法,org.squbs.unicomplex.Bootstrap
或者org.squbs.unicomplex.Shutdown,你可以通过如下的配置添加一个延迟:

squbs.shutdown-delay = 5 seconds

通过以上的配置, GracefulStop将会延迟5s后向 Unicomplex 发送。

在接收到GracefulStop消息后,Unicomplex actor将会停止服务,并传播
GracefulStop消息至所有的cube管理者中。每个管理者负责停止其cube中的actor(通过传播GracefulStop消息至希望执行优雅停止的children),确保他们成功关闭或超时后回传PoisonPill
,随后其关闭自身。一旦所有的cube管理者和服务停止,squbs系统关闭。然后,一个关闭钩子将被调用来关闭所有的扩展并且最后退出JVM.

目前web容器没有一个标准的控制台来允许squbs的用户构建他们自己的控制台。web控制台可以提供正确的用户关闭,通过发送一个停止消息至Unicomplex

  Unicomplex() ! GracefulStop

关闭

CustomRouteTestKit特质是特定于测试框架的,因此它们已经用测试框架钩子预先测试了,以便正确地开始和关闭。因此,没有必要使用任何风格的CustomRouteTestKit测试关闭Unicomplex。

相关文章