squbs-1. 引导

作者: 吕亦行 | 来源:发表于2017-01-15 00:19 被阅读158次

    原文地址:Unicomplex & Cube Bootstrapping

    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)隐式转换的方式设置超时时间。

    配置解决方案

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

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

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

    3. 其他情况下,将使用应用程序提供的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
    

    相关文章

      网友评论

        本文标题:squbs-1. 引导

        本文链接:https://www.haomeiwen.com/subject/nffybttx.html