fastify使用TypeScript
TypeScript
TypeScript
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.
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!
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.
🚨 Don't forget to install @types/node
Learn By Example
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
This example will get you up and running with Fastify and TypeScript. It results in a blank http Fastify server.
- 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
- Add the following lines to the
"scripts"section of thepackage.json:
{
"scripts": {
"build": "tsc -p tsconfig.json",
"start": "node index.js"
}
}
- Initialize a TypeScript configuration file:
npx tsc --init
or use one of the recommended ones.
Note: Set target property in tsconfig.json to es2017 or greater to avoid FastifyDeprecation warning.
- Create an
index.tsfile - 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}`)
}) - Run
npm run build- this will compileindex.tsintoindex.jswhich can be executed using Node.js. If you run into any errors please open an issue in fastify/help - Run
npm run startto run the Fastify server - You should see
Server listening at http://127.0.0.1:8080in your console - Try out your server using
curl localhost:8080/ping, it should returnpong🏓
🎉 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!
For more examples on initializing Fastify with TypeScript (such as enabling HTTP2) check out the detailed API section here
Using Generics
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.
-
If you did not complete the previous example, follow steps 1-4 to get set up.
-
Inside
index.ts, define three interfacesIQuerystring,IHeadersandIReply:interface IQuerystring {
username: string;
password: string;
}
interface IHeaders {
'h-Custom': string;
}
interface IReply {
200: { success: boolean };
302: { url: string };
'4xx': { error: string };
} -
Using the three interfaces, define a new API route and pass them as generics. The shorthand route methods (i.e.
.get) accept a generic objectRouteGenericInterfacecontaining five named properties:Body,Querystring,Params,HeadersandReply. The interfacesBody,Querystring,ParamsandHeaderswill be passed down through the route method into the route method handlerrequestinstance and theReplyinterface to thereplyinstance.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!`
}) -
Build and run the server code with
npm run buildandnpm run start -
Query the API
curl localhost:8080/auth?username=admin&password=Password123!And it should return back
logged in! -
But wait there's more! The generic interfaces are also available inside route level hook methods. Modify the previous route by adding a
preValidationhook: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!`
}) -
Build and run and query with the
usernamequery string option set to anything other thanadmin. The API should now return a HTTP 500 error{"statusCode":500,"error":"Internal Server Error","message":"Must be admin"}
🎉 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 Schema
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 Type Providers
Fastify offers two packages wrapping json-schema-to-ts and typebox:
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.
Below is how to setup schema validation using the typebox, json-schema-to-typescript, and json-schema-to-ts packages without type providers.
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.
When you want to use it for validation of some payload in a fastify route you can do it as follows:
-
Install
typeboxin your project.npm i @sinclair/typebox -
Define the schema you need with
Typeand create the respective type withStatic.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
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!
-
If you did not complete the 'Getting Started' example, go back and follow steps 1-4 first.
-
Install the
json-schema-to-typescriptmodule:npm i -D json-schema-to-typescript -
Create a new folder called
schemasand add two filesheaders.jsonandquerystring.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"]
} -
Add a
compile-schemasscript to the package.json:
{
"scripts": {
"compile-schemas": "json2ts -i schemas -o types"
}
}
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 `