Vafast 中文文档

Theme

Server Timing ​

@vafast/server-timing 测量请求处理耗时，写入响应头 Server-Timing，便于在浏览器 DevTools 中查看。

框架没有细粒度生命周期钩子，因此只提供 handle / total 两段计时。

安装 ​

bash
npm install @vafast/server-timing

快速开始 ​

typescript
import { Server, defineRoute, defineRoutes, json, serve } from 'vafast'
import { serverTiming } from '@vafast/server-timing'

const routes = defineRoutes([
  defineRoute({
    method: 'GET',
    path: '/',
    handler: () => json({ ok: true }),
  }),
])

const server = new Server(routes)
server.use(serverTiming())
serve({ fetch: server.fetch, port: 3000 })

响应示例：

http
Server-Timing: handle;dur=1.23,total;dur=1.25

用法 ​

全局启用 ​

typescript
server.use(serverTiming())

强制在生产开启 ​

默认生产关闭（enabled 默认 NODE_ENV !== 'production'）：

typescript
server.use(
  serverTiming({
    enabled: true,
  }),
)

仅对部分路径写头 ​

typescript
server.use(
  serverTiming({
    enabled: true,
    allow: ({ request }) =>
      new URL(request.url).pathname.startsWith('/api'),
    trace: { handle: true, total: true },
  }),
)

只输出 total ​

typescript
server.use(
  serverTiming({
    trace: { handle: false, total: true },
  }),
)

API ​

导出 ​

导出说明
serverTiming(options?)主入口，返回中间件
default同 serverTiming
ServerTimingOptions配置类型

serverTiming(options?: ServerTimingOptions) ​

参数类型默认说明
enabledbooleanNODE_ENV !== 'production'是否启用；生产默认关闭
allowboolean | ((ctx) => boolean | Promise<boolean>)允许写入是否写入该次响应的头；函数入参为 { request }
trace.handlebooleantrue是否输出 handle 段
trace.totalbooleantrue是否输出 total 段

当前实现仅支持 handle / total，没有其它生命周期指标。

最佳实践 ​

  • 开发环境用默认配置即可；生产默认关闭，避免无意义开销与信息暴露。
  • 需要抽样观察时用 allow 限制路径或请求比例。
  • 真正的生产链路追踪请用 OpenTelemetry。

注意事项 ​

  • 这是开发期性能观察工具，不是 APM。
  • 若响应 Headers 不可变，headers.set 可能静默失败（源码已 try/catch）。
  • enabled: false 时直接 next()，不写任何头。

相关链接 ​