跟踪

¥Trace

性能是 Elysia 的一个重要方面。

¥Performance is an important aspect for Elysia.

我们并非为了基准测试而追求速度，而是希望你在实际场景中拥有一台真正快速的服务器。

¥We don't want to be fast for benchmarking purposes, we want you to have a real fast server in real-world scenario.

有很多因素会降低我们应用的速度 - 并且很难识别它们，但 trace 可以通过在每个生命周期中注入启动和停止代码来解决这个问题。

¥There are many factors that can slow down our app - and it's hard to identify them, but trace can help solve that problem by injecting start and stop code to each life-cycle.

Trace 允许我们在每个生命周期事件的前后注入代码，阻止函数的执行并与之交互。

¥Trace allows us to inject code to before and after of each life-cycle event, block and interact with the execution of the function.

警告

trace 不适用于动态模式 aot: false，因为它要求函数是静态的并且在编译时已知，否则会对性能产生很大的影响。

¥trace doesn't work with dynamic mode aot: false, as it requires the function to be static and known at compile time otherwise it will have a large performance impact.

跟踪

¥Trace

Trace 使用回调监听器来确保回调函数在执行下一个生命周期事件之前完成。

¥Trace use a callback listener to ensure that callback function is finished before moving on to the next lifecycle event.

要使用 trace，你需要在 Elysia 实例上调用 trace 方法，并传递一个将在每个生命周期事件中执行的回调函数。

¥To use trace, you need to call trace method on the Elysia instance, and pass a callback function that will be executed for each life-cycle event.

你可以通过添加 on 前缀加上生命周期名称来监听每个生命周期，例如，使用 onHandle 来监听 handle 事件。

¥You may listen to each lifecycle by adding on prefix followed by the lifecycle name, for example onHandle to listen to the handle event.

import { Elysia } from 'elysia'

const app = new Elysia()
    .trace(async ({ onHandle }) => {
	    onHandle(({ begin, onStop }) => {
			onStop(({ end }) => {
        		console.log('handle took', end - begin, 'ms')
			})
	    })
    })
    .get('/', () => 'Hi')
    .listen(3000)

更多信息请参阅 生命周期事件：

¥Please refer to Life Cycle Events for more information:

子项

¥Children

除 handle 之外的每个事件都有子事件，子事件是一个事件数组，会在每次生命周期事件的内部执行。

¥Every event except handle has children, which is an array of events that are executed inside for each lifecycle event.

你可以使用 onEvent 按顺序监听每个子事件。

¥You can use onEvent to listen to each child event in order

import { Elysia } from 'elysia'

const sleep = (time = 1000) =>
    new Promise((resolve) => setTimeout(resolve, time))

const app = new Elysia()
    .trace(async ({ onBeforeHandle }) => {
        onBeforeHandle(({ total, onEvent }) => {
            console.log('total children:', total)

            onEvent(({ onStop }) => {
                onStop(({ elapsed }) => {
                    console.log('child took', elapsed, 'ms')
                })
            })
        })
    })
    .get('/', () => 'Hi', {
        beforeHandle: [
            function setup() {},
            async function delay() {
                await sleep()
            }
        ]
    })
    .listen(3000)

在此示例中，总子项数将为 2，因为 beforeHandle 事件中有 2 个子项。

¥In this example, total children will be 2 because there are 2 children in the beforeHandle event.

然后我们使用 onEvent 监听每个子事件并打印每个子事件的持续时间。

¥Then we listen to each child event by using onEvent and print the duration of each child event.

跟踪参数

¥Trace Parameter

调用每个生命周期时

¥When each lifecycle is called

import { Elysia } from 'elysia'

const app = new Elysia()
	// This is trace parameter
	// hover to view the type
	.trace((parameter) => {
	})
	.get('/', () => 'Hi')
	.listen(3000)

trace 接受以下参数：

¥trace accept the following parameters:

id - number

为每个请求随机生成唯一的 ID

¥Randomly generated unique id for each request

context - Context

Elysia 的 上下文，例如 set、store、query、params

¥Elysia's Context, eg. set, store, query, params

set - Context.set

context.set 的快捷方式，用于设置上下文的标头或状态

¥Shortcut for context.set, to set a headers or status of the context

store - Singleton.store

context.store 的快捷方式，用于访问上下文中的数据

¥Shortcut for context.store, to access a data in the context

time - number

请求调用的时间戳

¥Timestamp of when request is called

on[Event] - TraceListener

每个生命周期事件的事件监听器。

¥An event listener for each life-cycle event.

你可以监听以下生命周期：

¥You may listen to the following life-cycle:

• onRequest - 接收每个新请求的通知

• onParse - 用于解析主体的函数数组

• onTransform - 在验证之前转换请求和上下文

• onBeforeHandle - 自定义要求在主处理程序之前进行检查，如果返回响应，则可以跳过主处理程序。

• onHandle - 分配给路径的函数

• onAfterHandle - 在将响应发送回客户端之前与响应进行交互

• onMapResponse - 将返回值映射到 Web 标准响应中

• onError - 处理请求过程中抛出的错误

• onAfterResponse - 发送响应后的清理函数

跟踪监听器

¥Trace Listener

每个生命周期事件的监听器

¥A listener for each life-cycle event

import { Elysia } from 'elysia'

const app = new Elysia()
	.trace(({ onBeforeHandle }) => {
		// This is trace listener
		// hover to view the type
		onBeforeHandle((parameter) => {

		})
	})
	.get('/', () => 'Hi')
	.listen(3000)

每个生命周期监听器接受以下内容：

¥Each lifecycle listener accept the following

name - string

函数的名称，如果函数是匿名的，则名称为 anonymous。

¥The name of the function, if the function is anonymous, the name will be anonymous

begin - number

函数启动时间

¥The time when the function is started

end - Promise<number>

函数结束时间将在函数结束时解析。

¥The time when the function is ended, will be resolved when the function is ended

error - Promise<Error | null>

生命周期中抛出的错误将在函数结束时解决。

¥Error that was thrown in the lifecycle, will be resolved when the function is ended

onStop - callback?: (detail: TraceEndDetail) => any

生命周期结束时执行的回调

¥A callback that will be executed when the lifecycle is ended

import { Elysia } from 'elysia'

const app = new Elysia()
	.trace(({ onBeforeHandle, set }) => {
		onBeforeHandle(({ onStop }) => {
			onStop(({ elapsed }) => {
				set.headers['X-Elapsed'] = elapsed.toString()
			})
		})
	})
	.get('/', () => 'Hi')
	.listen(3000)

建议在此函数中修改上下文，因为有一个锁定机制可以确保在进入下一个生命周期事件之前上下文修改成功。

¥It's recommended to mutate context in this function as there's a lock mechanism to ensure the context is mutate successfully before moving on to the next lifecycle event

TraceEndDetail

传递给 onStop 回调的参数

¥A parameter that passed to onStop callback

end - number

函数结束时间

¥The time when the function is ended

error - Error | null

生命周期中抛出的错误

¥Error that was thrown in the lifecycle

elapsed - number

end - begin 的生命周期耗时

¥Elapsed time of the lifecycle or end - begin