日志

日志在应用线上问题排查中扮演着重要的角色。虽然我们可以使用 console 打印日志，但我们的日志需求可能更加多样化。例如，我们需要将日志不只是打印在控制台中，而是可以记录为文件，或者使用专门的日志平台。以及，我们需要对不同请求间打印的日志作区分来方便我们排错，尤其是在同时访问人数很多的情况下。

在任何可以使用 context 的地方，都可以直接使用 logger。logger 的用法几乎和 console 一样。

// 打印一条普通的日志
context.logger.log("Hello, Milkio!");
// 日志的第二个及之后的参数可以用来携带数据，这样日志会把这些数据也一起记录起来
context.logger.log("Hello, Milkio!", { foo: "bar " });
// 和 console 一样，也可以使用 debug, warn 或者 error 来记录不同级别的日志
context.logger.error("这里的运行出错了 UwU");

或者，也可以使用 useLogger 方法来创建一个日志记录器，此时需要提供一个 executeId 参数。该参数来自你的 API 的context对象，并且是唯一的。对于每个请求，executeId都是不同的。Milkio 的日志记录器通过它们来区分不同的请求。

const logger = useLogger(context.executeId);

在某些特殊情况下，你可能无法获取到executeId。这种情况下，你可以传入global，日志记录器将向所有并发请求同时写入该日志。

const logger = useLogger("global");

日志标签

除了打印日志之外，你还可以为一个请求打上日志标签。通过 loggerPushTags 方法，可以为某个请求添加若干自定义标签。

import { loggerPushTags } from "Milkio";

loggerPushTags(executeId, { userInfo: ..., permissions: ... });

在以往的日志中，我们常常直接将请求的用户信息、权限等数据输出到日志中，这样会掩盖了关键信息。合理地使用标签有助于使你的日志更加清晰易读，只保留关键信息。

内置日志标签

Milkio 会自动为你的每个请求添加一些日志标签。以下标签会被使用：

键	值
`from`	来源 “http-server” \| “execute”
`executeId`	执行此请求的唯一 id
`method`	请求方式
`ip`	请求发起者的 IP 地址
`url`	请求地址
`params`	请求的参数 (Object)
`body`	最终响应的数据 (Raw String)
`timein`	接收到请求的时间 (Number)
`timeout`	请求响应的时间 (Number)
`requestHeaders`	请求头 (Object)
`responseHeaders`	响应头 (Object)

注意，你不能假设这些日志标签始终存在。例如，在某些极端情况下，请求被直接终止时，可能不会添加body、params、responseHeaders等内容。此外，当通过编写 execute 代码而不是发送 HTTP 请求的方式进行调用时，像 ip 等数据将不存在，并且可能会获得其他一些值。

自定义日志记录器

你可以根据需要自由修改 /src/logger.ts 来自定义日志记录器的行为。默认情况下，根据代码编写，你的日志记录器会直接在控制台中显示日志。

import { type LoggerOptions, type ExecuteId } from "Milkio";

export const loggerOptions = {
  onSubmit: (tags, logs) => {
    console.log(`🥛 Milkio 响应！来自 :`, tags.url);
    console.log(JSON.stringify(tags));
  },
  onInsert: (options) => {
    console[options.loggerLevel](options.description, ...options.params);

    return true;
  },
} satisfies LoggerOptions;

onSubmit

onSubmit 方法会在一个请求即将结束时被调用，它可以是一个异步方法或返回一个Promise。你可以在此阶段将与该请求相关的日志持久化保存。

在这个方法中，你不仅可以获取该请求中记录的所有历史日志，还可以获取该请求上打过的所有标签。

onInsert

onInsert 方法是用于在每次记录日志时被调用的，它必须是一个同步方法。你需要返回 true 或 false。当你返回 false 时，该日志将被丢弃。举个例子，你可以通过返回 false 来实现在生产环境中不记录 debug 级别日志的功能。

请不要在此方法中进行日志的持久化保存（例如将日志写入文件或发送到各种日志系统中）。由于每次请求都可能需要写入大量日志，这将导致频繁的 IO 操作，从而降低性能。