V3移行ガイド

このガイドは、Fastify v2からv3への移行を支援することを目的としています。

開始する前に、v2からの非推奨警告をすべて修正してください。すべてのv2の非推奨機能は削除されており、アップグレード後は動作しなくなります。（#1750)

破壊的変更

変更されたミドルウェアのサポート (#2014)

Fastify v3以降、ミドルウェアのサポートはフレームワーク自体には標準で含まれていません。

アプリケーションでExpressミドルウェアを使用する場合は、先に@fastify/expressまたは@fastify/middieプラグインをインストールして登録してください。

v2

// Using the Express `cors` middleware in Fastify v2.
fastify.use(require('cors')());

v3

// Using the Express `cors` middleware in Fastify v3.
await fastify.register(require('@fastify/express'));
fastify.use(require('cors')());

変更されたログのシリアライゼーション (#2017)

ログのシリアライザーは、ネイティブオブジェクトではなく、FastifyのRequestオブジェクトとReplyオブジェクトを使用するように更新されました。

ネイティブオブジェクトには存在するが、Fastifyオブジェクトには存在しない`request`または`reply`プロパティに依存するカスタムシリアライザーは、更新する必要があります。

v2

const fastify = require('fastify')({
  logger: {
    serializers: {
      res(res) {
        return {
          statusCode: res.statusCode,
          customProp: res.customProp
        };
      }
    }
  }
});

v3

const fastify = require('fastify')({
  logger: {
    serializers: {
      res(reply) {
        return {
          statusCode: reply.statusCode, // No change required
          customProp: reply.raw.customProp // Log custom property from res object
        };
      }
    }
  }
});

変更されたスキーマの置換 (#2023)

非標準の`replace-way`共有スキーマサポートは削除されました。この機能は、JSONスキーマ仕様に準拠した`$ref`ベースの置換に置き換えられました。この変更を理解するために、Fastify v3での検証とシリアライゼーションをお読みください。

v2

const schema = {
  body: 'schemaId#'
};
fastify.route({ method, url, schema, handler });

v3

const schema = {
  body: {
    $ref: 'schemaId#'
  }
};
fastify.route({ method, url, schema, handler });

変更されたスキーマ検証オプション (#2023)

setSchemaCompilerおよびsetSchemaResolverオプションは、将来のツールの改善を可能にするためにsetValidatorCompilerに置き換えられました。この変更を理解するために、Fastify v3での検証とシリアライゼーションをお読みください。

v2

const fastify = Fastify();
const ajv = new AJV();
ajv.addSchema(schemaA);
ajv.addSchema(schemaB);

fastify.setSchemaCompiler(schema => ajv.compile(schema));
fastify.setSchemaResolver(ref => ajv.getSchema(ref).schema);

v3

const fastify = Fastify();
const ajv = new AJV();
ajv.addSchema(schemaA);
ajv.addSchema(schemaB);

fastify.setValidatorCompiler(({ schema, method, url, httpPart }) =>
  ajv.compile(schema)
);

変更されたpreParsingフックの動作 (#2286)

Fastify v3以降、preParsingフックの動作がわずかに変更され、リクエストペイロードの操作がサポートされます。

このフックには、追加の引数payloadが追加され、新しいフックシグネチャはfn(request, reply, payload, done)またはasync fn(request, reply, payload)になります。

フックは、done(null, stream)を介して新しいストリームを返すか、非同期関数の場合はストリームを返すことで、オプションで新しいストリームを返すことができます。

フックが新しいストリームを返す場合、後続のフックでは元のストリームの代わりにそのストリームが使用されます。これのサンプルユースケースは、圧縮されたリクエストの処理です。

新しいストリームは、クライアントから受信した実際のデータサイズを反映する必要がある`receivedEncodedLength`プロパティをストリームに追加する必要があります。たとえば、圧縮されたリクエストでは、圧縮されたペイロードのサイズである必要があります。このプロパティは、`data`イベント中に動的に更新できます（そしてする必要があります）。

ペイロードを使用しないFastify v2の古い構文はサポートされていますが、非推奨です。

変更されたフックの動作 (#2004)

Fastify v3以降、onRouteおよびonRegisterフックの動作がわずかに変更され、フックのカプセル化がサポートされます。

• onRoute - フックは非同期的に呼び出されます。このフックは、同じカプセル化スコープ内で新しいプラグインを登録するときに継承されます。したがって、このフックは、プラグインを登録する*前*に登録する必要があります。
• onRegister - onRouteフックと同じです。唯一の違いは、最初の呼び出しがフレームワーク自体ではなく、最初に登録されたプラグインになることです。

変更されたコンテンツタイプパーサーの構文 (#2286)

Fastify v3では、コンテンツタイプパーサーはパーサーに対して単一のシグネチャを持つようになりました。

新しいシグネチャはfn(request, payload, done)またはasync fn(request, payload)です。requestは、IncomingMessageではなく、Fastifyリクエストであることに注意してください。ペイロードは、デフォルトでストリームです。addContentTypeParserでparseAsオプションを使用する場合、payloadはオプション値（文字列またはバッファー）を反映します。

古いシグネチャfn(req, [done])またはfn(req, payload, [done])（ここでreqはIncomingMessage）は引き続きサポートされていますが、非推奨です。

変更されたTypeScriptサポート

Fastifyバージョン3では、型システムが変更されました。新しい型システムでは、ジェネリック制約とデフォルト設定、リクエストボディ、クエリ文字列などのスキーマタイプの新しい定義方法が導入されています。

v2

interface PingQuerystring {
  foo?: number;
}

interface PingParams {
  bar?: string;
}

interface PingHeaders {
  a?: string;
}

interface PingBody {
  baz?: string;
}

server.get<PingQuerystring, PingParams, PingHeaders, PingBody>(
  '/ping/:bar',
  opts,
  (request, reply) => {
    console.log(request.query); // This is of type `PingQuerystring`
    console.log(request.params); // This is of type `PingParams`
    console.log(request.headers); // This is of type `PingHeaders`
    console.log(request.body); // This is of type `PingBody`
  }
);

v3

server.get<{
  Querystring: PingQuerystring;
  Params: PingParams;
  Headers: PingHeaders;
  Body: PingBody;
}>('/ping/:bar', opts, async (request, reply) => {
  console.log(request.query); // This is of type `PingQuerystring`
  console.log(request.params); // This is of type `PingParams`
  console.log(request.headers); // This is of type `PingHeaders`
  console.log(request.body); // This is of type `PingBody`
});

未処理例外の管理 (#2073)

同期ルートハンドラーでは、エラーが発生すると、構成された.setErrorHandler()を呼び出さずに、サーバーが設計上クラッシュしていました。これが変更され、同期および非同期ルートのすべての予期しないエラーが管理されるようになりました。

v2

fastify.setErrorHandler((error, request, reply) => {
  // this is NOT called
  reply.send(error)
})
fastify.get('/', (request, reply) => {
  const maybeAnArray = request.body.something ? [] : 'I am a string'
  maybeAnArray.substr() // Thrown: [].substr is not a function and crash the server
})

v3

fastify.setErrorHandler((error, request, reply) => {
  // this IS called
  reply.send(error)
})
fastify.get('/', (request, reply) => {
  const maybeAnArray = request.body.something ? [] : 'I am a string'
  maybeAnArray.substr() // Thrown: [].substr is not a function, but it is handled
})

その他の追加と改善

• フックは、登録方法に関係なく、一貫したコンテキストを持つようになりました (#2005)
• request.reqとreply.resをrequest.rawとreply.rawに非推奨化しました (#2008)
• modifyCoreObjectsオプションを削除しました (#2015)
• connectionTimeoutオプションを追加しました (#2086)
• keepAliveTimeoutオプションを追加しました (#2086)
• プラグインのasync-awaitサポートを追加しました (#2093)
• エラーとしてオブジェクトをスローする機能を追加しました (#2134)