TypeScript

Fastify 框架是用普通 JavaScript 编写的，因此类型定义不太容易维护；然而，自版本 2 及更高版本以来，维护者和贡献者付出了巨大的努力来改进类型。

¥The Fastify framework is written in vanilla JavaScript, and as such type definitions are not as easy to maintain; however, since version 2 and beyond, maintainers and contributors have put in a great effort to improve the types.

Fastify 版本 3 中更改了类型系统。新的类型系统引入了通用约束和默认，以及定义模式类型（例如请求正文、查询字符串等）的新方法！由于团队致力于改进框架和类型定义协同作用，有时 API 的某些部分不会被键入或可能键入不正确。我们鼓励你做出贡献，帮助我们填补空白。在开始之前，请务必阅读我们的 CONTRIBUTING.md 文件，以确保一切顺利！

¥The type system was changed in Fastify version 3. The new type system introduces generic constraining and defaulting, plus a new way to define schema types such as a request body, querystring, and more! As the team works on improving framework and type definition synergy, sometimes parts of the API will not be typed or may be typed incorrectly. We encourage you to contribute to help us fill in the gaps. Just make sure to read our CONTRIBUTING.md file before getting started to make sure things go smoothly!

本节中的文档涵盖 Fastify 版本 3.x 类型
¥The documentation in this section covers Fastify version 3.x typings

插件可能包含也可能不包含类型。有关更多信息，请参阅插件。我们鼓励用户发送拉取请求以改善打字支持。
¥Plugins may or may not include typings. See Plugins for more information. We encourage users to send pull requests to improve typings support.

🚨 不要忘记安装 @types/node

¥🚨 Don't forget to install @types/node

通过实例学习

¥Learn By Example

学习 Fastify 类型系统的最佳方法是通过示例！以下四个示例应涵盖最常见的 Fastify 开发案例。示例之后还有关于类型系统的进一步、更详细的文档。

¥The best way to learn the Fastify type system is by example! The following four examples should cover the most common Fastify development cases. After the examples there is further, more detailed documentation for the type system.

入门

¥Getting Started

此示例将帮助你启动并运行 Fastify 和 TypeScript。它会导致一个空白的 http Fastify 服务器。

¥This example will get you up and running with Fastify and TypeScript. It results in a blank http Fastify server.

创建一个新的 npm 项目，安装 Fastify，并安装 typescript 和 Node.js 类型作为对等依赖：
¥Create a new npm project, install Fastify, and install typescript & Node.js types as peer dependencies:

npm init -y
npm i fastify
npm i -D typescript @types/node

将以下行添加到 package.json 的 "scripts" 部分：
¥Add the following lines to the "scripts" section of the package.json:

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node index.js"
  }
}

初始化 TypeScript 配置文件：
¥Initialize a TypeScript configuration file:

npx tsc --init

或者使用推荐的之一。

¥or use one of the recommended ones.

注意：将 tsconfig.json 中的 target 属性设置为 es2017 或更高以避免 FastifyDeprecation 警告。

¥Note: Set target property in tsconfig.json to es2017 or greater to avoid FastifyDeprecation warning.

创建 index.ts 文件 - 这将包含服务器代码
¥Create an index.ts file - this will contain the server code

将以下代码块添加到你的文件中：

¥Add the following code block to your file:

import fastify from 'fastify'

const server = fastify()

server.get('/ping', async (request, reply) => {
  return 'pong\n'
})

server.listen({ port: 8080 }, (err, address) => {
  if (err) {
    console.error(err)
    process.exit(1)
  }
  console.log(`Server listening at ${address}`)
})

运行 npm run build - 这会将 index.ts 编译为 index.js，可以使用 Node.js 执行。如果你遇到任何错误，请在 fastify/help 中打开一个问题
¥Run npm run build - this will compile index.ts into index.js which can be executed using Node.js. If you run into any errors please open an issue in fastify/help
运行 npm run start 以运行 Fastify 服务器
¥Run npm run start to run the Fastify server
你应该在控制台中看到 Server listening at http://127.0.0.1:8080
¥You should see Server listening at http://127.0.0.1:8080 in your console
使用 curl localhost:8080/ping 试用你的服务器，它应该返回 pong 🏓
¥Try out your server using curl localhost:8080/ping, it should return pong 🏓

🎉 你现在已经有了一个可以运行的 Typescript Fastify 服务器！此示例演示了 3.x 版本类型系统的简单性。默认情况下，类型系统假定你正在使用 http 服务器。后面的示例将演示如何创建更复杂的服务器，例如 https 和 http2、如何指定路由模式等等！

¥🎉 You now have a working Typescript Fastify server! This example demonstrates the simplicity of the version 3.x type system. By default, the type system assumes you are using an http server. The later examples will demonstrate how to create more complex servers such as https and http2, how to specify route schemas, and more!

有关使用 TypeScript 初始化 Fastify 的更多示例（例如启用 HTTP2），请查看详细的 API 部分此处
¥For more examples on initializing Fastify with TypeScript (such as enabling HTTP2) check out the detailed API section here

使用泛型

¥Using Generics

类型系统严重依赖泛型属性来提供最准确的开发体验。虽然有些人可能会觉得开销有点麻烦，但这种权衡是值得的！本示例将深入研究如何实现路由架构的泛型类型以及位于路由级 request 对象上的动态属性。

¥The type system heavily relies on generic properties to provide the most accurate development experience. While some may find the overhead a bit cumbersome, the tradeoff is worth it! This example will dive into implementing generic types for route schemas and the dynamic properties located on the route-level request object.

如果你未完成前面的示例，请按照步骤 1-4 进行设置。
¥If you did not complete the previous example, follow steps 1-4 to get set up.

在 index.ts 内部，定义三个接口 IQuerystring、IHeaders 和 IReply：

¥Inside index.ts, define three interfaces IQuerystring,IHeaders and IReply:

interface IQuerystring {
  username: string;
  password: string;
}

interface IHeaders {
  'h-Custom': string;
}

interface IReply {
  200: { success: boolean };
  302: { url: string };
  '4xx': { error: string };
}

使用这三个接口，定义一个新的 API 路由并将它们作为泛型传递。简写路由方法（即 .get）接受包含五个命名属性的通用对象 RouteGenericInterface：Body、Querystring、Params、Headers 和 Reply。接口 Body、Querystring、Params 和 Headers 将通过路由方法传递到路由方法处理程序 request 实例和 Reply 接口到 reply 实例。
¥Using the three interfaces, define a new API route and pass them as generics. The shorthand route methods (i.e. .get) accept a generic object RouteGenericInterface containing five named properties: Body, Querystring, Params, Headers and Reply. The interfaces Body, Querystring, Params and Headers will be passed down through the route method into the route method handler request instance and the Reply interface to the reply instance.
```
server.get<{
  Querystring: IQuerystring,
  Headers: IHeaders,
  Reply: IReply
}>('/auth', async (request, reply) => {
  const { username, password } = request.query
  const customerHeader = request.headers['h-Custom']
  // do something with request data

  // chaining .statusCode/.code calls with .send allows type narrowing. For example:
  // this works
  reply.code(200).send({ success: true });
  // but this gives a type error
  reply.code(200).send('uh-oh');
  // it even works for wildcards
  reply.code(404).send({ error: 'Not found' });
  return `logged in!`
})
```
使用 npm run build 和 npm run start 构建并运行服务器代码
¥Build and run the server code with npm run build and npm run start
查询 API
¥Query the API
```
curl localhost:8080/auth?username=admin&password=Password123!
```
它应该返回 logged in!
¥And it should return back logged in!

但等等还有更多！通用接口也可在路由级别钩子方法内使用。通过添加 preValidation 钩子修改上一个路由：

¥But wait there's more! The generic interfaces are also available inside route level hook methods. Modify the previous route by adding a preValidation hook:

server.get<{
  Querystring: IQuerystring,
  Headers: IHeaders,
  Reply: IReply
}>('/auth', {
  preValidation: (request, reply, done) => {
    const { username, password } = request.query
    done(username !== 'admin' ? new Error('Must be admin') : undefined) // only validate `admin` account
  }
}, async (request, reply) => {
  const customerHeader = request.headers['h-Custom']
  // do something with request data
  return `logged in!`
})

构建并运行查询，将 username 查询字符串选项设置为除 admin 以外的任何值。API 现在应该返回 HTTP 500 错误 {"statusCode":500,"error":"Internal Server Error","message":"Must be admin"}
¥Build and run and query with the username query string option set to anything other than admin. The API should now return a HTTP 500 error {"statusCode":500,"error":"Internal Server Error","message":"Must be admin"}

🎉 干得好，现在你可以为每个路由定义接口，并具有严格类型化的请求和响应实例。Fastify 类型系统的其他部分依赖于通用属性。请务必参考下面的详细类型系统文档，以了解有关可用内容的更多信息。

¥🎉 Good work, now you can define interfaces for each route and have strictly typed request and reply instances. Other parts of the Fastify type system rely on generic properties. Make sure to reference the detailed type system documentation below to learn more about what is available.

JSON 结构

¥JSON Schema

要验证你的请求和响应，你可以使用 JSON 架构文件。如果你还不知道，为 Fastify 路由定义模式可以提高其吞吐量！查看验证和序列化文档以获取更多信息。

¥To validate your requests and responses you can use JSON Schema files. If you didn't know already, defining schemas for your Fastify routes can increase their throughput! Check out the Validation and Serialization documentation for more info.

它还具有在处理程序中使用定义的类型（包括预验证等）的优点。

¥Also it has the advantage to use the defined type within your handlers (including pre-validation, etc.).

以下是有关如何实现此目标的一些选项。

¥Here are some options on how to achieve this.

Fastify 类型提供商

¥Fastify Type Providers

Fastify 提供两个封装 json-schema-to-ts 和 typebox 的包：

¥Fastify offers two packages wrapping json-schema-to-ts and typebox:

以及第三方的 zod 封装器，名为 fastify-type-provider-zod

¥And a zod wrapper by a third party called fastify-type-provider-zod

它们简化了模式验证设置，你可以在类型提供者页面中阅读有关它们的更多信息。

¥They simplify schema validation setup and you can read more about them in Type Providers page.

以下是如何使用没有类型提供程序的 typebox、json-schema-to-typescript 和 json-schema-to-ts 包设置模式验证。

¥Below is how to setup schema validation using the typebox, json-schema-to-typescript, and json-schema-to-ts packages without type providers.

TypeBox

用于同时构建类型和模式的有用库是 TypeBox。使用 TypeBox，你可以在代码中定义模式，并根据需要直接将它们用作类型或模式。

¥A useful library for building types and a schema at once is TypeBox. With TypeBox you define your schema within your code and use them directly as types or schemas as you need them.

当你想使用它来验证 fastify 路由中的某些有效负载时，你可以按如下方式操作：

¥When you want to use it for validation of some payload in a fastify route you can do it as follows:

在你的项目中安装 typebox。
¥Install typebox in your project.
```
npm i @sinclair/typebox
```

使用 Type 定义所需的模式，并使用 Static 创建相应的类型。

¥Define the schema you need with Type and create the respective type with Static.

import { Static, Type } from '@sinclair/typebox'

export const User = Type.Object({
  name: Type.String(),
  mail: Type.Optional(Type.String({ format: 'email' })),
})

export type UserType = Static<typeof User>

在定义路由期间使用定义的类型和架构

¥Use the defined type and schema during the definition of your route

import Fastify from 'fastify'
// ...

const fastify = Fastify()

fastify.post<{ Body: UserType, Reply: UserType }>(
  '/',
  {
    schema: {
      body: User,
      response: {
        200: User
      },
    },
  },
  (request, reply) => {
    // The `name` and `mail` types are automatically inferred
    const { name, mail } = request.body;
    reply.status(200).send({ name, mail });
  }
)

json-schema-to-typescript

在最后一个示例中，我们使用 Typebox 来定义路由的类型和模式。许多用户已经在使用 JSON 模式来定义这些属性，幸运的是，有一种方法可以将现有的 JSON 模式转换为 TypeScript 接口！

¥In the last example we used Typebox to define the types and schemas for our route. Many users will already be using JSON Schemas to define these properties, and luckily there is a way to transform existing JSON Schemas into TypeScript interfaces!

如果你没有完成 '入门' 示例，请返回并首先按照步骤 1-4 进行操作。
¥If you did not complete the 'Getting Started' example, go back and follow steps 1-4 first.
安装 json-schema-to-typescript 模块：
¥Install the json-schema-to-typescript module:
```
npm i -D json-schema-to-typescript
```

创建一个名为 schemas 的新文件夹并添加两个文件 headers.json 和 querystring.json。将以下架构定义复制并粘贴到相应的文件中：

¥Create a new folder called schemas and add two files headers.json and querystring.json. Copy and paste the following schema definitions into the respective files:

{
  "title": "Headers Schema",
  "type": "object",
  "properties": {
    "h-Custom": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["h-Custom"]
}

{
  "title": "Querystring Schema",
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "password": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["username", "password"]
}

将 compile-schemas 脚本添加到 package.json：
¥Add a compile-schemas script to the package.json:

   {
     "scripts": {
       "compile-schemas": "json2ts -i schemas -o types"
     }
   }

json2ts 是 json-schema-to-typescript 中包含的 CLI 实用程序。schemas 是输入路径，types 是输出路径。5.应该已经在 types 目录中创建了两个新文件。6.

¥json2ts is a CLI utility included in json-schema-to-typescript. schemas is the input path, and types is the output path. 5. Run npm run compile-schemas. Two new files should have been created in the types directory. 6. Update index.ts to have the following code:

   import fastify from 'fastify'

   // import json schemas as normal
   import QuerystringSchema from './schemas/querystring.json'
   import HeadersSchema from './schemas/headers.json'

   // import the generated interfaces
   import { QuerystringSchema as QuerystringSchemaInterface } from './types/querystring'
   import { HeadersSchema as HeadersSchemaInterface } from './types/headers'

   const server = fastify()

   server.get<{
     Querystring: QuerystringSchemaInterface,
     Headers: HeadersSchemaInterface
   }>('/auth', {
     schema: {
       querystring: QuerystringSchema,
       headers: HeadersSchema
     },
     preValidation: (request, reply, done) => {
       const { username, password } = request.query
       done(username !== 'admin' ? new Error('Must be admin') : undefined)
     }
     //  or if using async
     //  preValidation: async (request, reply) => {
     //    const { username, password } = request.query
     //    if (username !== "admin") throw new Error("Must be admin");
     //  }
   }, async (request, reply) => {
     const customerHeader = request.headers['h-Custom']
     // do something with request data
     return `logged in!`
   })

   server.route<{
     Querystring: QuerystringSchemaInterface,
     Headers: HeadersSchemaInterface
   }>({
     method: 'GET',
     url: '/auth2',
     schema: {
       querystring: QuerystringSchema,
       headers: HeadersSchema
     },
     preHandler: (request, reply, done) => {
       const { username, password } = request.query
       const customerHeader = request.headers['h-Custom']
       done()
     },
     handler: (request, reply) => {
       const { username, password } = request.query
       const customerHeader = request.headers['h-Custom']
       reply.status(200).send({username});
     }
   })

   server.listen({ port: 8080 }, (err, address) => {
     if (err) {
       console.error(err)
       process.exit(0)
     }
     console.log(`Server listening at ${address}`)
   })

请特别注意此文件顶部的导入。这可能看起来多余，但你需要导入架构文件和生成的接口。

¥Pay special attention to the imports at the top of this file. It might seem redundant, but you need to import both the schema files and the generated interfaces.

做得好！现在你可以使用 JSON 模式和 TypeScript 定义。

¥Great work! Now you can make use of both JSON Schemas and TypeScript definitions.

json-schema-to-ts

如果你不想从架构中生成类型，而是想直接从代码中使用它们，则可以使用 json-schema-to-ts 包。

¥If you do not want to generate types from your schemas, but want to use them directly from your code, you can use the package json-schema-to-ts.

你可以将其安装为开发依赖。

¥You can install it as dev-dependency.

npm i -D json-schema-to-ts

在代码中，你可以像普通对象一样定义模式。但请注意将其设置为 const，如模块文档中所解释的那样。

¥In your code you can define your schema like a normal object. But be aware of making it const like explained in the docs of the module.

const todo = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    description: { type: 'string' },
    done: { type: 'boolean' },
  },
  required: ['name'],
} as const; // don't forget to use const !

使用提供的类型 FromSchema，你可以从模式构建类型并在处理程序中使用它。

¥With the provided type FromSchema you can build a type from your schema and use it in your handler.

import { FromSchema } from "json-schema-to-ts";
fastify.post<{ Body: FromSchema<typeof todo> }>(
  '/todo',
  {
    schema: {
      body: todo,
      response: {
        201: {
          type: 'string',
        },
      },
    }
  },
  async (request, reply): Promise<void> => {

    /*
    request.body has type
    {
      [x: string]: unknown;
      description?: string;
      done?: boolean;
      name: string;
    }
    */

    request.body.name // will not throw type error
    request.body.notthere // will throw type error

    reply.status(201).send();
  },
);

插件

¥Plugins

Fastify 最显着的功能之一是其广泛的插件生态系统。插件类型完全受支持，并利用声明合并模式。该示例分为三个部分：创建 TypeScript Fastify 插件、为 Fastify 插件创建类型定义以及在 TypeScript 项目中使用 Fastify 插件。

¥One of Fastify's most distinguishable features is its extensive plugin ecosystem. Plugin types are fully supported, and take advantage of the declaration merging pattern. This example is broken up into three parts: Creating a TypeScript Fastify Plugin, Creating Type Definitions for a Fastify Plugin, and Using a Fastify Plugin in a TypeScript Project.

创建 TypeScript Fastify 插件

¥Creating a TypeScript Fastify Plugin

初始化一个新的 npm 项目并安装所需的依赖
¥Initialize a new npm project and install required dependencies
```
npm init -y
npm i fastify fastify-plugin
npm i -D typescript @types/node
```
将 build 脚本添加到 package.json 文件的 "scripts" 部分，将 'index.d.ts' 添加到 "types" 部分：
¥Add a build script to the "scripts" section and 'index.d.ts' to the "types" section of the package.json file:
```
{
  "types": "index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}
```
初始化 TypeScript 配置文件：
¥Initialize a TypeScript configuration file:
```
npx typescript --init
```
生成文件后，在 "compilerOptions" 对象中启用 "declaration" 选项。
¥Once the file is generated, enable the "declaration" option in the "compilerOptions" object.
```
{
  "compilerOptions": {
    "declaration": true
  }
}
```
创建 index.ts 文件 - 这将包含插件代码
¥Create an index.ts file - this will contain the plugin code

将以下代码添加到 index.ts

¥Add the following code to index.ts

import { FastifyPluginCallback, FastifyPluginAsync } from 'fastify'
import fp from 'fastify-plugin'

// using declaration merging, add your plugin props to the appropriate fastify interfaces
// if prop type is defined here, the value will be typechecked when you call decorate{,Request,Reply}
declare module 'fastify' {
  interface FastifyRequest {
    myPluginProp: string
  }
  interface FastifyReply {
    myPluginProp: number
  }
}

// define options
export interface MyPluginOptions {
  myPluginOption: string
}

// define plugin using callbacks
const myPluginCallback: FastifyPluginCallback<MyPluginOptions> = (fastify, options, done) => {
  fastify.decorateRequest('myPluginProp', 'super_secret_value')
  fastify.decorateReply('myPluginProp', options.myPluginOption)

  done()
}

// define plugin using promises
const myPluginAsync: FastifyPluginAsync<MyPluginOptions> = async (fastify, options) => {
  fastify.decorateRequest('myPluginProp', 'super_secret_value')
  fastify.decorateReply('myPluginProp', options.myPluginOption)
}

// export plugin using fastify-plugin
export default fp(myPluginCallback, '3.x')
// or
// export default fp(myPluginAsync, '3.x')

运行 npm run build 以编译插件代码并生成 JavaScript 源文件和类型定义文件。
¥Run npm run build to compile the plugin code and produce both a JavaScript source file and a type definition file.
插件现已完成，你可以[发布到 npm]或在本地使用它。
¥With the plugin now complete you can [publish to npm] or use it locally.
你无需将插件发布到 npm 即可使用它。你可以将其包含在 Fastify 项目中并像引用任何代码一样引用它！作为 TypeScript 用户，请确保声明覆盖存在于将包含在项目编译中的某个地方，以便 TypeScript 解释器可以处理它。
¥You do not need to publish your plugin to npm to use it. You can include it in a Fastify project and reference it as you would any piece of code! As a TypeScript user, make sure the declaration override exists somewhere that will be included in your project compilation so the TypeScript interpreter can process it.

为 Fastify 插件创建类型定义

¥Creating Type Definitions for a Fastify Plugin

本插件指南适用于用 JavaScript 编写的 Fastify 插件。本示例中概述的步骤是为使用你的插件的用户添加 TypeScript 支持。

¥This plugin guide is for Fastify plugins written in JavaScript. The steps outlined in this example are for adding TypeScript support for users consuming your plugin.

初始化一个新的 npm 项目并安装所需的依赖
¥Initialize a new npm project and install required dependencies
```
npm init -y
npm i fastify-plugin
```
创建两个文件 index.js 和 index.d.ts
¥Create two files index.js and index.d.ts
修改包 json 以在 main 和 types 属性下包含这些文件（名称不必明确为 index，但建议文件具有相同的名称）：
¥Modify the package json to include these files under the main and types properties (the name does not have to be index explicitly, but it is recommended the files have the same name):
```
{
  "main": "index.js",
  "types": "index.d.ts"
}
```

打开 index.js 并添加以下代码：

¥Open index.js and add the following code:

// fastify-plugin is highly recommended for any plugin you write
const fp = require('fastify-plugin')

function myPlugin (instance, options, done) {

  // decorate the fastify instance with a custom function called myPluginFunc
  instance.decorate('myPluginFunc', (input) => {
    return input.toUpperCase()
  })

  done()
}

module.exports = fp(myPlugin, {
  fastify: '5.x',
  name: 'my-plugin' // this is used by fastify-plugin to derive the property name
})

打开 index.d.ts 并添加以下代码：

¥Open index.d.ts and add the following code:

import { FastifyPluginCallback } from 'fastify'

interface PluginOptions {
  //...
}

// Optionally, you can add any additional exports.
// Here we are exporting the decorator we added.
export interface myPluginFunc {
  (input: string): string
}

// Most importantly, use declaration merging to add the custom property to the Fastify type system
declare module 'fastify' {
  interface FastifyInstance {
    myPluginFunc: myPluginFunc
  }
}

// fastify-plugin automatically adds named export, so be sure to add also this type
// the variable name is derived from `options.name` property if `module.exports.myPlugin` is missing
export const myPlugin: FastifyPluginCallback<PluginOptions>

// fastify-plugin automatically adds `.default` property to the exported plugin. See the note below
export default myPlugin

注意：fastify-plugin v2.3.0 及更新版本，自动将 .default 属性和命名导出添加到导出的插件。请确保在你的输入中使用 export default 和 export const myPlugin，以提供最佳的开发者体验。有关完整示例，你可以查看 @fastify/swagger。

¥Note: fastify-plugin v2.3.0 and newer, automatically adds .default property and a named export to the exported plugin. Be sure to export default and export const myPlugin in your typings to provide the best developer experience. For a complete example you can check out @fastify/swagger.

完成这些文件后，该插件现在就可以被任何 TypeScript 项目使用了！

¥With those files completed, the plugin is now ready to be consumed by any TypeScript project!

Fastify 插件系统使开发者能够装饰 Fastify 实例和请求/响应实例。有关更多信息，请查看声明合并和通用继承上的这篇博客文章。

¥The Fastify plugin system enables developers to decorate the Fastify instance, and the request/reply instances. For more information check out this blog post on Declaration Merging and Generic Inheritance.

使用插件

¥Using a Plugin

在 TypeScript 中使用 Fastify 插件就像在 JavaScript 中使用插件一样简单。使用 import/from 导入插件，你就一切就绪了 - 但有一个例外用户应该注意。

¥Using a Fastify plugin in TypeScript is just as easy as using one in JavaScript. Import the plugin with import/from and you're all set -- except there is one exception users should be aware of.

Fastify 插件使用声明合并来修改现有的 Fastify 类型接口（查看前两个示例以了解更多详细信息）。声明合并不是很智能，这意味着如果插件的插件类型定义在 TypeScript 解释器的范围内，那么无论是否使用该插件，都将包含插件类型。这是使用 TypeScript 的一个不幸的限制，并且目前是不可避免的。

¥Fastify plugins use declaration merging to modify existing Fastify type interfaces (check out the previous two examples for more details). Declaration merging is not very smart, meaning if the plugin type definition for a plugin is within the scope of the TypeScript interpreter, then the plugin types will be included regardless of if the plugin is being used or not. This is an unfortunate limitation of using TypeScript and is unavoidable as of right now.

不过，有一些建议可以帮助改善这种体验：

¥However, there are a couple of suggestions to help improve this experience:

确保在 ESLint 中启用了 no-unused-vars 规则，并且任何导入的插件都实际正在加载。
¥Make sure the no-unused-vars rule is enabled in ESLint and any imported plugin are actually being loaded.
如果你已启用 @typescript-eslint/no-floating-promises，请仔细检查你的 ESLint 配置是否包含 allowForKnownSafePromises 属性，如 typescript-eslint no-floating-promises allowForKnownSafePromises documentation 中所述：
¥In case you've the @typescript-eslint/no-floating-promises enabled, please double-check that your ESLint configuration includes a allowForKnownSafePromises property as described on the typescript-eslint no-floating-promises allowForKnownSafePromises documentation:

{
  "rules": {
    "@typescript-eslint/no-floating-promises": ["error", {
      "allowForKnownSafePromises": [
        { "from": "package", "name": "FastifyInstance", "package": "fastify" },
        { "from": "package", "name": "FastifyReply", "package": "fastify" },
        { "from": "package", "name": "SafePromiseLike", "package": "fastify" },
      ]
    }]
  }
}

使用 depcheck 或 npm-check 等模块来验证插件依赖是否正在项目中的某个地方使用。
¥Use a module such as depcheck or npm-check to verify plugin dependencies are being used somewhere in your project.

请注意，使用 require 将无法正确加载类型定义，并可能导致类型错误。TypeScript 只能识别直接导入到代码中的类型，这意味着你可以使用 require inline 和 import on top。例如：

¥Note that using require will not load the type definitions properly and may cause type errors. TypeScript can only identify the types that are directly imported into code, which means that you can use require inline with import on top. For example:

import 'plugin' // here will trigger the type augmentation.

fastify.register(require('plugin'))

import plugin from 'plugin' //  here will trigger the type augmentation.

fastify.register(plugin)

或者甚至在 tsconfig 上进行显式配置

¥Or even explicit config on tsconfig

{
  "types": ["plugin"] // we force TypeScript to import the types
}

Vanilla JavaScript 中的代码完成

¥Code Completion In Vanilla JavaScript

Vanilla JavaScript 可以使用已发布的类型通过遵循 TypeScript JSDoc 参考来提供代码完成（例如 Intellisense）。

¥Vanilla JavaScript can use the published types to provide code completion (e.g. Intellisense) by following the TypeScript JSDoc Reference.

例如：

¥For example:

/**  @type {import('fastify').FastifyPluginAsync<{ optionA: boolean, optionB: string }>} */
module.exports = async function (fastify, { optionA, optionB }) {
  fastify.get('/look', () => 'at me');
}

API 类型系统文档

¥API Type System Documentation

本节详细介绍了 Fastify 3.x 版本中所有可用的类型

¥This section is a detailed account of all the types available to you in Fastify version 3.x

所有 http、https 和 http2 类型都是从 @types/node 推断出来的

¥All http, https, and http2 types are inferred from @types/node

泛型由其默认值及其约束值记录。阅读这些文章以获取有关 TypeScript 泛型的更多信息。

¥Generics are documented by their default value as well as their constraint value(s). Read these articles for more information on TypeScript generics.

如何导入

¥How to import

Fastify API 由 fastify() 方法提供支持。在 JavaScript 中，你可以使用 const fastify = require('fastify') 导入它。在 TypeScript 中，建议改用 import/from 语法，以便可以解析类型。Fastify 类型系统支持多种导入方法。

¥The Fastify API is powered by the fastify() method. In JavaScript you would import it using const fastify = require('fastify'). In TypeScript it is recommended to use the import/from syntax instead so types can be resolved. There are a couple supported import methods with the Fastify type system.

import fastify from 'fastify'

类型已解析，但无法使用点表示法访问
¥Types are resolved but not accessible using dot notation

示例：

¥Example:

import fastify from 'fastify'

const f = fastify()
f.listen({ port: 8080 }, () => { console.log('running') })

通过解构访问类型：

¥Gain access to types with destructuring:

import fastify, { FastifyInstance } from 'fastify'

const f: FastifyInstance = fastify()
f.listen({ port: 8080 }, () => { console.log('running') })

解构也适用于主要的 API 方法：

¥Destructuring also works for the main API method:

import { fastify, FastifyInstance } from 'fastify'

const f: FastifyInstance = fastify()
f.listen({ port: 8080 }, () => { console.log('running') })

import * as Fastify from 'fastify'
- 使用点表示法解析和访问类型
  ¥Types are resolved and accessible using dot notation
- 调用主要 Fastify API 方法需要稍微不同的语法（参见示例）
  ¥Calling the main Fastify API method requires a slightly different syntax (see example)
- 示例：
  ¥Example:
```
import * as Fastify from 'fastify'

const f: Fastify.FastifyInstance = Fastify.fastify()
f.listen({ port: 8080 }, () => { console.log('running') })
```
const fastify = require('fastify')
- 此语法有效，并将按预期导入 fastify；但是，类型不会被解析
  ¥This syntax is valid and will import fastify as expected; however, types will not be resolved
- 示例：
  ¥Example:
```
const fastify = require('fastify')

const f = fastify()
f.listen({ port: 8080 }, () => { console.log('running') })
```
- 支持解构并将正确解析类型
  ¥Destructuring is supported and will resolve types properly
```
const { fastify } = require('fastify')

const f = fastify()
f.listen({ port: 8080 }, () => { console.log('running') })
```

泛型

¥Generics

许多类型定义共享相同的通用参数；它们都在本节中详细记录。

¥Many type definitions share the same generic parameters; they are all documented, in detail, within this section.

大多数定义依赖于 @types/node 模块 http、https 和 http2

¥Most definitions depend on @types/node modules http, https, and http2

RawServer

底层 Node.js 服务器类型

¥Underlying Node.js server type

默认：http.Server

¥Default: http.Server

限制条件：http.Server, https.Server, http2.Http2Server, http2.Http2SecureServer

¥Constraints: http.Server, https.Server, http2.Http2Server, http2.Http2SecureServer

强制通用参数：RawRequest, RawReply

¥Enforces generic parameters: RawRequest, RawReply

RawRequest

底层 Node.js 请求类型

¥Underlying Node.js request type

默认：RawRequestDefaultExpression

¥Default: RawRequestDefaultExpression

限制条件：http.IncomingMessage, http2.Http2ServerRequest

¥Constraints: http.IncomingMessage, http2.Http2ServerRequest

执行者：RawServer

¥Enforced by: RawServer

RawReply

底层 Node.js 响应类型

¥Underlying Node.js response type

默认：RawReplyDefaultExpression

¥Default: RawReplyDefaultExpression

限制条件：http.ServerResponse, http2.Http2ServerResponse

¥Constraints: http.ServerResponse, http2.Http2ServerResponse

执行者：RawServer

¥Enforced by: RawServer

Logger

Fastify 日志实用程序

¥Fastify logging utility

默认：FastifyLoggerOptions

¥Default: FastifyLoggerOptions

执行者：RawServer

¥Enforced by: RawServer

RawBody

内容类型解析器方法的通用参数。

¥A generic parameter for the content-type-parser methods.

限制条件：string | Buffer

¥Constraints: string | Buffer

TypeScript

TypeScript​

通过实例学习​

入门​

使用泛型​

JSON 结构​

Fastify 类型提供商​

TypeBox​

json-schema-to-typescript​

json-schema-to-ts​

插件​

创建 TypeScript Fastify 插件​

为 Fastify 插件创建类型定义​

使用插件​

Vanilla JavaScript 中的代码完成​

API 类型系统文档​

如何导入​

泛型​

RawServer​

RawRequest​

RawReply​

Logger​

RawBody​

Fastify​

fastify< RawRequest, RawReply, Logger>(opts?: FastifyServerOptions): FastifyInstance​

示例 1：标准 HTTP 服务器​

示例 2：HTTPS 服务器​

示例 3：HTTP2 服务器​

示例 4：扩展 HTTP 服务器​

示例 5：指定日志器类型​

fastify.HTTPMethods​

fastify.RawServerBase​

fastify.RawServerDefault​

fastify.FastifyServerOptions< RawServer, Logger>​

fastify.FastifyInstance< RawServer, RawRequest, RequestGeneric, Logger>​

请求​

fastify.FastifyRequest< RequestGeneric, RawServer, RawRequest>​

示例​

fastify.RequestGenericInterface​

fastify.RawRequestDefaultExpression\<RawServer>​

响应​

fastify.FastifyReply<RequestGeneric, RawServer, RawRequest, RawReply, ContextConfig>​

示例​

fastify.RawReplyDefaultExpression< RawServer>​

Plugin​

fastify.FastifyPluginCallback< Options>​

fastify.FastifyPluginAsync< Options>​

fastify.FastifyPlugin< Options>​

fastify.FastifyPluginOptions​

注册​

fastify.FastifyRegister(plugin: [FastifyPluginCallback][FastifyPluginCallback], opts: [FastifyRegisterOptions][FastifyRegisterOptions])​

fastify.FastifyRegister(plugin: [FastifyPluginAsync][FastifyPluginAsync], opts: [FastifyRegisterOptions][FastifyRegisterOptions])​

fastify.FastifyRegister(plugin: [FastifyPlugin][FastifyPlugin], opts: [FastifyRegisterOptions][FastifyRegisterOptions])​

fastify.FastifyRegisterOptions​

Logger​

fastify.FastifyLoggerOptions< RawServer, RawRequest, RawReply>​

fastify.FastifyLogFn​

fastify.LogLevel​

Context​

fastify.FastifyRequestContext​

fastify.FastifyReplyContext​

Routing​

fastify.RouteHandlerMethod< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>​

fastify.RouteOptions< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>​

fastify.RouteShorthandMethod< RawServer, RawRequest, RawReply>​

fastify.RouteShorthandOptions< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>​

fastify.RouteShorthandOptionsWithHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>​

Parsers​

RawBody​

fastify.FastifyBodyParser< RawBody, RawServer, RawRequest>​

fastify.FastifyContentTypeParser< RawServer, RawRequest>​

fastify.AddContentTypeParser< RawServer, RawRequest>​

fastify.hasContentTypeParser​

错误​

fastify.FastifyError​

fastify.ValidationResult​

钩子​

fastify.onRequestHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void​

fastify.preParsingHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void​

fastify.preValidationHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void​

TypeScript

通过实例学习

入门

使用泛型

JSON 结构

Fastify 类型提供商

TypeBox

json-schema-to-typescript

json-schema-to-ts

插件

创建 TypeScript Fastify 插件

为 Fastify 插件创建类型定义

使用插件

Vanilla JavaScript 中的代码完成

API 类型系统文档

如何导入

泛型

RawServer

RawRequest

RawReply

Logger

RawBody

Fastify

fastify< RawRequest, RawReply, Logger>(opts?: FastifyServerOptions): FastifyInstance

示例 1：标准 HTTP 服务器

示例 2：HTTPS 服务器

示例 3：HTTP2 服务器

示例 4：扩展 HTTP 服务器

示例 5：指定日志器类型

fastify.HTTPMethods

fastify.RawServerBase

fastify.RawServerDefault

fastify.FastifyServerOptions< RawServer, Logger>

fastify.FastifyInstance< RawServer, RawRequest, RequestGeneric, Logger>

请求

fastify.FastifyRequest< RequestGeneric, RawServer, RawRequest>

示例

fastify.RequestGenericInterface

fastify.RawRequestDefaultExpression\<RawServer>

响应

fastify.FastifyReply<RequestGeneric, RawServer, RawRequest, RawReply, ContextConfig>

示例

fastify.RawReplyDefaultExpression< RawServer>

Plugin

fastify.FastifyPluginCallback< Options>

fastify.FastifyPluginAsync< Options>

fastify.FastifyPlugin< Options>

fastify.FastifyPluginOptions

注册

fastify.FastifyRegister(plugin: [FastifyPluginCallback][FastifyPluginCallback], opts: [FastifyRegisterOptions][FastifyRegisterOptions])

fastify.FastifyRegister(plugin: [FastifyPluginAsync][FastifyPluginAsync], opts: [FastifyRegisterOptions][FastifyRegisterOptions])

fastify.FastifyRegister(plugin: [FastifyPlugin][FastifyPlugin], opts: [FastifyRegisterOptions][FastifyRegisterOptions])

fastify.FastifyRegisterOptions

Logger

fastify.FastifyLoggerOptions< RawServer, RawRequest, RawReply>

fastify.FastifyLogFn

fastify.LogLevel

Context

fastify.FastifyRequestContext

fastify.FastifyReplyContext

Routing

fastify.RouteHandlerMethod< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>

fastify.RouteOptions< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>

fastify.RouteShorthandMethod< RawServer, RawRequest, RawReply>

fastify.RouteShorthandOptions< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>

fastify.RouteShorthandOptionsWithHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>

Parsers

RawBody

fastify.FastifyBodyParser< RawBody, RawServer, RawRequest>

fastify.FastifyContentTypeParser< RawServer, RawRequest>

fastify.AddContentTypeParser< RawServer, RawRequest>

fastify.hasContentTypeParser

错误

fastify.FastifyError

fastify.ValidationResult

钩子

fastify.onRequestHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void

fastify.preParsingHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void

fastify.preValidationHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void

fastify.preHandlerHookHandler< RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>(request: FastifyRequest, reply: FastifyReply, done: (err?: FastifyError) => void): Promise\<unknown> | void