Lakutata 核心概念
本指南介绍所有 Lakutata 应用共同遵循的模型:应用由哪些对象构成、这些对象继承哪些类,以及这些设计背后的考虑。具体规则见对象与生命周期、依赖注入和模块;应用设计说明如何将这一模型应用到应用的结构上。
1. 应用是一棵对象树
Lakutata 应用由 IoC 容器创建的对象构成。应用在其选项中声明这些对象(每个名称由哪个类提供、带有哪些选项);容器在对象首次被请求时创建它,或者在应用将其列入 bootstrap 时于启动阶段创建它。对象之间从不使用 new 相互创建,而是由每个对象声明其所需的对象,再由容器负责提供。
每个对象都拥有自身的容器,在该容器中创建的对象归其所有。因此,应用是一棵树的根,而这棵树决定了每个对象的存续时间:
Application 根对象:声明下列对象,并管理进程
├── log 组件,由 lakutata 包预置:日志记录器
├── orders 组件:订单数据,由所有请求共享
├── payments 模块:一个功能单元,带有它所声明的对象
│ ├── gateway 模块的组件
│ └── refunds 模块的提供者
└── entrypoint 组件:通过各种传输方式对外提供控制器
└── 请求的作用域 每次请求时创建,请求结束时销毁
├── OrderController 控制器:每次请求一个实例
└── CurrentUser 提供者:每次请求一个实例请求结束时,其作用域被销毁,为该请求创建的控制器和提供者随之销毁。应用停止时,入口先停止接收请求,然后销毁对象树中的对象。容器在依赖就绪后才将其提供给对象,并在对象的所有者销毁时一并销毁该对象。因此,应用的代码只需声明对象,对象的生命周期由框架管理。
2. 基础类
对象树中的每个对象都继承自框架的某个基础类:
BaseObject 容器创建的所有对象;默认为 @Transient
└── Provider 存在于某个作用域中的功能单元;默认为 @Scoped
├── Controller 处理入口的请求;@Scoped(锁定)
└── Component 应用的长期服务;@Singleton(锁定)
└── Module 声明自身对象的组件
└── Application 根模块,由 Application.run() 创建BaseObject提供所有对象共有的能力:异步构造、生命周期钩子、经校验规则校验的选项,以及对容器的访问(getObject())。其直接子类是瞬态的,即每个请求该类的对象都会得到一个新实例。它适合自身带有状态的辅助对象,例如依赖注入中的Stopwatch。Provider是存在于某个作用域中的功能单元:每个作用域一个实例,由该作用域中的对象共享,并随作用域一起销毁。入口的每次请求都是一个作用域,因此提供者可以保存一次请求的状态(例如已登录的用户),而这些状态不会泄露到其他请求中。典型的提供者包括仓储、密码哈希器,以及按请求配置的客户端。Component是整个应用共享的长期服务,例如日志记录器、数据库连接、缓存和入口。它是单例,并且其生命周期类型已锁定,子类无法将其改为作用域或瞬态。组件持有只应存在一份的资源(连接、服务器、定时器、文件);组件同时是事件发射器:其他对象通过监听其事件来响应其变化,而无需由组件直接调用。Controller处理入口的请求。每次请求都会创建各自的控制器,并带有该请求的上下文和中止信号;请求结束时控制器随之销毁。因此,控制器不在请求之间保存状态,需要跨请求存在的状态应放在组件中。Module是声明自身组件、提供者和对象的组件,声明方式与应用相同。模块中的对象先在模块内、再到应用中解析依赖,而应用中的其他对象无法注入它们。模块将一个功能的各个对象组织起来,并通过一个对象对外提供。Application是根模块。它在模块之上增加了与进程相关的部分:启动、退出信号与退出码、运行模式、环境变量和路径别名。
有两个类不在对象树中。DTO 用校验规则描述数据(动作的输入、消息、对象的选项);框架用它校验数据,但不会将其作为对象创建。Container 即容器本身;测试、脚本和库可以自行创建容器,在没有应用的情况下使用框架的对象(对象与生命周期第 5 节)。
3. 声明而非构造
对象说明自身需要什么,应用说明如何提供:
- 属性上的
@Inject('mailer')声明该对象需要以mailer为名注册的对象; - 属性上的
@Configurable(schema)声明对象的一个选项,以及该选项的值必须满足的校验规则; - 应用选项声明每个名称由哪个类提供,以及带有哪些选项:
mailer: {class: Mailer, host: 'smtp.example.com'}。
由于对象声明依赖而非自行构造依赖,同一个类可以在多个应用中以不同的选项使用,框架自身的各个包正是如此(依赖注入第 3 节)。应用在启动时检查其声明的每个对象的选项,因此即使某个对象从未被使用,配置错误也会使启动失败。测试可以使用其所需的选项启动应用,或者替换提供某个名称的类,而无需修改注入该名称的对象。
4. 异步构造
对象的构造是异步的:对象可以在被使用之前连接服务器、打开文件或加载数据,而 getObject() 只在对象就绪后才完成。每个阶段都有对应的钩子:
| 钩子 | 执行时机 | 典型用途 |
|---|---|---|
init() | 依赖已注入、选项已设置之后 | 建立连接、加载数据、检查配置;在此抛出的错误会导致创建失败 |
startup() | init() 之后;请求该对象的其他对象会等待它结束 | 启动其他对象所依赖的部分,例如开始监听的服务器 |
launched() | 应用启动完成之后;不会被等待 | 需要整个应用就绪后才能进行的工作 |
beforeDestroy() | 对象销毁时最先执行 | 拒绝新的工作,不再使用其他对象 |
destroy() | 最后执行,此时对象所拥有的对象已经销毁 | 释放自身的资源:连接、定时器、文件 |
因此,对象在依赖就绪后才会得到它们。例外情况发生在 startup() 执行期间以及模块的 bootstrap 中,分别见对象与生命周期第 4 节和模块第 3 节。
5. 生命周期类型与作用域
类的生命周期类型决定容器为它创建多少个实例:
- 单例:每个注册该类的容器一个实例,用于应用的资源和状态;
- 作用域:每个作用域一个实例,用于一次请求的状态,由该请求的控制器和提供者共享;
- 瞬态:每当有对象请求它时创建一个新实例,用于状态只属于使用者自身的辅助对象。
入口为每次请求创建一个作用域,因此一次请求中的作用域对象不会与其他请求中的对象共享状态,请求结束时作用域会释放这些对象。每个基础类的默认生命周期类型与其职责一致:组件是单例,提供者和控制器是作用域,其他对象是瞬态。具体规则(包括单例注入作用域对象时得到的是哪个实例)见对象与生命周期。
6. 选项即契约
对象的选项是标记了 @Configurable 的属性,每个属性都带有校验规则。这些校验规则构成了对象与声明它的应用之间的契约:应用在其选项中给出取值,框架在 init() 执行之前对这些值进行校验和转换。应用选项通常又由一个读取环境变量的函数(模板中的 config())生成,测试则以其所需的取值调用同一个函数(应用设计第 5 节)。
7. 同一个动作,所有传输方式
控制器中带有动作装饰器的方法称为动作。装饰器给出动作在每种传输方式下的地址:HTTP 路由(@GET('/orders/:id'))、命令(@CLIAction('order'))、服务调用的模式(@ServiceAction({cmd: 'order.get'}))、定时任务(@Schedule)或消息队列(@QueueAction)。expressHTTPEntrypoint()、commanderCLIEntrypoint() 等适配器将各传输方式的请求转换为对动作的调用,并将动作的结果和异常转换为响应。
因此,无论通过哪种传输方式调用,动作收到的都是已经由其 DTO 校验过的输入,并返回一个结果;动作本身不依赖调用它的传输方式。输入校验、访问控制,以及入口和控制器上声明的中间件,在所有传输方式下以相同的方式生效。异常会根据传输方式转换为 HTTP 状态码、服务调用的错误响应或命令的退出码。同一个方法可以同时为多种传输方式提供服务(控制器与动作)。
8. 术语
| 术语 | 含义 |
|---|---|
| 应用(Application) | 程序的根对象,由 Application.run() 创建 |
| 对象 | 继承自 BaseObject 的类的实例,由容器创建 |
| 声明 | 应用或模块选项中的一个对象条目:{class, ...options} |
| 组件(Component) | 应用中的单例对象:一项服务或一种资源 |
| 提供者(Provider) | 存在于作用域中的对象,每个作用域一个实例 |
| 模块(Module) | 声明自身对象的组件 |
| 控制器(Controller) | 其方法为入口的请求提供服务的类 |
| 动作 | 由动作装饰器绑定到某个地址的控制器方法 |
| 入口(Entrypoint) | 通过各个适配器对外提供控制器的组件,由 buildEntrypoints() 声明 |
| 适配器 | 入口中负责一种传输方式的部分,例如 expressHTTPEntrypoint() |
| 传输方式 | 访问动作的途径:HTTP、命令行、服务调用、定时任务、消息队列 |
| 驱动 | 组件的后端,例如 Database 组件所用的数据库,或 Queue 组件所用的消息代理 |
| 作用域 | 为每个作用域类保存一个实例的子容器;入口为每次请求创建一个作用域 |
| 生命周期类型 | 决定容器为一个类创建多少个实例的规则:单例、作用域、瞬态 |
| DTO | 用校验规则描述数据的类,用于校验选项、输入和结果 |
| bootstrap | 应用启动时依次执行的步骤:要创建的对象,以及要调用的函数 |