企业官网建设流程全解析

深入 Fastify 插件开发指南：编写高质量、可维护、可生态化插件的完整实践

【免费下载链接】fastifyFast and low overhead web framework, for Node.js项目地址: https://gitcode.com/GitHub_Trending/fa/fastify

Fastify 是一个以性能与低开销为核心目标、以"一切皆插件（Everything is a Plugin）"为架构哲学的开源 Web 框架。本文基于仓库官方指南 Write-Plugin.md，系统讲解如何编写一个"高质量"的 Fastify 插件，覆盖代码规范、文档要求、许可证选择、示例编写、自动化测试、代码规范工具（Linter）与持续集成（CI）等完整环节，并结合 Plugins-Guide.md、Testing.md 与框架源码给出可落地、可复现的实战方案。读完本文，你将掌握一套从零编写、测试并提交到 Fastify 生态列表的完整插件开发工作流。

编写插件前必须理解的 Fastify 哲学

Fastify 官方在 Write-Plugin.md 中开宗明义：Fastify 是一个极简框架（minimal framework），插件（plugin）才是它真正的力量所在。因此任何插件作者在动笔之前，都应把 Fastify 的三大核心原则刻在脑中：

1. 性能（performance）：插件代码应当尽量避免引入不必要的开销；
2. 低开销（low overhead）：尽可能复用 Fastify 已有的请求/响应管线能力，而非重复造轮子；
3. 良好的用户体验（good experience）：插件应易于理解、安装、配置与调试。

理解这些原则不能停留在口号层面，需要真正搞清楚插件在 Fastify 内部是如何被加载、封装与执行的。官方为插件开发者准备了一份完整的向导文档 The hitchhiker's guide to plugins（即"插件搭便车指南"），其中覆盖了register、decorate、decorateRequest、decorateReply、hooks 与fastify-plugin封装逃逸等全部核心 API。下面是编写插件前必须具备的三个底层认知。

认知一：在 Fastify 中，一切皆插件

正如 JavaScript 中一切都是对象，在 Fastify 中一切都是插件：路由、工具函数、中间件、连接池管理统统以插件形式注册。统一的入口 API 就是register（详见 Plugins 参考文档）：

fastify.register( require('./my-plugin'), { options } )

从 fastify.js 的源码可以看到，Fastify 实例上的register、after、ready、close等方法由avvio（一个专门管理异步插件加载顺序的库）注入并接管，且设定了autostart: false——这意味着Fastify 只会在.listen()、.inject()或.ready()被调用之后才开始真正加载插件，此前插件只是被"登记"而非"执行"。

认知二：register会创建封装上下文（Encapsulation）

register的核心语义是：每次调用都会创建一个新的 Fastify 上下文（context）。你在该上下文中对实例做的任何改动（例如decorate注入的变量、addHook注册的钩子）不会泄漏到其父级或兄弟级上下文，只有子上下文可以继承。这正是 Fastify 封装模型（Encapsulation）的意义：它彻底避免了跨模块的隐式依赖，让你可以在任意时刻把单体应用拆分为多个微服务，而无需大规模重构。

这条设计在源码层有非常直接的体现：Fastify 实例暴露了一组 decorator 检查 API，如hasDecorator、hasRequestDecorator、hasReplyDecorator，它们在 decorate.js 中实现，用于在插件加载前后验证装饰器是否已就位。

认知三：插件本质是一个特定签名的函数

不论功能如何，Fastify 插件的形态都是"暴露一个单一函数"，有两种等价写法。

经典回调式（callback）：

module.exports = function (fastify, options, done) { // fastify：被封装后的 Fastify 实例 // options ：注册时传入的选项对象 // done ：插件就绪后必须调用的回调 fastify.get('/plugin', (request, reply) => { reply.send({ hello: 'world' }) }) done() }

ESM / async 式（现代推荐）：

// plugin.mjs —— ESM 自 Node.js v13.3.0 起得到支持 async function plugin (fastify, opts) { fastify.get('/', async (req, reply) => { return { hello: 'world' } }) } export default plugin

插件系统是**完全可重入（reentrant）且基于图（graph-based）**的：插件内部可以继续注册路由、继续嵌套register，同时 Fastify 会强制保证插件的加载顺序与关闭顺序（关闭顺序由onClose钩子与avvio保证）。

从源码看懂插件注册与校验流程（Code 环节的底层支撑）

Write-Plugin.md 的 Code 一节建议插件作者先通读插件指南以掌握全部可用 API。为了让"高质量代码"不至于悬空，这里把框架内部注册插件时的实际校验逻辑展示出来。在 plugin-utils.js 中，registerPlugin依次执行了五个步骤：

1. 注册插件名（registerPluginName）：读取插件元数据中的name并记录到当前实例的kRegisteredPlugins列表；
2. 健康检查（checkPluginHealthiness）：若插件是async function却又声明了 3 个形参（即async (fastify, opts, done)），会抛出FST_ERR_PLUGIN_INVALID_ASYNC_HANDLER，因为 async 插件应返回 Promise 而不是调用done；
3. 版本校验（checkVersion）：读取元数据中的fastify版本范围字段，用semver判断当前 Fastify 版本是否满足要求，否则抛出FST_ERR_PLUGIN_VERSION_MISMATCH（lib/plugin-utils.js）；
4. 装饰器依赖校验（checkDecorators）：若插件在元数据里声明依赖某个已存在的装饰器（如decorators: { fastify: ['db'] }），注册时会即时检查，缺失则抛出FST_ERR_PLUGIN_NOT_PRESENT_IN_INSTANCE；
5. 插件依赖校验（checkDependencies）：检查插件声明的"前置插件依赖"是否已注册，缺失抛出FST_ERR_PLUGIN_DEPENDENCY_NOT_REGISTERED。

与此同时，Fastify 提供了一组便于排查的公开 API，这些都能帮助你写出"可观测"的插件代码：

• fastify.printPlugins()：打印插件树的加载结构（由 avvio 的prettyPrint提供，见 fastify.js）；
• fastify.pluginName：返回当前上下文所处插件链（kPluginNameChain）的展示名称（fastify.js）；
• fastify.hasPlugin(name)：判断某插件是否已注册（fastify.js）。

插件名称的解析规则在 getPluginName 中非常清晰：优先读取Symbol.for('fastify.display-name')（见测试夹具 test/plugin.name.display.js），其次是 Node.jsrequire.cache中的文件路径，再次是函数自身的name属性，最后回退为函数源码前两行。这意味着：给插件函数起一个有意义的名字、或显式设置 display-name，是高质量插件应当养成的习惯，因为它直接影响用户排查插件树与报错时的可读性。

精心组织插件代码：封装、共享与分发

"Code"环节的质量高低，取决于你是否能把插件要暴露的能力通过最小且明确的 API 呈现给使用者。Fastify 提供了三类扩展点，分别对应不同的注入目标：

下面分别说明它们的使用要点与注意事项。

decorate：把能力挂到实例上

fastify.decorate('util', (a, b) => a + b) // 之后任意处可调用：fastify.util('that is ', 'awesome')

decorateReply / decorateRequest：更贴合对象的写法

对比"把 HTML 渲染函数挂到实例上，再手动取出使用"：

fastify.decorate('html', payload => { return generateHtml(payload) }) fastify.get('/html', (request, reply) => { reply .type('text/html') .send(fastify.html({ hello: 'world' })) })

更优雅的是直接用decorateReply，把行为内聚到reply对象本身：

fastify.decorateReply('html', function (payload) { this.type('text/html') // this 即 Reply 对象 this.send(generateHtml(payload)) }) fastify.get('/html', (request, reply) => { reply.html({ hello: 'world' }) })

注意：因为这里this需要指向Reply/Request对象，传入decorateRequest/decorateReply的工具必须使用function关键字定义，不能使用箭头函数。

对请求对象的装饰同理。与其在每处路由里写：

fastify.decorate('getBoolHeader', (req, name) => { return req.headers[name] ?? false })

不如直接扩展Request原型（文档明确说明装饰到原型上更利于性能）：

fastify.decorateRequest('setBoolHeader', function (name) { this.isHappy = this.headers[name] ?? false }) fastify.decorateRequest('isHappy', false) // 挂到 Request 原型上，速度更快 fastify.addHook('preHandler', (request, reply, done) => { request.setBoolHeader('happy') done() }) fastify.get('/happiness', (request, reply) => { reply.send({ happy: request.isHappy }) })

利用 hooks 让工具在恰当时刻自动执行

如果某个工具需要在每个请求上都运行，最糟糕的写法是在每个路由处理器里手动重复调用。正确的做法是把它注册为 hook（生命周期事件见 Lifecycle 参考文档，hooks 完整列表见 Hooks 参考文档）：

fastify.decorate('util', (request, key, value) => { request[key] = value }) fastify.addHook('preHandler', (request, reply, done) => { fastify.util(request, 'timestamp', new Date()) done() })

如果你只想让 hook 作用于一部分路由，仍然靠封装模型实现：把decorate+addHook+ 受影响的get全部放进一个register块内，钩子便只对该上下文生效。更进一步，对于要对外分发的插件，官方推荐使用onRoutehook动态地为符合条件（如配置了config.useUtil: true）的路由注入 preHandler，这样使用者只需声明配置即可获得增强（示例见 Plugins-Guide.md 的 onRoute 小节），其完整实现位于 Hooks 参考文档。

处理封装与分发：fastify-plugin 的两种核心用法

封装是保护伞，但当你分发插件（例如封装了数据库连接的插件）时，反而需要打破它。Fastify 提供的官方配套模块是fastify-plugin（fp），将插件函数包裹后即可"跳出"封装、让装饰器直达根实例；同时它还天然支持异步启动（因为decorate是同步 API，而register包裹后插件可等待异步连接建立完成）。

const fp = require('fastify-plugin') const dbClient = require('db-client') function dbPlugin (fastify, opts, done) { dbClient.connect(opts.url, (err, conn) => { fastify.decorate('db', conn) done() }) } module.exports = fp(dbPlugin)

fastify-plugin在封装层面的"免于封装"行为，可以从框架测试 test/plugin.1.test.js 中反推验证：例如测试对插件设置plugin[Symbol.for('skip-override')] = true后，即便register(plugin, { prefix: 'foo' })注册，其内部定义的路由也不会被前缀封装；而fastify-plugin正是通过在你导出的函数上打Symbol.for('skip-override')标记来实现这一效果（相关判定逻辑在 lib/plugin-utils.js 的shouldSkipOverride）。

fastify-plugin的第二大价值是元数据声明：在包裹前先给插件函数附加元数据，fp会将其透传给 Fastify，从而在注册时触发上节所述的版本校验、装饰器校验与依赖校验。最典型的两种声明：

// 要求 Fastify 主版本范围 module.exports[Symbol.for('plugin-meta')] = { name: 'my-plugin', fastify: '4.x', dependencies: ['@fastify/some-dependency'], decorators: { fastify: ['existingDecorator'] } } module.exports = fp(pluginFunction)

此外还有一种常见技巧：若你的插件依赖前序插件注入的变量作为注册选项，register的第二个参数可以传入函数（接收父级实例）：

const fastify = require('fastify')() fastify.register(fp(dbPlugin), { url: 'https://fastify.example' }) fastify.register(require('your-plugin'), parent => { return { connection: parent.db, otherOption: 'foo-bar' } })

这里回调中的parent是外层 Fastify 实例的引用，可以按声明顺序读取前面插件注入的任何变量。

错误处理、自定义错误与告警

在 Plugins-Guide.md 中，官方还给出了三个插件分发阶段的"工程化"建议：

• 启动期错误：用afterAPI 捕获注册后立即发生的错误。after回调有四种形态——无参数（错误直接交给下一个错误处理器）、一参数（该参数即错误对象）、二参数（错误对象 + done 回调）、三参数（错误对象 + 上下文 + done 回调）。典型用法：

fastify .register(require('./database-connector')) .after(err => { if (err) throw err })

• 自定义错误：如需暴露统一的错误对象，可使用官方错误工具@fastify/error生成带code、statusCode的标准错误类（Fastify 自身约 100 个内置FST_ERR_*错误码也采用这套机制，错误码定义见 lib/errors.js，参考文档见 Errors 参考文档）：

const createError = require('@fastify/error') const CustomError = createError('ERROR_CODE', 'message') throw new CustomError()

• 弃用告警：当需要提示用户"该 API 即将弃用"或提醒特殊使用场景时，使用官方process-warning模块（Fastify 的运行时告警系统，见 warnings.js 与 Warnings 参考文档）：

const warning = require('process-warning')() warning.create('MyPluginWarning', 'MP_ERROR_CODE', 'message') warning.emit('MP_ERROR_CODE')

文档：插件能否进入生态列表的硬门槛

Write-Plugin.md 的 Documentation 一节给出了一条毫不含糊的规则：

如果插件文档质量不佳，官方不会将其纳入生态列表（ecosystem list）。缺少高质量文档会让使用者难以接入，也往往导致插件最终无人问津。

文档环节建议至少覆盖如下内容：

1. 一句话定位：说明插件解决什么问题、适用场景；
2. 安装命令：给出npm install一行命令；
3. 最小可用示例：完整的 register + 最小配置代码，让用户能 30 秒跑通；
4. 选项（Options）完整参考：逐一列出选项名、类型、默认值与含义（可对照 Routes 参考文档 中的 route 选项风格）；
5. 与既有 API 的关系：说明插件会注入哪些装饰器、注册哪些钩子、可能影响哪些 Fastify 默认行为（如 content-type parser 改动），这些概念分别见 Decorators、Hooks、ContentTypeParser 等参考文档；
6. 使用限制与版本要求：明确声明peerDependencies与元数据中的fastify版本范围。

此外，应当让文档成为"可导航的目录"——仓库的 Plugins-Guide.md 通过目录（TOC）与锚点链接组织长文，这一做法值得插件作者在撰写 README 时借鉴。

许可证：官方不强制，但推荐 MIT

关于许可证，官方态度非常开放：你完全可以选择自己喜欢的许可证，Fastify 不做任何强制。不过官方更偏好 MIT，理由是它允许更多人自由使用你的代码。若不确定如何选择，可参考 OSI 维护的开源许可证清单或 GitHub 的 choosealicense.com 向导。作为对比，本仓库 Fastify 自身即采用 MIT 协议（见根目录 LICENSE）。

示例：仓库里永远要放一个可直接运行的例子

高质量插件仓库中必须包含示例文件。示例是用户快速验证插件、理解插件行为的最短路径。官方指出"你的用户会因此感激你"。

在本仓库中即可找到真实对照：插件形态示例 examples/plugin.js 暴露了一个同时注册GET/POST路由的经典插件函数；而 examples/use-plugin.js 展示了使用者一侧的完整接法——构造 Fastify 实例、定义含 schema 的选项、register插件、最后.listen()启动：

// examples/use-plugin.js 的核心接线逻辑 const fastify = require('../fastify')({ logger: true }) const opts = { schema: { response: { '2xx': { type: 'object', properties: { hello: { type: 'string' } } } } } } fastify.register(require('./plugin'), opts, function (err) { if (err) { throw err } }) fastify.listen({ port: 3000 }, function (err) { if (err) { throw err } })

推荐在 README 中以"Install → Register → Run"三段式组织示例，保证它不经修改即可直接node运行。

测试：无测试的插件不会被生态列表接受

测试是 Write-Plugin.md 中最重的硬性要求：

插件必须经过彻底测试以证明其工作正常。没有测试的插件不会被生态列表接受。缺少测试无法建立信任，也无法保证插件在其依赖不同版本下仍能持续工作。

官方不强制任何测试框架。Fastify 团队自身使用 Node.js 内置测试运行器node:test，因为它开箱即用地支持并行测试（parallel testing）与代码覆盖率（code coverage）。建议通读 Testing.md 中的 Plugins 专项章节来掌握插件测试方法。

测试插件的标准模式：Mock 实例 + register + inject

插件测试通常不直接起服务器，而是创建一个纯内存的 Fastify 实例作为宿主，注册插件，再用内置的inject发起伪 HTTP 请求。inject由light-my-request提供（fastify.js 中展示了它是按需懒加载的），其最大优点是会自动保证所有已注册插件完成启动。

以 Testing.md 中的插件示例为例。先写好插件（建议用fastify-plugin包裹，并分别练习实例装饰与请求装饰）：

// plugin/myFirstPlugin.js const fP = require('fastify-plugin') async function myPlugin (fastify, options) { fastify.decorateRequest('helloRequest', 'Hello World') fastify.decorate('helloInstance', 'Hello Fastify Instance') } module.exports = fP(myPlugin)

再编写完整断言版本（使用 Node 内置node:test）：

// test/myFirstPlugin.test.js const Fastify = require('fastify') const { test } = require('node:test') const myPlugin = require('../plugin/myFirstPlugin') test('Test the Plugin Route', async t => { t.plan(5) const fastify = Fastify() fastify.register(myPlugin) fastify.get('/', async (request, reply) => { // 断言插件注入的装饰器可用 t.assert.ifError(request.helloRequest) t.assert.ok(request.helloRequest, 'Hello World') t.assert.ok(fastify.helloInstance, 'Hello Fastify Instance') return { message: request.helloRequest } }) const fastifyResponse = await fastify.inject({ method: 'GET', url: '/' }) t.assert.strictEqual(fastifyResponse.statusCode, 200) t.assert.deepStrictEqual( JSON.parse(fastifyResponse.body), { message: 'Hello World' } ) })

在package.json中把测试脚本设为：

"test": "node --test --watch"

运行npm test即可看到结果。

inject 的三种调用形态

HTTP 注入还支持回调、链式与 Promise/async 三种形态，供你在不同测试风格中选择：

// 1) 回调形态 fastify.inject({ method: 'GET', url: '/', query: {}, // 可携带 query、payload、headers、cookies 等 payload: {}, headers: {}, cookies: {} }, (error, response) => { // 你的断言 }) // 2) 链式形态（省略回调后返回可链式调用对象，.end 触发请求） fastify .inject() .get('/') .headers({ foo: 'bar' }) .query({ foo: 'bar' }) .end((err, res) => { console.log(res.payload) }) // 3) async/await 形态（推荐） const res = await fastify.inject({ method: 'GET', url: '/' }) // 直接断言 res.statusCode、res.json() 等

插件测试的额外工程实践

结合 Testing.md 与仓库内真实测试代码，还有三个高频实践值得纳入你的测试计划：

• 善用t.after(() => fastify.close())：在测试用例末尾关闭实例，确保与外部服务（数据库、Redis 等）的连接被正确释放，避免句柄泄漏导致进程不退出；
• 测试"加载即校验"的边界：插件的装饰器冲突、依赖缺失、版本不匹配应各有一个测试用例。例如仓库在 test/plugin.1.test.js 中覆盖了skip-override、插件命名、fastify-plugin不产生封装（不注册 fp 时instance.test为undefined，注册 fp 后可达）等场景，你的插件测试也应覆盖"注册成功"之外的失败路径；
• 测试插件之间的组合：当插件声明了对其他插件的依赖时，编写一个"先注册依赖插件、再注册当前插件"的组合测试，确保依赖树解析正确。

并行测试与覆盖率

因为node:test原生支持并行执行，若插件内部使用了共享资源（如同一端口），请为不同测试文件分配独立资源或使用t.plan精确规划断言数量。覆盖率方面，仓库自身在package.json中使用borp作为node:test之上的运行器并配合c8收集覆盖率（参见 package.json 的unit、coverage脚本），插件作者也可以直接使用这些工具或任意自己偏好的库——官方不强制。

代码规范（Linter）：非强制但强烈推荐

Write-Plugin.md 指出：代码规范工具（linter）不是强制要求，但强烈推荐，它能保证一致的代码风格并帮助避免大量低级错误。Fastify 团队自身使用standard风格，因为它无需配置且极易接入测试套件。本仓库（Fastify 本体）当前实际使用的是 ESLint +neostandard配置，配置项位于 eslint.config.js，相关脚本见 package.json 中的lint/lint:fix/lint:markdown。

对插件作者的建议：

• 为插件单独建立 lint 脚本并纳入 CI；
• 配置lint:fix让格式问题可以一键修复；
• 若发布的是 TypeScript 插件，可同时引入类型检查（Fastify 的类型定义见 fastify.d.ts 与 types 目录）。

持续集成（CI）与依赖更新

虽然不是强制要求，但如果你以开源方式发布插件，持续集成能带来两个实际好处：

1. 保证贡献不会破坏插件——任何外部 PR 都会被 CI 自动验证；
2. 持续证明插件可用——每次提交都跑通测试，本身就是对用户的承诺。

官方点名的选项包括 CircleCI 与 GitHub Actions，二者对开源项目免费且易于配置。此外，可以启用 Dependabot 之类的依赖更新服务，它既能帮你保持依赖最新，还能提前发现新版本 Fastify 与你的插件之间的兼容性问题——这恰好呼应了插件元数据中fastify版本范围声明的价值。

一个最小可行的 CI 流水线通常包含四个 Job：npm ci安装 →lint→node --test（或npm test）→ （可选）覆盖率上传。

提交到生态列表：入库前的自我对照清单

完成插件后，官方欢迎你把作品提交到生态列表（ecosystem），团队会审查代码并在必要时帮你改进。生态列表由 Fastify 团队维护的 Core 部分与社区维护的 Community 部分构成（分类与完整清单见 Ecosystem.md）。提交之前，请对照 Write-Plugin.md 做一次完整自检：

仓库文档中列出的一组真实世界范例（均为生态内知名插件，可作为文档与工程质量的参照）：

• @fastify/view：模板渲染插件，支持 ejs、pug、handlebars、marko 等引擎；
• @fastify/mongodb：MongoDB 连接插件，让服务各处的代码共享同一连接池；
• @fastify/multipart：为 Fastify 提供 multipart 表单支持；
• @fastify/helmet：为 Fastify 注入关键安全响应头；
• 此外，Write-Plugin.md 推荐的文档范本还包括@fastify/caching、@fastify/compress、@fastify/cookie、@fastify/under-pressure等，它们的 README 结构（定位、安装、选项表、示例、测试说明）都值得逐字研读。

最后再回顾官方那句话：Fastify 是极简的，插件才是它的力量所在。把性能、低开销、用户友好三条原则贯彻到代码、文档、测试与工程化配置的每一环，你写出的就不仅是一个"能跑"的插件，而是一个进入生态后能被长期维护、被他人信任、经得起版本演进考验的优质插件。

【免费下载链接】fastifyFast and low overhead web framework, for Node.js项目地址: https://gitcode.com/GitHub_Trending/fa/fastify