Request Logger

@vafast/request-logger 是 HTTP 访问日志中间件：记录方法、路径、耗时、脱敏后的 headers/body/response，异步上报远程服务，并可双写 stdout。

与 @vafast/logger 的区别

包	用途
@vafast/logger	应用内 logger.info / error（不是中间件）
@vafast/request-logger	每个 HTTP 请求的访问日志中间件

安装

npm install @vafast/request-logger

快速开始

url 与 service 必填：

import { Server, defineRoute, defineRoutes, serve } from 'vafast'
import { requestId } from '@vafast/request-id'
import { requestLogger } from '@vafast/request-logger'

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

const server = new Server(routes)
server.use(requestId())
server.use(
  requestLogger({
    url: 'http://log-server:9005/api/logs/ingest',
    service: 'my-server',
  }),
)

serve({ fetch: server.fetch, port: 3000 })

默认行为：stdout JSON 双写开启、敏感字段脱敏、上报失败熔断 + 错误节流。

用法

认证头与排除路径

server.use(
  requestLogger({
    url: process.env.LOG_INGEST_URL!,
    service: 'auth-server',
    headers: {
      Authorization: `Bearer ${process.env.LOG_INGEST_TOKEN}`,
    },
    excludePaths: ['/health', '/metrics', /^\/internal/],
  }),
)

excludePaths：字符串为精确匹配或「前缀 + /」；RegExp 则 test(path)。

路由级关闭

在路由定义上设 log: false（经框架 getRoute 读取）：

defineRoute({
  method: 'GET',
  path: '/health',
  log: false,
  handler: () => ({ ok: true }),
})

stdout 双写（K8s）

requestLogger({
  url: '...',
  service: 'auth-server',
  stdout: {
    enabled: true, // 默认 true；设 false 可关闭
    format: 'json', // 或 'text'
    includeBody: true,
    includeResponse: false, // 响应体可能很大
  },
})

stdout 级别：2xx → 30 (INFO)，4xx → 40 (WARN)，5xx → 50 (ERROR)。

自定义业务字段

requestLogger({
  url: '...',
  service: 'billing-server',
  getUserId: ({ req }) => req.__locals?.userInfo?.id,
  getAppId: async ({ path, body }) => {
    if (path !== '/notify/alipay') return undefined
    const form = body as Record<string, string>
    return lookupAppId(form.out_trade_no)
  },
  getAuthType: ({ headers }) =>
    headers.authorization?.startsWith('Bearer ak_') ? 'apiKey' : undefined,
})

未提供 getter 时的默认：

• appId ← header app-id
• authType ← Authorization 前缀启发式（Bearer ak_ → apiKey，Bearer eyJ → jwt）
• userId ← 未验签解析 JWT payload 的 sub / userId / id
• clientKey ← header client-key（Ones App Client）
• platform ← header x-platform
• appVersion ← header x-app-version

端字段在 headers 脱敏前解析并写入 ingest 顶层；缺失或空串为 null。log-server 不再从 headers 兜底。

采样与熔断

requestLogger({
  url: '...',
  service: 'gateway',
  sampleRate: 0.1, // 只记约 10%
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 60_000,
  },
  errorThrottle: { interval: 60_000 },
  onError: (error, { droppedCount }) => {
    console.warn(error.message, droppedCount)
  },
})

与 request-id

优先 req.id，否则读 requestIdHeader（默认 x-request-id）：

server.use(requestId())
server.use(requestLogger({ url: '...', service: 'my-server' }))

API完整参数

requestLogger(options)

requestLogger(options: RequestLoggerOptions): Middleware

createRequestLogger 为同名别名（已废弃）。

RequestLoggerOptions

参数	类型	必填	默认	说明
url	string	是	—	远程 ingest URL
service	string	是	—	服务标识
headers	Record<string, string>	否	{}	上报请求额外头
timeout	number	否	5000	上报超时（毫秒）
enabled	boolean	否	true	总开关
excludePaths	(string | RegExp)[]	否	[]	排除路径
sanitize	SanitizeConfig	否	内置默认	body/headers/response 脱敏
onError	(error, { droppedCount }) => void	否	结构化 warn JSON	上报失败回调
circuitBreaker	CircuitBreakerConfig	否	见下	熔断
errorThrottle	ErrorThrottleConfig	否	见下	错误节流
stdout	StdoutConfig	否	见下	stdout 双写
sampleRate	number	否	1	0–1，采样率
requestIdHeader	string	否	'x-request-id'	无 req.id 时读取的头
getAppId	ContextGetter	否	—	自定义 appId
getUserId	ContextGetter	否	—	自定义 userId
getAuthType	ContextGetter	否	—	自定义 authType

ContextGetter：

(context: RequestLoggerContext) => string | undefined | Promise<string | undefined>

RequestLoggerContext 含：req、response、method、url、path、headers、body、responseData。

CircuitBreakerConfig

参数	默认	说明
failureThreshold	5	连续失败次数后打开熔断
resetTimeout	60000	熔断后等待再试（毫秒）

ErrorThrottleConfig

参数	默认	说明
interval	60000	同类错误节流间隔（毫秒）

StdoutConfig

参数	默认	说明
enabled	true	enabled !== false 即输出
format	'json'	'json' | 'text'
includeBody	true	是否含请求体
includeResponse	false	是否含响应体

SanitizeConfig

参数	默认	说明
removeFields	password / secret 等	字段名精确匹配（小写）→ 占位符
maskFields	token / authorization 等	字段名包含匹配 → 部分脱敏
placeholder	'[REDACTED]'	占位
maxDepth	10	递归深度

另导出：sanitize、sanitizeHeaders、isSensitiveField（见包源码）。

上报载荷（示意）

{
  method, url, path, headers, body, query,
  status, duration, service,
  appId, authType, userId, clientKey, platform, appVersion,
  ip, traceId, userAgent,
  createdAt, response,
  clientIp?, requestId?
}

最佳实践

• 必填 url + service；本地可把 url 指到假服务，或 enabled: false
• 先 requestId() 再 requestLogger()，保证 traceId / requestId 一致
• 健康检查、metrics 用 excludePaths 或路由 log: false
• 高 QPS 用 sampleRate；响应体默认不要开 stdout.includeResponse
• 支付回调等无登录态场景用 getAppId 从 body 反查租户

注意事项

• 上报在 next() 之后异步执行，不阻塞响应；失败只触发熔断 / onError，不影响业务
• 会在业务前 req.clone() 读 body；跳过日志的路径（排除 / log: false / 采样）不会读 body
• 没有默认排除 /health——需自己配置 excludePaths
• JWT userId 默认解析不验签，仅用于日志归属
• sanitize 配置字段是 removeFields / maskFields，不是 fields / mask

相关链接

• Logger
• Request ID
• 最佳实践