Fastify 是一个运行在 Node.js 上的 Web 框架,注重开发体验和低开支(overhead),提供完整的 Web 框架特性,但也保有良好的性能,性能要比 Express 框架还好上不少。Fastify 支持 TypeScript 语言,笔者建议使用 TypeScript 来开发 Fastify 应用程序。然而,要创建出一个完整 TypeScript 项目是一件繁琐的事情,我们会需要安装多种套件及工具并撰写设置档和代码,来使项目能符合我们自己的开发习惯。在这篇文章中,笔者要分享自己创建 TypeScript 项目并使用 Fastify 框架来开发 Web 服务的方式。
创建使用 Fastify 框架的 TypeScript 项目
创建 TypeScript 应用程序项目
请参考以下链接的文章来创建 TypeScript 应用程序项目,要加入 Jest 测试框架。
加入 Fastify 和其它会用到的 Node.js 套件
在项目根目录中运行以下指令来安装套件:
pnpm i fastify@^5 glob pino pino-pretty ts-essentials
fastify 套件即是 Fastify 框架的核心套件;glob 是方便用来匹配文件路径的套件;pino 是输出日志(log)的套件,笔者习惯自行控制日志的输出,而不会让 Fastify 框架本身输出日志;pino-pretty 是用来美化日志输出的套件,可以加颜色上去;ts-essentials 套件提供了很多方便的类型,这篇文章会用到其中的 DeepReadonly。
接着按照以下的方式修改 package.json 中的 start:dev 脚本,打开 Node.js 的 inspect 的功能,方便在任何时候于开发环境将我们的 Web 服务附加至 JavaScript 的 Debugger 中。
{
"scripts": {
...
"start:dev": "NODE_ENV=development nodemon --signal SIGINT --exec \"node --enable-source-maps --inspect=0.0.0.0:9229 --import ./ts-node.register.mjs src/app.ts\" -e 'ts,json'",
...
}
}
如果您有使用 run-with-node-env 套件,请自行将 NODE_ENV=development 改为 run-with-node-env development。
另外,之所以要让 nodemon 指令加上 --signal SIGINT 参数是为了要解决重启失败而导致连接端口占用的问题,并且也可以让之后要介绍的「优雅的关机」的机制能正常作用于当文件发生变化使 nodemon 自动重启时。SIGINT 即在终端机下对运行中的程序按下 Ctrl + c 时所发出的中断信号。
创建基本的目录和代码文件
目录
首先创建出 src/schemas、src/controllers、src/routes 这三个目录。
Linux 或是 macOS 环境可以直接运行以下指令来创建:
src/schemas 目录用来放置各种数据的 JSON Schema 和相关代码;src/controllers 目录用来放置处理 HTTP 请求的代码,即 Fastify 的路由处理程序(handler);src/routes 目录用来放置注册路由的代码,并对每个路由设置 JSON Schema。
Logger
然后要创建 src/logger.ts,内容如下:
import cluster from "node:cluster";
import { pino } from "pino";
let logger;
let base: Record<string, unknown> | undefined = undefined;
if (cluster.isWorker) {
base = { pid: process.pid };
}
switch (process.env.NODE_ENV) {
case "production":
logger = pino({
level: process.env.LOG_LEVEL ?? "info",
base,
transport: {
target: "pino-pretty",
options: { translateTime: "SYS:standard" },
},
});
break;
case "test":
logger = pino({
level: process.env.LOG_LEVEL ?? "warn",
base,
transport: { target: "pino-pretty", options: { sync: true } },
});
break;
default:
logger = pino({
level: process.env.LOG_LEVEL ?? "debug",
base,
transport: { target: "pino-pretty" },
});
break;
}
export const Logger = logger;
这个 src/logger.ts 可用来代替 console.log 的用途。日志等级由低到高分别为 trace、debug、info、warn、error、fatal。借由 LOG_LEVEL 环境变量可以设置要输出的日志的最低等级,而 NODE_ENV 环境变量的值则会影响到预设输出的日志的最低等级。translateTime: "SYS:standard" 可以让日志除了时间外还有日期,方便日后追踪。不过每个人看日志有不同的习惯,您可以根据自己的喜好来修改这个文件。
路由
笔者将注册路由的代码都规划到 src/routes 目录下,文件名格式必须为 xxx.route.ts,并利用 glob 套件和 import() 将文件动态引入进来。且为了进一步限制 xxx.route.ts 的撰写方式,确保动态引入不容易出问题,又撰写了 Route 界面,让 xxx.route.ts 暴露(export)的默认值得是 Route 类型才行。
Route 界面写在 src/routes/route.ts 文件中,内容如下:
export interface Route {
readonly setRoutes: (app: import("fastify").FastifyInstance) => void;
}
读取 xxx.route.ts 的程序写在 src/app.routes.ts 文件中,内容如下:
import { dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { globSync } from "glob";
const __dirname = dirname(fileURLToPath(import.meta.url));
export const registerRoutes = async (
app: import("fastify").FastifyInstance,
): Promise<void> => {
const filePaths = globSync("routes/**/*.route.@(js|ts)", { cwd: __dirname });
for (const filePath of filePaths) {
const requirePath = filePath.substring(0, filePath.length - 3);
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
const route = (await import(`./${requirePath}.js`)).default as import("./routes/route.js").Route;
void app.register((app, _opts, done) => {
route.setRoutes(app);
done();
});
}
};
Fastify 实体
创建 Fastify 实体的程序写在 src/app.fastify.ts 文件中,内容如下:
import type { FastifyError } from "fastify";
import { fastify } from "fastify";
import type { FastifySchemaValidationError } from "fastify/types/schema.js";
import { registerRoutes } from "./app.routes.js";
import { Logger } from "./logger.js";
const app = fastify({ routerOptions: { ignoreTrailingSlash: true } });
app.setErrorHandler<FastifyError>((error, _req, res) => {
Logger.trace(error);
const statusCode = error.statusCode ?? 500;
let validation: {
context: string;
errors: FastifySchemaValidationError[];
} | undefined;
if (statusCode >= 500 && statusCode < 600) {
Logger.error(error.stack);
} else if (statusCode === 415) {
Logger.warn(error.stack);
} else if (typeof error.validation !== "undefined") {
error.validation.forEach((e) => {
delete e.message;
});
validation = {
context:
(error as unknown as { validationContext: string })
.validationContext,
errors: error.validation,
};
}
void res.code(statusCode);
void res.send({ validation });
});
app.setNotFoundHandler((_req, res) => {
void res.status(404);
void res.send({});
});
app.addHook("onResponse", (req, res, done) => {
const method = req.method;
let realIP: string | null;
let ip = req.headers["x-real-ip"];
if (typeof ip === "undefined") {
ip = req.headers["x-forwarded-for"];
if (typeof ip === "undefined") {
realIP = req.socket.remoteAddress ?? null;
} else if (Array.isArray(ip)) {
realIP = ip[0];
} else {
const ips = ip.split(",");
realIP = ips[0];
}
} else if (Array.isArray(ip)) {
realIP = ip[0];
} else {
realIP = ip;
}
const url = req.raw.url ?? null; // should not be null
const userAgent = req.headers["user-agent"] ?? "";
const statusCode = res.statusCode;
Logger.info(`${method} ${url} ${statusCode} - ${userAgent} ${realIP}`);
done();
});
await registerRoutes(app);
export default app;
在这个文件中,设置了 Fastify 对于被抛出(throw)的错误的处理方式。错误时会回应一个空的 JSON 对象,不过如果是由 Fastify schema 所产生的数据验证错误,则详细错误信息会被放进这个 JSON 对象的 validation 字段中。
另外在这个文件中,还设计了在回应的时候要输出的日志格式。实际输出内容看起来会像是以下这样:
[13:34:41.345] INFO: GET /10 404 - Mozilla/5.0 (X11; Linux x86_64; rv:105.0) Gecko/20100101 Firefox/105.0 127.0.0.1
这个文件只会创建出 Fastify 实体,并不会进行 TCP 等 Socket 的监听。在撰写测试的时候应直接引入这个文件,并使用 Fastify 实体自带的 inject 方法来发送请求,就不必透过 TCP 等 Socket 连接的方式来发送数据,稍后会介绍要怎么撰写 Fastify Web 服务的测试。
程序进入点
将该有的模块都备齐后,就可以开始撰写程序进入点了。我们的 TypeScript 应用程序项目的程序进入点是 src/app.ts,内容如下:
import cluster from "node:cluster";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import app from "./app.fastify.js";
import { Logger } from "./logger.js";
const PORT = parseInt(process.env.PORT ?? "3000");
let instanceNumber = parseInt(process.env.INSTANCE_NUMBER ?? "0");
if (process.env.NODE_ENV === "production") {
if (instanceNumber === 0) {
instanceNumber = os.cpus().length;
}
}
if (instanceNumber > 1 && cluster.isPrimary) {
if (process.env.SOCKET_PATH) {
const socketPath = path.resolve(process.env.SOCKET_PATH);
let stat;
try {
stat = fs.statSync(socketPath);
} catch (_err) {
// do nothing
}
if (stat) {
if (stat.isSocket()) {
try {
fs.unlinkSync(socketPath);
} catch (err) {
Logger.error(err);
}
} else {
Logger.error(
`${socketPath} exists but it is not a socket file`,
);
process.exit(1);
}
}
}
const pids = new Set<number>();
for (let i = 0; i < instanceNumber; ++i) {
const worker = cluster.fork();
if (typeof worker.process.pid !== "undefined") {
const pid = worker.process.pid;
pids.add(pid);
worker.on("exit", () => {
pids.delete(pid);
});
}
}
const signals: NodeJS.Signals[] = [
"SIGINT",
"SIGTERM",
"SIGHUP",
"SIGUSR1",
"SIGUSR2",
];
for (const signal of signals) {
process.on(signal, () => {
for (const pid of pids) {
try {
process.kill(pid, signal);
} catch {
// do nothing
}
}
});
}
} else if (process.env.SOCKET_PATH) {
const socketPath = path.resolve(process.env.SOCKET_PATH);
app.listen({ path: socketPath }, (err) => {
if (err) {
Logger.error(err);
return;
}
fs.chmodSync(socketPath, 0o777);
Logger.info(`HTTP server started at ${socketPath}`);
});
} else {
app.listen({ host: "0.0.0.0", port: PORT }, (err) => {
if (err) {
Logger.error(err);
return;
}
Logger.info(`HTTP server started at http://localhost:${PORT}`);
});
}
程序进入的时候,会先依据 INSTANCE_NUMBER 环境变量来决定要 fork 多少进程出来,进程数量愈多,服务的吞吐量就愈大。如果没有设置 INSTANCE_NUMBER 环境变量,在生产环境下,会使用等同于逻辑内核数量的进程来启动服务;在非生产环境下,则只会使用一个进程来启动服务。在启动服务之前,会判断 SOCKET_PATH 环境变量有没有设置,有的话就会启动 UDS (Unix Domain Socket)服务,没有的话就是启动 TCP 服务(监听连接端口 3000)。
范例程序
以下是 src/controllers 目录底下的程序范例。
import type { FastifyReply, FastifyRequest } from "fastify";
export const ExampleController = {
hello: (
req: FastifyRequest<{ Querystring: { name?: string } }>,
res: FastifyReply,
): void => {
void res.send(`Hello, ${req.query.name ?? "stranger"}!`);
},
helloPost: (
req: FastifyRequest<{ Body?: { name?: string } }>,
res: FastifyReply,
): void => {
void res.send(`Hello, ${req.body?.name ?? "stranger"}!`);
},
};
这就是一个 Hello World 程序,可以在请求中传入一个名称来设置回传时要打招呼的对象。hello 会去读取请求网址中的 Query 部份,helloPost 则是会去读取 HTTP 请求中的 Body。
接着在 src/schemas 目录底下定义数据的 JSON Schema。
import type { DeepReadonly } from "ts-essentials";
const helloSchema = {
type: "object",
nullable: true,
properties: { name: { type: "string" } },
};
export const HelloSchema: DeepReadonly<typeof helloSchema> = helloSchema;
在暴露的时候利用 DeepReadonly 类型将 JSON Schema 包裹起来,避免在其它地方被意外修改。
最后是在 src/routes 目录底下创建路由。
import type { FastifyInstance } from "fastify";
import { ExampleController } from "../controllers/example.controller.js";
import { HelloSchema } from "../schemas/example.schema.js";
import type { Route } from "./route.js";
const ExampleRoute: Route = {
setRoutes(app: FastifyInstance): void {
app.get(
"/hello",
{ schema: { querystring: HelloSchema } },
ExampleController.hello,
);
app.post(
"/hello",
{ schema: { body: HelloSchema } },
ExampleController.helloPost,
);
},
};
// eslint-disable-next-line import/no-unused-modules
export default ExampleRoute;
至此范例程序就可以动作了。要测试它的话,我们可以再撰写以下的测试程序:
import app from "../src/app.fastify.js";
describe("say hello", () => {
it("GET /hello", async () => {
const response = await app.inject({
method: "GET",
url: "/hello",
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, stranger!");
});
it("GET /hello?name=David", async () => {
const response = await app.inject({
method: "GET",
url: "/hello",
query: { name: "David" },
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, David!");
});
it("POST /hello", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, stranger!");
});
it("POST /hello, name='David'", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
payload: { name: "David" },
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, David!");
});
it("POST /hello (body is not a JSON object)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
headers: { "content-type": "application/json; charset=utf-8" },
payload: "\"David\"",
});
expect(response.statusCode).toBe(400);
const body = response.json<
{
validation: {
context: string;
errors: { instancePath: string; keyword: string }[];
};
}
>();
expect(body.validation.context).toBe("body");
expect(body.validation.errors[0]).toMatchObject({
instancePath: "",
keyword: "type",
});
});
it("POST /hello (body is an incorrect JSON)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
headers: { "content-type": "application/json; charset=utf-8" },
payload: "{name: \"David\"}",
});
expect(response.statusCode).toBe(400);
expect(response.json()).toEqual({});
});
it("POST /hello, name={} (name is not a string)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
payload: { name: {} },
});
expect(response.statusCode).toBe(400);
const body = response.json<
{
validation: {
context: string;
errors: { instancePath: string; keyword: string }[];
};
}
>();
expect(body.validation.context).toBe("body");
expect(body.validation.errors[0]).toMatchObject({
instancePath: "/name",
keyword: "type",
});
});
});
以上测试中,有个特别需要注意的地方是,虽然我们有用 JSON Schema 设置请求中传来的数据必须是一个 object,但当请求中的 Body 不是一个正确的 JSON 格式时,错误处理程序接到的错误是一个 code 为 FST_ERR_CTP_INVALID_JSON_BODY 的 FastifyError。
错误代码
一个错误回应中最好使用错误代码而不是罐头式的错误消息(所以我们之前并未让 Fastify 在处理错误时回应 Error 实体的 message 字段),这样前端在串接后端 API 的时候才能比较方便且有效率地处理发生错误时的后续行为。由于 Fastify 有内置基于 JSON Schema 的数据验证机制,在数据不符合 JSON Schema 所定义的格式的时候会自动抛出错误,所以我们要有个将这些错误自动转换成错误代码的机制才行。
运用 TypeScript 提供的枚举(Enum),我们可以自行定义枚举的变体名称,并让变体的数值由 TypeScript 自动产生出来,十分方便。在 Fastify 内置的 JSON Schema 数据验证功能所产生的错误信息中,可以找到 validationContext 和 schemaPath 字段,我们可以利用它们来组成变体名称,大致上是将 validationContext 和 schemaPath(省略开头字符 #,以及分隔字符 /,还有其中的 properties 和 items)串接在一起。至于名称的格式可以用 camelcase 套件来做范式,大小写变化使用帕斯卡命名法(Pascal Case),即:Word1Word2。
首先运行以下指令来安装 camelcase 套件:
接着创建 src/errors 目录。src/errors 目录用来放置各种错误的枚举和相关代码。如果可以的话,建议把所有错误的枚举独立成一个 TypeScript 函数库项目,如此后端便能直接与前端共用同一个错误代码枚举,前端就不用担心会对应到不对的错误代码啦!
然后要创建 src/errors/index.ts 文件,内容如下:
import type { FastifyRequest, preParsingHookHandler } from "fastify";
interface ErrorCodeInterface<T> {
errorCode?: T;
}
export type ErrorCode<T = Record<string, number>> = Readonly<
ErrorCodeInterface<T>
>;
/**
* Add `errorCodeEnum` to `FastifyRequest` instances (`{errorCode: errorCodeEnum}`) in order to make this route errorCode-able.
*
* @param errorCodeEnum should be an enum whose variants' values are all integers
*/
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
export const createErrorCodePreParsingHook = <T>(errorCodeEnum: T): preParsingHookHandler => (req: FastifyRequest & ErrorCodeInterface<T>, _res, _payload, done) => {
req.errorCode = errorCodeEnum;
done();
};
// APIError
type Errors = number[];
const DEFAULT_STATUS_CODE = 500;
export class APIError extends Error {
readonly statusCode: number;
readonly errors: Readonly<Errors>;
readonly extra: unknown;
constructor(errors: Errors, extra?: unknown);
constructor(statusCode: number, errors: Errors, extra?: unknown);
constructor(
statusCodeOrErrors: number | Errors,
errors?: unknown,
extra?: unknown,
) {
if (typeof statusCodeOrErrors === "number") {
super("API failed.");
this.statusCode = statusCodeOrErrors;
this.errors = errors as Errors;
this.extra = extra;
} else {
super("API failed.");
this.statusCode = DEFAULT_STATUS_CODE;
this.extra = errors;
this.errors = statusCodeOrErrors;
}
this.name = "APIError";
}
}
将 src/app.fastify.ts 文件修改如下:
import camelCase from "camelcase";
import type { FastifyError, FastifyRequest } from "fastify";
...
import type { ErrorCode } from "./errors/index.js";
import { APIError } from "./errors/index.js";
...
app.setErrorHandler<FastifyError | APIError>((error, req: FastifyRequest & ErrorCode, res) => {
Logger.trace(error);
if (error instanceof APIError) {
void res.code(error.statusCode);
void res.send({
errors: error.errors,
extra: error.extra,
});
} else {
const statusCode = error.statusCode ?? 500;
let validation: {
context: string;
errors: FastifySchemaValidationError[];
} | undefined;
let errors: number[] | undefined;
if (statusCode >= 500 && statusCode < 600) {
Logger.error(error.stack);
} else if (statusCode === 415) {
Logger.warn(error.stack);
} else if (typeof error.validation !== "undefined") {
const context = (error as unknown as { validationContext: string }).validationContext;
if (typeof req.errorCode !== "undefined") {
errors = [];
for (const v of error.validation) {
const variantNameTokens = [context, ...v.schemaPath.substring(1).split("/").filter((e) => e !== "properties" && e !== "items")];
switch (v.keyword) {
case "required":
variantNameTokens.splice(variantNameTokens.length - 1, 0, v.params.missingProperty as string);
break;
}
const variantName = camelCase(variantNameTokens, { pascalCase: true, preserveConsecutiveUppercase: true });
if (Object.hasOwn(req.errorCode, variantName)) {
errors.push(req.errorCode[variantName]);
} else {
Logger.warn(`[ErrorCode] cannot find the variant named ${JSON.stringify(variantName)}`);
}
}
} else {
error.validation.forEach((e) => {
delete e.message;
});
validation = {
context,
errors: error.validation,
};
}
} else if (error.code === "FST_ERR_CTP_INVALID_JSON_BODY") {
if (typeof req.errorCode !== "undefined") {
errors = [];
const variantName = "BodyType";
if (Object.hasOwn(req.errorCode, variantName)) {
errors.push(req.errorCode[variantName]);
} else {
Logger.warn(`[ErrorCode] cannot find the variant named ${JSON.stringify(variantName)}`);
}
}
}
void res.code(statusCode);
void res.send({
errors,
validation,
});
}
});
...
以上程序有个特别需要提及的地方是,若有使用错误代码机制且遇到 code 为 FST_ERR_CTP_INVALID_JSON_BODY 的错误时,会去使用 BodyType 这个变体名称。
范例程序
在 src/errors 目录底下定义错误代码的枚举。
export enum ExampleErrorCode {
BodyType = 1,
BodyNameType,
NameCannotBeJohn = 100,
}
在注册路由的时候使用 createErrorCodePreParsingHook 函数透过传入一个错误代码的枚举来创建出 preParsingHook,以便让错误处理程序知道可以用错误代码机制来处理错误。我们要修改 src/routes/example.route.ts 文件,内容如下:
import type { FastifyInstance, RouteHandlerMethod } from "fastify";
import { ExampleController } from "../controllers/example.controller.js";
import { ExampleErrorCode } from "../errors/example.error.js";
import { createErrorCodePreParsingHook } from "../errors/index.js";
import { HelloSchema } from "../schemas/example.schema.js";
import type { Route } from "./route.js";
const ExampleRoute: Route = {
setRoutes(app: FastifyInstance): void {
app.get("/hello", {
preParsing: createErrorCodePreParsingHook(ExampleErrorCode),
schema: { querystring: HelloSchema },
}, ExampleController.hello as RouteHandlerMethod);
app.post("/hello", {
preParsing: createErrorCodePreParsingHook(ExampleErrorCode),
schema: { body: HelloSchema },
}, ExampleController.helloPost as RouteHandlerMethod);
},
};
// eslint-disable-next-line import/no-unused-modules
export default ExampleRoute;
接着加入不跟 John 打招呼的功能。修改 src/controllers/example.controller.ts 文件,内容如下:
import type { FastifyReply, FastifyRequest } from "fastify";
import { ExampleErrorCode } from "../errors/example.error.js";
import { APIError } from "../errors/index.js";
export const ExampleController = {
hello: (
req: FastifyRequest<{ Querystring: { name?: string } }>,
res: FastifyReply,
): void => {
if (req.query.name === "John") {
throw new APIError(400, [ExampleErrorCode.NameCannotBeJohn]);
}
void res.send(`Hello, ${req.query.name ?? "stranger"}!`);
},
helloPost: (
req: FastifyRequest<{ Body?: { name?: string } }>,
res: FastifyReply,
): void => {
if (req.body?.name === "John") {
throw new APIError(400, [ExampleErrorCode.NameCannotBeJohn]);
}
void res.send(`Hello, ${req.body?.name ?? "stranger"}!`);
},
};
修改测试程序。
import app from "../src/app.fastify.js";
import { ExampleErrorCode } from "../src/errors/example.error.js";
describe("say hello", () => {
it("GET /hello", async () => {
const response = await app.inject({
method: "GET",
url: "/hello",
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, stranger!");
});
it("GET /hello?name=David", async () => {
const response = await app.inject({
method: "GET",
url: "/hello",
query: { name: "David" },
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, David!");
});
it("GET /hello?name=John", async () => {
const response = await app.inject({
method: "GET",
url: "/hello",
query: { name: "John" },
});
expect(response.statusCode).toBe(400);
expect(response.json<{ errors: number[] }>().errors).toEqual([ExampleErrorCode.NameCannotBeJohn]);
});
it("POST /hello", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, stranger!");
});
it("POST /hello, name='David'", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
payload: { name: "David" },
});
expect(response.statusCode).toBe(200);
expect(response.body).toBe("Hello, David!");
});
it("POST /hello, name='John' (errorCode = ExampleErrorCode.NameCannotBeJohn)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
payload: { name: "John" },
});
expect(response.statusCode).toBe(400);
expect(response.json<{ errors: number[] }>().errors).toEqual([ExampleErrorCode.NameCannotBeJohn]);
});
it("POST /hello (errorCode = ExampleErrorCode.BodyType, body is not a JSON object)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
headers: { "content-type": "application/json; charset=utf-8" },
payload: "\"David\"",
});
expect(response.statusCode).toBe(400);
expect(response.json<{ errors: number[] }>().errors).toEqual([ExampleErrorCode.BodyType]);
});
it("POST /hello (errorCode = ExampleErrorCode.BodyType, body is an incorrect JSON)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
headers: { "content-type": "application/json; charset=utf-8" },
payload: "{name: \"David\"}",
});
expect(response.statusCode).toBe(400);
expect(response.json<{ errors: number[] }>().errors).toEqual([ExampleErrorCode.BodyType]);
});
it("POST /hello, name={} (errorCode = ExampleErrorCode.BodyNameType, name is not a string)", async () => {
const response = await app.inject({
method: "POST",
url: "/hello",
payload: { name: {} },
});
expect(response.statusCode).toBe(400);
expect(response.json<{ errors: number[] }>().errors).toEqual([ExampleErrorCode.BodyNameType]);
});
});
插件
依照自己的需求来决定要安装哪些 Fastify 的插件。以下介绍几个基本的插件的安装方式。
CORS (Cross-Origin Resource Sharing)
用以下指令安装所需的套件:
修改 src/app.fastify.ts 以激活 CORS。如下:
...
import cors from "@fastify/cors";
...
void app.register(cors, {
maxAge: 3600,
origin: true,
credentials: true,
methods: [
"GET", "HEAD", "POST", "DELETE", "PUT", "PATCH",
],
});
...
methods 若不设置,预设为 GET,HEAD,POST。
x-www-form-urlencoded
用以下指令安装所需的套件:
修改 src/app.fastify.ts 以支持 application/x-www-form-urlencoded 类型的请求 Body。如下:
...
import formbody from "@fastify/formbody";
...
void app.register(formbody);
...
form-data
用以下指令安装所需的套件:
修改 src/app.fastify.ts 以支持 multipart/form-data 类型的请求 Body。如下:
...
import multipart from "@fastify/multipart";
...
void app.register(multipart);
...
详细用法可以参考 @fastify/multipart 的文档说明。笔者觉得这个插件跟 JSON Schema 没有集成得很好,还待改进。
静态文件
用以下指令安装所需的套件:
修改 src/app.fastify.ts 让 Fastify 可以提供静态文件。如下:
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
...
import { fastifyStatic } from "@fastify/static";
...
const __dirname = dirname(fileURLToPath(import.meta.url));
void app.register(fastifyStatic, { root: resolve(__dirname, "../public"), prefix: "/static" });
...
以上设置可以让 GET /static/... 的请求去对应到程序项目根目录下的 public 目录中的文件。
优雅的关机(Graceful Shutdown)
我们通常会希望当 Web 服务在被停止之前能够好好地把目前正在处理的请求全都处理完后再停止,以避免脏数据(Dirty Data)的产生。
用以下指令安装所需的套件:
修改 src/app.fastify.ts 让 Fastify 可以在被停止前等待手上的工作先处理完毕。如下:
...
import fastifyGracefulShutdown from "fastify-graceful-shutdown";
...
void app.register(fastifyGracefulShutdown);
app.after(() => {
app.gracefulShutdown(async (signal) => {
Logger.info(`Received ${signal}. Shutting down...`);
await Promise.resolve("doSomethingAsync");
});
});
...
OpenAPI 文档 (Swagger)
OpenAPI 是一种用来定义 RESTful API 规格的标准,与 JSON Schema 兼容。它是一种经过标准化的文字数据结构,可以使用 JSON、YAML 等文档格式来撰写。我们可以利用有支持 OpenAPI 的工具来自动产生 API 文档,或者是 Web 服务的路由代码。
Fastify 官方提供的 @fastify/swagger 套件可以在使用 Fastify 的 JSON Schema 机制来实作出验证请求和回应中所带的数据的功能的同时,也顺便产生 API 文档出来,非常方便!
用以下指令安装所需的套件:
虽然 Fastify 官方有提供 @fastify/swagger-ui 套件来自动生成 Swagger UI 的相关路由,但有一些限制存在。所以笔者还是喜欢自己透过 swagger-ui-dist 套件来撰写 Swagger UI 相关的处理程序。http-status-codes 套件则可以使用 HTTP 状态码来查找对应的错误描述。
添加 src/app.swagger-spec.ts 文件,内容如下:
export const swaggerSpec: import("@fastify/swagger").FastifyDynamicSwaggerOptions["openapi"] = {
info: {
title: "Example",
description: "Example",
version: process.env.npm_package_version ?? "0.0.0",
},
components: {
securitySchemes: {
bearerAuth: {
type: "http",
scheme: "bearer",
description: "Example",
},
},
},
tags: [
{
name: "Example",
description: "Example",
externalDocs: { url: "http://example.com" },
},
],
};
上面的程序用来设置我们的 Web 服务的 API 规格。如果您还不熟悉 OpenAPI 的写法,可以参考这个网页。正常来说,API 端点(endpoint)的规格应定义在 OpenAPI 的 paths 字段,不过我们应该要善用 Fastify 的 JSON Schema 机制,将端点的 OpenAPI 文档写在 JSON Schema 中,将它们集成在一起,如此一来端点的请求与回应的数据验证和用来产生 API 文档的 OpenAPI 文档就不需要分两边撰写。API 端点的网址前缀(OpenAPI 的 servers 字段)笔者是用环境变量来控制,所以这些也不会被写在 src/app.swagger-spec.ts 文件中。
再来添加 src/app.swagger.ts 文件,内容如下:
import fs from "node:fs";
import type { FastifyInstance } from "fastify";
import { swaggerSpec } from "./app.swagger-spec.js";
const CACHE_CONTROL_MAX_AGE = 86400;
const ENV_PREFIX = "SWAGGER_SERVER_";
const DOCS_PATH = process.env.DOCS_PATH ?? "/docs";
const fnv1a = (s: string): number => {
let h = 0x811C9DC5;
const l = s.length;
for (let i = 0; i < l; i++) {
// eslint-disable-next-line no-bitwise
h ^= s.charCodeAt(i);
// eslint-disable-next-line no-bitwise
h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
}
// eslint-disable-next-line no-bitwise
return h >>> 0;
};
export const swaggerOptions: import("@fastify/swagger").SwaggerOptions = { openapi: swaggerSpec };
export const afterRegisterRoutes = (app: FastifyInstance): void => {
if (typeof app.swagger === "function") {
const lastDocsPath = DOCS_PATH.substring(
DOCS_PATH.lastIndexOf("/"),
DOCS_PATH.length,
);
const data = {
swaggerSpecEtag: "",
swaggerUIDistEtag: "",
swaggerSpecJson: "",
swaggerSpecJsonHTML: "",
};
app.addHook("onReady", () => {
const swaggerSpec = app.swagger();
// add servers from environment variables
const servers = [];
for (const variableName of Object.keys(process.env)) {
if (variableName.startsWith(ENV_PREFIX)) {
const order = parseInt(
variableName.substring(ENV_PREFIX.length),
);
if (isNaN(order)) {
continue;
}
servers.push({
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
url: process.env[variableName]!,
order,
});
}
}
servers.sort((a, b) => a.order - b.order);
(swaggerSpec as (typeof swaggerSpec & { openapi: string, servers: typeof servers })).servers = servers;
(swaggerSpec as (typeof swaggerSpec & { openapi: string })).openapi = "3.1.0";
data.swaggerSpecJson = JSON.stringify(swaggerSpec);
data.swaggerSpecJsonHTML = data.swaggerSpecJson.replace(
/<\/(script)>/ugi,
"<\\/$1>",
);
data.swaggerSpecEtag = `W/"${fnv1a(data.swaggerSpecJson)}"`;
data.swaggerUIDistEtag = `W/"${
fnv1a(
process.env.npm_package_dependencies_swagger_ui_dist ?? "",
)
}"`;
});
void app.register((app, _opts, done) => {
const schemaHide = { schema: { hide: true } };
app.get(DOCS_PATH, schemaHide, (req, res) => {
if (req.url.endsWith("/")) {
void res.redirect("./static/index.html");
} else {
void res.redirect(`.${lastDocsPath}/static/index.html`);
}
});
app.get(`${DOCS_PATH}/static`, schemaHide, (req, res) => {
if (req.url.endsWith("/")) {
void res.redirect("./index.html");
} else {
void res.redirect("./static/index.html");
}
});
app.get(`${DOCS_PATH}/json`, schemaHide, (req, res) => {
if (req.headers["if-none-match"] === data.swaggerSpecEtag) {
return void res.code(304).send();
}
void res.code(200)
.header("content-type", "application/json; charset=utf-8")
.header("etag", data.swaggerSpecEtag)
.send(data.swaggerSpecJson);
});
app.get(
`${DOCS_PATH}/static/index.html`,
schemaHide,
(req, res) => {
if (req.url.endsWith("/")) {
return void res.redirect(
`${DOCS_PATH}/static/index.html`,
);
}
if (req.headers["if-none-match"] === data.swaggerSpecEtag) {
return void res.code(304).send();
}
void res.code(200)
.header("content-type", "text/html; charset=utf-8")
.header("etag", data.swaggerSpecEtag)
.send(`<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>API Docs</title>
<link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="./swagger-ui-bundle.js"></script>
<script>
const swaggerSpec = ${data.swaggerSpecJsonHTML};
const docPathIndex = window.location.href.indexOf('${DOCS_PATH}');
if (docPathIndex) {
if (!swaggerSpec.servers) {
swaggerSpec.servers = [];
}
const prefix = window.location.href.substring(0, docPathIndex);
swaggerSpec.servers = [{
url: prefix,
description: 'The server of this API document.'
}].concat(swaggerSpec.servers);
}
window.onload = function() {
window.ui = SwaggerUIBundle({
spec: swaggerSpec,
dom_id: '#swagger-ui',
deepLinking: true,
withCredentials: true,
})
};
</script>
</body>
</html>`);
},
);
app.get(
`${DOCS_PATH}/static/swagger-ui-bundle.js`,
schemaHide,
(req, res) => {
if (
req.headers["if-none-match"] === data.swaggerUIDistEtag
) {
return void res.code(304).send();
}
const file = fs.createReadStream(
"./node_modules/swagger-ui-dist/swagger-ui-bundle.js",
);
void res.code(200)
.header(
"content-type",
"application/javascript; charset=utf-8",
)
.header(
"cache-control",
`public, max-age=${CACHE_CONTROL_MAX_AGE}`,
)
.header("etag", data.swaggerUIDistEtag)
.send(file);
},
);
app.get(
`${DOCS_PATH}/static/swagger-ui-bundle.js.map`,
schemaHide,
(req, res) => {
if (
req.headers["if-none-match"] === data.swaggerUIDistEtag
) {
return void res.code(304).send();
}
const file = fs.createReadStream(
"./node_modules/swagger-ui-dist/swagger-ui-bundle.js.map",
);
void res.code(200)
.header(
"content-type",
"application/json; charset=utf-8",
)
.header(
"cache-control",
`public, max-age=${CACHE_CONTROL_MAX_AGE}`,
)
.header("etag", data.swaggerUIDistEtag)
.send(file);
},
);
app.get(
`${DOCS_PATH}/static/swagger-ui.css`,
schemaHide,
(req, res) => {
if (
req.headers["if-none-match"] === data.swaggerUIDistEtag
) {
return void res.code(304).send();
}
const file = fs.createReadStream(
"./node_modules/swagger-ui-dist/swagger-ui.css",
);
void res.code(200)
.header("content-type", "text/css; charset=utf-8")
.header(
"cache-control",
`public, max-age=${CACHE_CONTROL_MAX_AGE}`,
)
.header("etag", data.swaggerUIDistEtag)
.send(file);
},
);
app.get(
`${DOCS_PATH}/static/swagger-ui.css.map`,
schemaHide,
(req, res) => {
if (
req.headers["if-none-match"] === data.swaggerUIDistEtag
) {
return void res.code(304).send();
}
const file = fs.createReadStream(
"./node_modules/swagger-ui-dist/swagger-ui.css.map",
);
void res.code(200)
.header(
"content-type",
"application/json; charset=utf-8",
)
.header(
"cache-control",
`public, max-age=${CACHE_CONTROL_MAX_AGE}`,
)
.header("etag", data.swaggerUIDistEtag)
.send(file);
},
);
done();
});
}
};
以上程序能够让 Fastify 利用 Swagger UI 来产生 API 文档,并且可以使用两种环境变量来控制。第一种环境变量是以 SWAGGER_SERVER_ 为前缀再接上一个整数的环境变量名称,这种环境变量用来设置 OpenAPI 规格中的 servers 字段(Swagger UI 本身所在的网址前缀因为我们有写程序让它自动使用网页的 JavaScript 程序来加入,所以不需写进来),整数数字愈小排得愈前面。第二种是 DOCS_PATH 环境变量,用来设置 Swagger UI 要使用的路由路径。
接着修改 src/app.fastify.ts 文件,修改方式如下:
...
import { fastifySwagger } from "@fastify/swagger";
...
import { swaggerOptions } from "./app.swagger.js";
...
void app.register(fastifySwagger, swaggerOptions);
...
await registerRoutes(app);
export default app;
以上有个地方要注意,registerRoutes 函数必须要在 Fastify 实体注册了 @fastify/swagger 插件之后运行。
然后修改 src/app.routes.ts 文件,修改方式如下:
...
import { afterRegisterRoutes } from "./app.swagger.js";
...
app.after(() => {
afterRegisterRoutes(app);
});
};
以上有个地方要注意,app.after 那段代码必须要在读取完所有的 xxx.route.ts 文件之后才运行。
至此 Swagger UI 就可以使用了。不过我们还是可以再添加一些让程序开发起来更方便的代码。
添加 src/schemas/index.ts 文件,内容如下:
import { getReasonPhrase } from "http-status-codes";
const _errorResponse = {
type: "object",
description: "The default error response",
properties: {},
};
const _validation = {
type: "object",
required: [
"context",
"errors",
],
properties: {
context: {
type: "string",
enum: [
"body",
"params",
"querystring",
"headers",
],
},
errors: {
type: "array",
items: {
type: "object",
required: [
"instancePath",
"schemaPath",
"keyword",
"params",
],
properties: {
instancePath: { type: "string" },
schemaPath: { type: "string" },
keyword: { type: "string" },
params: {
type: "object",
additionalProperties: true,
},
},
},
minItems: 1,
},
},
};
const _errorCode = {
type: "array",
items: { type: "integer" },
};
// eslint-disable-next-line import/no-unused-modules
export type ErrorResponse = typeof _errorResponse & {
properties: {
validation?: typeof _validation;
errors?: typeof _errorCode & { description?: string };
extra?: unknown;
};
};
/**
* @param statusCode HTTP status code
* @param description the description of this response
* @param errorCode set to `true` or any non-empty strings (the description of the error code) to use error code
* @param extraTypes set to `{ type: ... }` or `{ anyOf: [...] }` to include extra data in the response
*/
export const errorResponse = (
statusCode?: number,
description?: string,
errorCode?: boolean | string,
extraTypes?: unknown,
): ErrorResponse => {
const res = structuredClone(_errorResponse) as ErrorResponse;
if (typeof statusCode !== "undefined") {
if (statusCode === 400 && !errorCode) {
res.properties.validation = structuredClone(_validation);
}
if (typeof description !== "undefined") {
res.description = description;
} else {
try {
const reasonPhrase = getReasonPhrase(statusCode);
res.description = reasonPhrase;
} catch (_err) {
// do nothing
}
}
} else if (typeof description !== "undefined") {
res.description = description;
}
if (errorCode) {
if (typeof extraTypes !== "undefined") {
res.properties.extra = extraTypes;
}
res.properties.errors = structuredClone(_errorCode);
if (errorCode !== true) {
res.properties.errors.description = errorCode;
}
}
return res;
};
以上模块提供 errorResponse 函数,可以快速产生端点回应的 OpenAPI 文档,实际用法等等会介绍。
再来要修改 src/errors/index.ts 文件,如下:
...
/**
* Quickly generate Markdown table text from an `errorCodeEnum` and an `errorCodeVariantsDescriptions` record object.
*
* @param errorCodeEnum should be an enum whose variants' values are all integers
* @param errorCodeVariantsDescriptions a string-string record object
*/
export const generateErrorCodeVariantsDescriptions = (
errorCodeEnum: unknown,
errorCodeVariantsDescriptions: Record<string, string>,
): string => {
const errorCodeEnumR = errorCodeEnum as Record<string, string | number>;
const variants = [];
for (const key of Object.keys(errorCodeEnumR)) {
const i = parseInt(key);
if (isNaN(i)) {
variants.push({
name: key,
code: errorCodeEnumR[key] as number,
});
}
}
variants.sort((a, b) => a.code - b.code);
let markdown = "";
for (const { name, code } of variants) {
let description = name;
if (Object.hasOwn(errorCodeVariantsDescriptions, name)) {
description = errorCodeVariantsDescriptions[name].replaceAll(
"|",
"|",
);
}
markdown += `| ${code} | ${description} |\n`;
}
return markdown.trimEnd();
};
...
以上的 generateErrorCodeVariantsDescriptions 函数可以用来快速产生错误代码的说明列表,实际用法请参考以下范例。
范例程序修改
import type { DeepReadonly } from "ts-essentials";
const helloSchema = {
type: "object",
nullable: true,
properties: {
name: {
type: "string",
examples: ["John"],
description: "The name that you want to greet",
},
},
};
export const HelloSchema: DeepReadonly<typeof helloSchema> = helloSchema;
如上,替 JSON Schema 添加 examples 和 description 等更多让人理解这到底在干啥的信息。
import { generateErrorCodeVariantsDescriptions } from "./index.js";
export enum ExampleErrorCode {
BodyType = 1,
BodyNameType,
NameCannotBeJohn = 100,
}
const exampleErrorCodeVariantsDescriptions = {
BodyType: "The format of body in the HTTP request is incorrect",
BodyNameType: "The type of the field `name` is incorrect",
NameCannotBeJohn: "The value of the field `name` cannot be `John`",
};
export const exampleErrorCodeDescription = `Error code list:
| Code | Description |
| ---- | ----------- |
${
generateErrorCodeVariantsDescriptions(
ExampleErrorCode,
exampleErrorCodeVariantsDescriptions,
)
}
`;
如上,替 Fastify 加入了 OpenAPI 支持之后,我们应该要替每个错误代码枚举添加描述。而描述可以用如上的方式,借由新建一个存放着每个错误代码的说明的大括号对象和 generateErrorCodeVariantsDescriptions 函数来快速产生。
import type { FastifyInstance, RouteHandlerMethod } from "fastify";
import { ExampleController } from "../controllers/example.controller.js";
import {
ExampleErrorCode,
exampleErrorCodeDescription,
} from "../errors/example.error.js";
import { createErrorCodePreParsingHook } from "../errors/index.js";
import { HelloSchema } from "../schemas/example.schema.js";
import { errorResponse } from "../schemas/index.js";
import type { Route } from "./route.js";
const ExampleRoute: Route = {
setRoutes(app: FastifyInstance): void {
app.get("/hello", {
preParsing: createErrorCodePreParsingHook(ExampleErrorCode),
schema: {
tags: ["Example"],
description: "Say hello to a person",
summary: "Hello!",
produces: ["application/json", "text/plain"],
querystring: HelloSchema,
response: {
200: { type: "string", description: "OK" },
400: errorResponse(
400,
undefined,
exampleErrorCodeDescription,
),
},
},
}, ExampleController.hello as RouteHandlerMethod);
app.post("/hello", {
preParsing: createErrorCodePreParsingHook(ExampleErrorCode),
schema: {
tags: ["Example"],
description: "Say hello to a person",
summary: "Hello!",
produces: ["application/json", "text/plain"],
body: HelloSchema,
response: {
200: { type: "string", description: "OK" },
400: errorResponse(
400,
undefined,
exampleErrorCodeDescription,
),
},
},
}, ExampleController.helloPost as RouteHandlerMethod);
},
};
// eslint-disable-next-line import/no-unused-modules
export default ExampleRoute;
如上,我们可以利用刚才加入的代码来简洁有力地撰写支持错误代码机制的 JSON Schema!
Docker
我们可以让我们的 Web 服务运行在 Docker 容器中,以隔离环境、方便部署。
如果您还不熟悉 Docker,请先参考这篇文章:
首先在程序项目根目录中创建 .dockerignore 文件,内容如下:
*
!/src
!/tests
!/.eslintrc
!/pnpm-*.yaml
!/*.json
!/*.mjs
透过以上的 .dockerignore 文件,我们只会把部份的文件纳进 Docker 的 build context 中,以加快 Docker 映像的创建速度。
笔者将 Docker 的设置分为开发(Development)环境和生产(Production)环境,以下会分别介绍要怎么加入。
开发环境上的 Docker
我们可以创建出一种映像,它并没有包含我们 Web 服务的 JavaScript 代码以及 TypeScript 代码,而是提供一个较完整的运行环境,让我们可以将 src 和 tests 目录挂载进容器内进行编译运行与测试的动作。这样在 Host 上我们只需要 VS Code 和 Docker 就可以进进程式开发。
开发环境用的 Dockerfile 笔者习惯将其命名为 Dockerfile.dev,内容如下:
FROM rust:slim-bookworm AS builder
WORKDIR /build
RUN cargo install wait-service --features json \
&& cp ${CARGO_HOME}/bin/wait-service /build
FROM node:24-slim
RUN npm i -g pnpm
EXPOSE 3000 9229 9230
WORKDIR /app
RUN chown node:node /app
COPY --chown=node:node --from=builder /build/wait-service /app/
COPY --chown=node:node pnpm-*.yaml .eslintrc *.mjs *.json /app/
USER node
RUN pnpm i --frozen-lockfile && pnpm store prune
CMD ["npm", "run", "start:dev"]
以上的 Dockerfile 中,使用到 wait-service 这个工具,介绍可以参考这篇文章:
如果您确定您的 Web 服务不会用 TCP 或是 UDS 再去连其它服务,就无需使用 wait-service,可以将它从 Dockerfile 中拿掉。
开发环境上的 Docker 映像是基于轻量(slim)的 Debian 映像,本身即保有一些方便的指令工具能用,如果有缺也可以再于 Dockerfile 中使用 RUN 命令透过 apt 指令来安装。映像内会预先安装好完整的 node_modules(包含 devDependencies)。
以下指令可以创建开发用的 Docker 映像:
docker build -t $(node -p "require('./package.json').name"):dev -f Dockerfile.dev .
以下指令可以启动开发用的 Docker 容器:
docker run -t -d -v "$(pwd)/src:/app/src" -v "$(pwd)/tests:/app/tests" -p 9229:9229 -p 9230:9230 -P --name $(node -p "require('./package.json').name")-dev $(node -p "require('./package.json').name"):dev && docker port $(node -p "require('./package.json').name")-dev
以上指令会用同号的 Host 连接端口映射容器中 inspect 的连接端口,而容器中的 Web 服务监听的 TCP 连接端口 3000 则让 Docker 自行决定要用 Host 的哪个连接端口来映射。
以下指令可以显示开发用的 Docker 容器中的 Web 服务所监听的 TCP 连接端口是 Host 的哪个连接端口:
docker port $(node -p "require('./package.json').name")-dev 3000 | cut -f 2 -d ':' | tr -d '[:space:]'
以下指令可以显示开发用的 Docker 容器的日志:
docker logs -f $(node -p "require('./package.json').name")-dev
以下指令可以停止开发用的 Docker 容器:
docker stop $(node -p "require('./package.json').name")-dev
以下指令可以启动停止中开发用的 Docker 容器:
docker start $(node -p "require('./package.json').name")-dev
以下指令可以(强制)移除开发用的 Docker 容器:
docker rm -f $(node -p "require('./package.json').name")-dev
以下指令可以在开发用的 Docker 容器中跑测试:
docker exec -t $(node -p "require('./package.json').name")-dev npm run test
以下指令也可以在开发用的 Docker 容器中跑测试,但会先等待 Debugger 的接入(稍后会说明如何设置 VS Code):
docker exec -t $(node -p "require('./package.json').name")-dev npm run test:inspect-brk
生产环境上的 Docker
我们可以创建出一种映像,它仅包含 Node.js 运行环境以及我们用 TypeScript 编译出来的 JavaScript 代码和其相依的 node_modules,让我们的 Web 服务能够轻巧地运行在 Docker 容器中。
生产环境用的 Dockerfile 笔者习惯直接将其命名为 Dockerfile,内容如下:
FROM rust:bookworm AS builder
WORKDIR /build
RUN apt update && apt install -y make musl-tools musl-dev \
&& rustup target add x86_64-unknown-linux-musl
RUN cargo install --target x86_64-unknown-linux-musl wait-service --features json \
&& cp ${CARGO_HOME}/bin/wait-service /build
FROM node:24-alpine AS node-builder
RUN npm i -g pnpm
WORKDIR /build
RUN chown node:node /build
COPY --chown=node:node package.json pnpm-*.yaml tsconfig*.json /build/
COPY --chown=node:node src /build/src/
USER node
RUN pnpm i --frozen-lockfile && npm run build && rm -rf node_modules && pnpm i --frozen-lockfile --production
FROM node:24-alpine
EXPOSE 3000
WORKDIR /app
RUN chown node:node /app
COPY --chown=node:node --from=builder /build/wait-service /app/
COPY --chown=node:node --from=node-builder /build/package*.json /app/
COPY --chown=node:node --from=node-builder /build/dist /app/dist/
COPY --chown=node:node --from=node-builder /build/node_modules /app/node_modules/
USER node
CMD ["npm", "start"]
以上的 Dockerfile 中,同样也使用到 wait-service 这个工具,如果您不需要也可以自行移除。生产环境上的 Docker 映像是基于 alpine 映像,非常轻巧。
以下指令可以创建生产用的 Docker 映像:
docker build -t $(node -p "require('./package.json').name") .
以下指令可以启动生产用的 Docker 容器:
docker run -t -d --restart always -P --name $(node -p "require('./package.json').name") $(node -p "require('./package.json').name") && docker port $(node -p "require('./package.json').name")
以下指令可以显示生产用的 Docker 容器中的 Web 服务所监听的 TCP 连接端口是 Host 的哪个连接端口:
docker port $(node -p "require('./package.json').name") 3000 | cut -f 2 -d ':' | tr -d '[:space:]'
以下指令可以显示生产用的 Docker 容器的日志:
docker logs -f $(node -p "require('./package.json').name")
以下指令可以停止生产用的 Docker 容器:
docker stop $(node -p "require('./package.json').name")
以下指令可以启动停止中生产用的 Docker 容器:
docker start $(node -p "require('./package.json').name")
以下指令可以(强制)移除生产用的 Docker 容器:
docker rm -f $(node -p "require('./package.json').name")
VS Code 设置
在 .vscode/launch.json 文件中加入以下设置,让 VS Code 的 Debugger 可以附加 Docker 容器的 Node.js 程序。
{
...
"configurations": [
...
{
"type": "node",
"name": "Docker:inspect",
"request": "attach",
"port": 9229,
"remoteRoot": "/app",
"restart": true
},
{
"type": "node",
"name": "Docker:inspect-brk",
"request": "attach",
"port": 9230,
"remoteRoot": "/app"
}
]
}
Docker Compose
替我们的 Fastify 应用程序加入 Docker 支持之后,还可以再加入 Docker Compose,以方便管理。
如果您还不熟悉 Docker Compose,请先参考这篇文章:
笔者同样将 Docker Compose 的设置分为开发(Development)环境和生产(Production)环境,以下会分别介绍要怎么加入。
开发环境上的 Docker Compose
由于在开发环境上会比较常去透过 docker compose 指令来运行或停止服务,所以开发环境用的 Docker Compose 设置档笔者习惯将其命名为预设的 docker-compose.yml,内容如下:
services:
app:
build:
context: .
dockerfile: Dockerfile.dev
image: example:dev
tty: true
# environment:
# EXAMPLE: example
volumes:
- ./src:/app/src
- ./tests:/app/tests
ports:
- "3000:3000"
# - "9229:9229"
# - "9230:9230"
# networks:
# - example
# depends_on:
# - mongo
# command: ["./wait-service", "--tcp", "mongo.example:27017", "--", "npm", "run", "start:dev"]
# networks:
# example:
# name: example
使用以下指令就可以启动我们开发用的 Web 服务:
生产环境上的 Docker Compose
生产环境用的 Docker Compose 设置档笔者习惯将其命名为 docker-compose.prod.yml,内容如下:
services:
app:
restart: always
build:
context: .
dockerfile: Dockerfile
image: example
tty: true
# environment:
# EXAMPLE: example
ports:
- "3000:3000"
# networks:
# - example
# depends_on:
# - mongo
# command: ["./wait-service", "--tcp", "mongo.example:27017", "--", "npm", "start"]
# networks:
# example:
# name: example
使用以下指令就可以启动我们生产用的 Web 服务:
