原文地址:Unicomplex & Cube Bootstrapping
Unicomplex和Cube的引导
squbs默认自带一个org.squbs.unicomplex.Bootstrap
的引导类。它可以通过IDE、命令行、sbt、Maven启动。引导类扫描类加载器,并在每个加载的jar包资源中查找META-INF/squbs-meta.<ext>。如果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()
让我们来看看每个部分:
-
创建UnicomplexBoot (boot) 对象。它可以通过传递一个自定义的配置文件或是actor系统创建者的闭包
UnicomplexBoot.apply()
来完成。 -
在例子中展示的
customConfig
即为配置对象 。这是一个从Typesafe配置类库解析函数中获取的配置对象。此配置对象尚未与application.conf
合并。 -
ActorSystem创建者通过传递一个函数或者闭包来创建ActorSystem。这个实际的创建在开始阶段(条目7)。默认的函数是
{(name, config) => ActorSystem(name, config)}
。其中输入的name是从配置项中读取的ActorSystem的名称。这个config将会在其他所有配置项合并之后再进行加载。大多是用例都希望以这种方式创建ActorSystem,因此并不需要提供该函数。createUsing
完全可以避免使用。 -
通过
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")
。 -
使用
initExtension
函数初始化扩展。它会初始化扫描到的扩展。在ActorSystem创建前,扩展将会完成初始化。在多重Unicomplex用例中(多个ActorSystem),同样的扩展至多初始化一次。一个扩展只能用在一个测试用例中。在一些测试用例中,我们根本不想初始化扩展,并且不会调用initExtension
。 -
在退出的时候停止JVM。调用
stopJVMOnExit
这个函数启动该功能。这个选项通常不会在测试用例里面使用。它被用在squbs引导中以保证subqs正常的关闭与退出。 -
调用
start()
方法启动Unicomplex。这个是强制性的步骤。如果没有这个ActorSystem将不会启动,并且Actor也不可运行。该启动调用在完全启动并运行或者超时前会处于阻塞。如果启动超时,某些组件可能依然在初始化,从而使系统处于Initializing
状态,但是,任何单个组件故障将在超时时将系统状态转变为Failed
。这将允许类似系统组件的系统诊断执行和结束。默认的启动超时时间为60秒。对于期望超时的测试,可以设置一个较低的超时时间作为参数传递给start()
函数,如start(Timeout(5 seconds))
,或者通过如start(5 seconds)
隐式转换的方式设置超时时间。
配置解决方案
squbs选择一个应用配置,并将classpath中聚合的application.conf 、reference.conf进行合并。这个应用配置以下面这个顺序进行合并:
-
如果在创建引导对象的时候已经提供了这个配置,则选择这个配置。这就是上面例子中的
customConfig
字段。 -
如果在外部的配置目录中提供了
application.conf
文件,这个application.conf
文件将被选择。外部的配置文件目录可以通过配置squbs.external-config-dir
参数设置,默认为squbsconfig
。不是那样的话,设置的目录将不会被提供的目录或外部配置文件改变和覆盖(因为目录本身是使用config属性确定的)。 -
其他情况下,将使用应用程序提供的
application.conf
。最后使用reference.conf
。
插件模块化系统
squbs将应用划分成称为cube的模块。squbs中的模块在平行的类路径中隔离运行。模块化意在达到模块之间的松耦合,而不会导致发生任何依赖关系引起的类路径冲突。
当前的实现是从一个平面(flat)类路径进行引导。在引导下,squb会自动检测classpath下扫描的模块。扫描到的cubes将会自动被检测和启动。
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
特性。
配置解决方案
当多个cube尝试提供它们内部的 application.conf
文件时,为cube提供 application.conf
配置文件可能出现问题。合并这些配置文件的优先级规则未被定义。推荐cube仅提供reference.conf
并且可以在部署时可以被外部的application.conf覆盖。
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。
服务(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
扩展
squbs中的扩展是为环境所启动的低等级设备。扩展初始化需要继承org.squbs.lifecycle.ExtensionLifecycle
特性同时复写回调参数。一个扩展有很大的能力来反思系统,并且提供额外的squbs未提供的功能。在同一个cube中,一个扩展不可以与一个actor或service组合。
扩展按照顺序一个一个加载的。扩展的生成者可以在扩展声明中通过指定:sequence = [number]来为扩展启动提供序列号。如果序列号没有被指定,它默认为Int.maxValue。这代表着它将会在所有标有序列号的扩展启动之后启动。如果存在多个扩展没有指定序列号或者制定了相同的序列号,那么他们之间启动顺序是不确定的。关闭写顺序和启动的顺序相反。
关闭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
网友评论