Fastify

TypeScript

尽管 Fastify 自带了 typings 声明文件，你可能仍然需要根据所使用的 Node.js 版本来安装 @types/node。

Types 支持

我们关注 TypeScript 社区，当前也有一名团队的核心成员正在重做所有的 types。 我们尽自己最大的努力来保证 typings 文件与最新的 API 同步，但并不能完全避免不同步的情况发生。
幸运的是这是个开源项目，你可以参与修复。我们十分欢迎你的贡献，并会尽快发布补丁。请看 贡献 指南吧！

插件有可能包含 typings，也可能没有。具体信息请参阅 插件类型。

示例

以下 TypeScript 的程序示例和 JavaScript 版本的示例紧密相似：

  1. import * as fastify from 'fastify'
  2. import { Server, IncomingMessage, ServerResponse } from 'http'
  4. // 创建一个 http 服务器，将 http 对应版本所使用的 typings 传递过去。
  5. // 这么做我们便能获知路由底层 http 对象的结构。
  6. // 如果使用 http2，你应该传递 <http2.Http2Server, http2.Http2ServerRequest, http2.Http2ServerResponse>
  7. // 如果使用 https，则是 http2.Http2SecureServer 或 http.SecureServer，而不是 Server。
  8. const server: fastify.FastifyInstance<Server, IncomingMessage, ServerResponse> = fastify({})
  10. const opts: fastify.RouteShorthandOptions = {
  11.   schema: {
  12.     response: {
  13.       200: {
  14.         type: 'object',
  15.         properties: {
  16.           pong: {
  17.             type: 'string'
  18.           }
  19.         }
  20.       }
  21.     }
  22.   }
  23. }
  25. server.get('/ping', opts, (request, reply) => {
  26.   console.log(reply.res) // 带有正确 typings 的 http.ServerResponse！
  27.   reply.code(200).send({ pong: 'it worked!' })
  28. })

一般类型的参数

你不但可以校验 querystring、url 参数、body 以及 header，你还可以覆盖 request 接口中定义的默认类型：

  1. import * as fastify from 'fastify'
  3. const server = fastify({})
  5. interface Query {
  6.   foo?: number
  7. }
  9. interface Params {
  10.   bar?: string
  11. }
  13. interface Body {
  14.   baz?: string
  15. }
  17. interface Headers {
  18.   a?: string
  19. }
  21. const opts: fastify.RouteShorthandOptions = {
  22.   schema: {
  23.     querystring: {
  24.       type: 'object',
  25.       properties: {
  26.         foo: {
  27.           type: 'number'
  28.         }
  29.       }
  30.     },
  31.     params: {
  32.       type: 'object',
  33.       properties: {
  34.         bar: {
  35.           type: 'string'
  36.         }
  37.       }
  38.     },
  39.     body: {
  40.       type: 'object',
  41.       properties: {
  42.         baz: {
  43.           type: 'string'
  44.         }
  45.       }
  46.     },
  47.     headers: {
  48.       type: 'object',
  49.       properties: {
  50.         a: {
  51.           type: 'string'
  52.         }
  53.       }
  54.     }
  55.   }
  56. }
  58. server.get<Query, Params, Headers, Body>('/ping/:bar', opts, (request, reply) => {
  59.   console.log(request.query) // 这是 Query 类型
  60.   console.log(request.params) // 这是 Params 类型
  61.   console.log(request.headers) // 这是 Headers 类型
  62.   console.log(request.body) // 这是 Body 类型
  63.   reply.code(200).send({ pong: 'it worked!' })
  64. })

所有的一般类型都是可选的，因此你可以只传递你使用 schema 校验的类型：

  1. import * as fastify from 'fastify'
  3. const server = fastify({})
  5. interface Params {
  6.   bar?: string
  7. }
  9. const opts: fastify.RouteShorthandOptions = {
  10.   schema: {
  11.     params: {
  12.       type: 'object',
  13.       properties: {
  14.         bar: {
  15.           type: 'string'
  16.         }
  17.       }
  18.     },
  19.   }
  20. }
  22. server.get<fastify.DefaultQuery, Params, unknown>('/ping/:bar', opts, (request, reply) => {
  23.   console.log(request.query) // 这是 fastify.DefaultQuery 类型
  24.   console.log(request.params) // 这是 Params 类型
  25.   console.log(request.headers) // 这是未知的类型
  26.   console.log(request.body) // 这是 fastify.DefaultBody 类型，因为 typescript 会使用默认类型
  27.   reply.code(200).send({ pong: 'it worked!' })
  28. })
  30. // 假设你不校验 querystring、body 或者 header，
  31. // 最好将类型设为 `unknown`。但这个选择取决于你。
  32. // 下面的例子展示了这一做法，它可以避免你搬起石头砸自己的脚。
  33. // 换句话说，就是别使用不去校验的类型。
  34. server.get<unknown, Params, unknown, unknown>('/ping/:bar', opts, (request, reply) => {
  35.   console.log(request.query) // 这是未知的类型
  36.   console.log(request.params) // 这是 Params 类型
  37.   console.log(request.headers) // 这是未知的类型
  38.   console.log(request.body) // 这是未知的类型
  39.   reply.code(200).send({ pong: 'it worked!' })
  40. })

HTTP 原型

默认情况下，Fastify 会根据你给的配置决定使用 http 的哪个版本。出于某种原因需要覆盖的话，你可以这么做：

  1. interface CustomIncomingMessage extends http.IncomingMessage {
  2.   getClientDeviceType: () => string
  3. }
  5. // 将覆盖的 http 原型传给 Fastify
  6. const server: fastify.FastifyInstance<http.Server, CustomIncomingMessage, http.ServerResponse> = fastify()
  8. server.get('/ping', (request, reply) => {
  9.   // 使用自定义的 http 原型方法
  10.   const clientDeviceType = request.raw.getClientDeviceType()
  12.   reply.send({ clientDeviceType: `you called this endpoint from a ${clientDeviceType}` })
  13. })

在这个例子中，我们传递了一个经过修改的 http.IncomingMessage 接口，该接口在程序的其他地方得到了扩展。

贡献

和 TypeScript 相关的改动可以被归入下列类别：

  • Core - Fastify 的 typings 文件
  • Plugins - Fastify 插件

记得要先阅读 CONTRIBUTING.md 文件，确保行事顺利！

核心类型

当更新核心类型时，你应当向本仓库发一个 PR。请确保：

  1. 将改动反映在 examples/typescript-server.ts 文件中 (当需要时)
  2. 更新 test/types/index.ts 来验证改动是否成功

插件类型

和 fastify 仓库一样，由 GitHub 上的 fastify 组织所维护的插件，应当自带 typings 文件。 目前一些插件还没有 typings 文件，我们很欢迎你参与其中。typings 的例子请看 fastify-cors 仓库。

第三方插件可能自带 typings 文件，或存放于 DefinitelyTyped 之上。请记住，如果你写了一个插件，也请选择上述两种途径之一来存放 typings 文件！从 DefinitelyTyped 安装 typings 的方法可以在这里找到。

一些类型可能还不可用，因此尽管去贡献吧。

编写插件类型

扩展了 FastifyRequest、FastifyReply 或 FastifyInstance 对象的许多插件，可以通过如下方式获取。

以下代码展示了 fastify-static 插件的 typings。

  1. /// <reference types="node" />
  3. // 导入 fastify typings
  4. import * as fastify from 'fastify';
  6. // 导入必需的 http, http2, https typings
  7. import { Server, IncomingMessage, ServerResponse } from "http";
  8. import { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse } from "http2";
  9. import * as https from "https";
  10. type HttpServer = Server | Http2Server | Http2SecureServer | https.Server;
  11. type HttpRequest = IncomingMessage | Http2ServerRequest;
  12. type HttpResponse = ServerResponse | Http2ServerResponse;
  14. // 拓展 fastify typings
  15. declare module "fastify" {
  16.   interface FastifyReply<HttpResponse> {
  17.     sendFile(filename: string): FastifyReply<HttpResponse>;
  18.   }
  19. }
  21. // 使用 fastify.Plugin 声明插件的类型
  22. declare function fastifyStatic(): fastify.Plugin<
  23.   Server,
  24.   IncomingMessage,
  25.   ServerResponse,
  26.   {
  27.     root: string;
  28.     prefix?: string;
  29.     serve?: boolean;
  30.     decorateReply?: boolean;
  31.     schemaHide?: boolean;
  32.     setHeaders?: (...args: any[]) => void;
  33.     redirect?: boolean;
  34.     wildcard?: boolean | string;
  36.     // `send` 的选项
  37.     acceptRanges?: boolean;
  38.     cacheControl?: boolean;
  39.     dotfiles?: boolean;
  40.     etag?: boolean;
  41.     extensions?: string[];
  42.     immutable?: boolean;
  43.     index?: string[];
  44.     lastModified?: boolean;
  45.     maxAge?: string | number;
  46.   }
  47. >;
  49. declare namespace fastifyStatic {
  50.   interface FastifyStaticOptions {}
  51. }
  53. // 导出插件类型
  54. export = fastifyStatic;

现在你便可以如此使用插件了：

  1. import * as Fastify from 'fastify'
  2. import * as fastifyStatic from 'fastify-static'
  4. const app = Fastify()
  6. // 这里的配置项会类型检查
  7. app.register(fastifyStatic, {
  8.   acceptRanges: true,
  9.   cacheControl: true,
  10.   decorateReply: true,
  11.   dotfiles: true,
  12.   etag: true,
  13.   extensions: ['.js'],
  14.   immutable: true,
  15.   index: ['1'],
  16.   lastModified: true,
  17.   maxAge: '',
  18.   prefix: '',
  19.   root: '',
  20.   schemaHide: true,
  21.   serve: true,
  22.   setHeaders: (res, pathName) => {
  23.     res.setHeader('some-header', pathName)
  24.   }
  25. })
  27. app.get('/file', (request, reply) => {
  28.   // 使用上文定义的 FastifyReply.sendFile 方法
  29.   reply.sendFile('some-file-name')
  30. })

给我们所有的插件加上 typings 需要社区的努力，因此尽管来贡献吧！