Fastify

回复

简介

处理函数的第二个参数为 Reply。 Reply 是 Fastify 的一个核心对象。它暴露了以下函数及属性:

  • .code(statusCode) - 设置状态码。
  • .status(statusCode) - .code(statusCode) 的别名。
  • .statusCode - 获取或设置 HTTP 状态码。
  • .header(name, value) - 设置响应 header。
  • .getHeader(name) - 获取某个 header 的值。
  • .removeHeader(key) - 清除已设置的 header 的值。
  • .hasHeader(name) - 检查某个 header 是否设置。
  • .type(value) - 设置 Content-Type header。
  • .redirect([code,] url) - 重定向至指定的 url,状态码可选 (默认为 302)。
  • .callNotFound() - 调用自定义的 not found 处理函数。
  • .serialize(payload) - 使用默认的或自定义的 json 序列化工具序列化指定的 payload,并返回处理后的结果。
  • .serializer(function) - 设置自定义的 payload 序列化工具。
  • .send(payload) - 向用户发送 payload。类型可以是纯文本、buffer、JSON、stream,或一个 Error 对象。
  • .sent - 一个 boolean,检查 send 是否已被调用。
  • .res - Node 原生的 http.ServerResponse 对象。
  • .log - 请求的日志实例。
  • .request - 请求。
  1. fastify.get('/', options, function (request, reply) {
  2. // 你的代码
  3. reply
  4. .code(200)
  5. .header('Content-Type', 'application/json; charset=utf-8')
  6. .send({ hello: 'world' })
  7. })

另外,Reply 能够访问请求的上下文:

  1. fastify.get('/', {config: {foo: 'bar'}}, function (request, reply) {
  2. reply.send('handler config.foo = ' + reply.context.config.foo)
  3. })

.code(statusCode)

如果没有设置 reply.codestatusCode 会是 200

.statusCode

获取或设置 HTTP 状态码。作为 setter 使用时,是 reply.code() 的别名。

  1. if (reply.statusCode >= 299) {
  2. reply.statusCode = 500
  3. }

.header(key, value)

设置响应 header。如果值被省略或为 undefined,将被强制设成 ''

更多信息,请看 http.ServerResponse#setHeader

.getHeader(key)

获取已设置的 header 的值。

  1. reply.header('x-foo', 'foo') // 设置 x-foo header 的值为 foo
  2. reply.getHeader('x-foo') // 'foo'

.removeHeader(key)

清除已设置的 header 的值。

  1. reply.header('x-foo', 'foo')
  2. reply.removeHeader('x-foo')
  3. reply.getHeader('x-foo') // undefined

.hasHeader(key)

返回一个 boolean,用于检查是否设置了某个 header。

.redirect([code ,] dest)

重定向请求至指定的 url,状态码可选,当未通过 code 方法设置时,默认为 302

示例 (不调用 reply.code()):状态码 302,重定向至 /home

  1. reply.redirect('/home')

示例 (不调用 reply.code()):状态码 303,重定向至 /home

  1. reply.redirect(303, '/home')

示例 (调用 reply.code()):状态码 303,重定向至 /home

  1. reply.code(303).redirect('/home')

示例 (调用 reply.code()):状态码 302,重定向至 /home

  1. reply.code(303).redirect(302, '/home')

.callNotFound()

调用自定义的 not found 处理函数。 要注意的是,只有 setNotFoundHandler 中指明的 preHandler 钩子函数会被调用。

  1. reply.callNotFound()

.getResponseTime()

调用自定义响应时间获取函数,来计算自收到请求起的时间。

  1. const milliseconds = reply.getResponseTime()

.type(contentType, type)

设置响应的 content type。 这是 reply.header('Content-Type', 'the/type') 的简写。

  1. reply.type('text/html')

.serializer(func)

.send() 方法会默认将 BufferstreamstringundefinedError 之外类型的值 JSON-序列化。假如你需要在特定的请求上使用自定义的序列化工具,你可以通过 .serializer() 来实现。要注意的是,如果使用了自定义的序列化工具,你必须同时设置 'Content-Type' header。

  1. reply
  2. .header('Content-Type', 'application/x-protobuf')
  3. .serializer(protoBuf.serialize)

注意,你并不需要在一个 handler 内部使用这一工具,因为 Buffers、streams 以及字符串 (除非已经设置了序列化工具) 被认为是已序列化过的。

  1. reply
  2. .header('Content-Type', 'application/x-protobuf')
  3. .send(protoBuf.serialize(data))

请看 .send() 了解更多关于发送不同类型值的信息。

.sent

如你所见,.sent 属性表明是否已通过 reply.send() 发送了一个响应。

当控制器是一个 async 函数或返回一个 promise 时,可以手动设置 reply.sent = true,以防 promise resolve 时自动调用 reply.send()。通过设置 reply.sent = true,程序能完全掌控底层的请求,且相关钩子不会被触发。

请看范例:

  1. app.get('/', (req, reply) => {
  2. reply.sent = true
  3. reply.res.end('hello world')
  4. return Promise.resolve('this will be skipped') // 译注:该处会被跳过
  5. })

如果处理函数 reject,将会记录一个错误。

.send(data)

顾名思义,.send() 是向用户发送 payload 的函数。

对象

如上文所述,如果你发送 JSON 对象时,设置了输出的 schema,那么 send 会使用 fast-json-stringify 来序列化对象。否则,将使用 JSON.stringify()

  1. fastify.get('/json', options, function (request, reply) {
  2. reply.send({ hello: 'world' })
  3. })

字符串

在未设置 Content-Type 的时候,字符串会以 text/plain; charset=utf-8 类型发送。如果设置了 Content-Type,且使用自定义序列化工具,那么 send 发出的字符串会被序列化。否则,字符串不会有任何改动 (除非 Content-Type 的值为 application/json; charset=utf-8,这时,字符串会像对象一样被 JSON-序列化,正如上一节所述)。

  1. fastify.get('/json', options, function (request, reply) {
  2. reply.send('plain string')
  3. })

Streams

send 开箱即用地支持 stream。它使用 pump 来避免文件描述符 (file descriptors) 的泄露。如果在未设置 'Content-Type' header 的情况下发送 stream,它会被设定为 'application/octet-stream'

  1. fastify.get('/streams', function (request, reply) {
  2. const fs = require('fs')
  3. const stream = fs.createReadStream('some-file', 'utf8')
  4. reply.send(stream)
  5. })

Buffers

未设置 'Content-Type' header 的情况下发送 buffer,send 会将其设置为 'application/octet-stream'

  1. const fs = require('fs')
  2. fastify.get('/streams', function (request, reply) {
  3. fs.readFile('some-file', (err, fileBuffer) => {
  4. reply.send(err || fileBuffer)
  5. })
  6. })

Errors

若使用 send 发送一个 Error 的实例,Fastify 会自动创建一个如下的错误结构:

  1. {
  2. error: String // http 错误信息
  3. code: String // Fastify 的错误代码
  4. message: String // 用户错误信息
  5. statusCode: Number // http 状态码
  6. }

你可以向 Error 对象添加自定义属性,例如 headers,这可以用来增强 http 响应。
注意:如果 send 一个错误,但状态码小于 400,Fastify 会自动将其设为 500。

贴士:你可以通过 http-errorsfastify-sensible 来简化生成的错误:

  1. fastify.get('/', function (request, reply) {
  2. reply.send(httpErrors.Gone())
  3. })

如果你想完全自定义错误处理,请看 setErrorHandler API。
注:当自定义错误处理时,你需要自行记录日志

API:

  1. fastify.setErrorHandler(function (error, request, reply) {
  2. request.log.warn(error)
  3. var statusCode = error.statusCode >= 400 ? error.statusCode : 500
  4. reply
  5. .code(statusCode)
  6. .type('text/plain')
  7. .send(statusCode >= 500 ? 'Internal server error' : error.message)
  8. })

路由生成的 not found 错误会使用 setNotFoundHandler。 API:

  1. fastify.setNotFoundHandler(function (request, reply) {
  2. reply
  3. .code(404)
  4. .type('text/plain')
  5. .send('a custom not found')
  6. })

最终 payload 的类型

发送的 payload (序列化之后、经过任意的 onSend 钩子) 必须为下列类型之一,否则将会抛出一个错误:

  • string
  • Buffer
  • stream
  • undefined
  • null

Async-Await 与 Promise

Fastify 原生地处理 promise 并支持 async-await。
请注意,在下面的例子中我们没有使用 reply.send。

  1. const delay = promisify(setTimeout)
  2. fastify.get('/promises', options, function (request, reply) {
  3. return delay(200).then(() => { return { hello: 'world' }})
  4. })
  5. fastify.get('/async-await', options, async function (request, reply) {
  6. await delay(200)
  7. return { hello: 'world' }
  8. })

被 reject 的 promise 默认发送 500 状态码。要修改回复,可以 reject 一个 promise,或在 async 函数 中进行 throw 操作,同时附带上一个有 statusCode (或 status) 与 message 属性的 Error 对象。不支持抛出普通的对象,必须是 Error 的实例:

  1. fastify.get('/teapot', async function (request, reply) => {
  2. const err = new Error()
  3. err.statusCode = 418
  4. err.message = 'short and stout'
  5. throw err
  6. })

想要了解更多?请看 Routes#async-await

.then(fullfilled, rejected)

顾名思义,Reply 对象能被等待。换句话说,await reply 将会等待,直到回复被发送。 如上的 await 语法调用了 reply.then()

reply.then(fullfilled, rejected) 接受两个参数:

  • fullfilled 会在响应完全发送后被调用。
  • rejected 会在底层的 stream 出现错误时被调用。例如,socket 连接被破坏时。

更多细节,请看: