メイン コンテンツにスキップ
バージョン: latest (v5.0.x)

V4 移行ガイド

このガイドは、Fastify v3 から v4 への移行に役立つことを目的としています。

v4 に移行する前に、v3 のすべての非推奨警告を修正していることを確認してください。v3 の非推奨機能はすべて削除されており、アップグレード後は機能しなくなります。

Codemod​

Fastify v4 Codemod​

アップグレードを支援するために、Codemod チームと協力して、Fastify v4 の新しい API とパターンの多くにコードを自動的に更新する Codemod を公開しました。

次の 移行レシピ を実行して、コードを Fastify v4 に自動的に更新します。

npx codemod@latest fastify/4/migration-recipe

これにより、次の Codemod が実行されます。

これらの Codemod は、それぞれ v4 移行ガイドに記載されている変更を自動化します。利用可能な Fastify Codemod の完全なリストと詳細については、Codemod レジストリを参照してください。

重大な変更​

エラー処理の構成 (#3261)​

非同期エラー処理関数でエラーが発生すると、設定されている場合は上位レベルのエラー処理が実行されます。上位レベルのエラー処理がない場合は、以前と同様にデフォルトが実行されます。

import Fastify from 'fastify'

const fastify = Fastify()

fastify.register(async fastify => {
  fastify.setErrorHandler(async err => {
    console.log(err.message) // 'kaboom'
    throw new Error('caught')
  })
  
  fastify.get('/encapsulated', async () => {
    throw new Error('kaboom')
  })
})

fastify.setErrorHandler(async err => {
  console.log(err.message) // 'caught' 
  throw new Error('wrapped')
})

const res = await fastify.inject('/encapsulated')
console.log(res.json().message) // 'wrapped'

ルート エラー処理は、Fastify の汎用エラー処理です。このエラー処理は、存在する場合、エラー オブジェクト内のヘッダーとステータス コードを使用します。カスタム エラー処理が提供されている場合、ヘッダーとステータス コードは自動的には設定されません。

app.use() の削除 (#3506)​

Fastify の v4 では、app.use() が削除され、ミドルウェアの使用はサポートされなくなりました。

ミドルウェアを使用する必要がある場合は、継続的にメンテナンスされている @fastify/middie または @fastify/express を使用します。ただし、Fastify の フック に移行することを強くお勧めします。

注意: コードモッドを使用して、app.use()を削除します

npx codemod@latest fastify/4/remove-app-use

reply.resがreply.rawに移動しました

以前はreply.res属性を使用して基盤となるリクエストオブジェクトにアクセスしていましたが、これからはreply.rawを使用する必要があります。

注意: コードモッドを使用して、reply.resをreply.rawに変更します

npx codemod@latest fastify/4/reply-raw-access

プロミスの連鎖を「分岐」させるにはreplyを返す必要があります

応答が非同期で送信されたときや、応答を明示的に返さない場合など、状況によってはルーターハンドラーからreply引数を返す必要があります。

exposeHeadRoutesはデフォルトでtrue

v4以降では、すべてのGETルートに対して同等のHEADルートが作成されます。サーバーオプションでexposeHeadRoutes: falseを設定することで、この動作を元に戻すことができます。

同期ルート定義(#2954)

ルート定義のエラーレポートを改善するために、ルート登録が同期化されました。そのため、プラグインでonRouteフックを指定する場合は、次のいずれかを実行する必要があります。

  • ルートをプラグインでラップする（推奨）

    たとえば、これをリファクタリングします

    fastify.register((instance, opts, done) => {
      instance.addHook('onRoute', (routeOptions) => {
        const { path, method } = routeOptions;
        console.log({ path, method });
        done();
      });
    });

    fastify.get('/', (request, reply) => { reply.send('hello') });

    これを次のようにします

    fastify.register((instance, opts, done) => {
      instance.addHook('onRoute', (routeOptions) => {
        const { path, method } = routeOptions;
        console.log({ path, method });
        done();
      });
    });

    fastify.register((instance, opts, done) => {
      instance.get('/', (request, reply) => { reply.send('hello') });
      done();
    });

    注意: コードモッドを使用してルート定義を同期化します

    npx codemod@latest fastify/4/wrap-routes-plugin

  • await register(...)を使用します

    たとえば、これをリファクタリングします

    fastify.register((instance, opts, done) => {
      instance.addHook('onRoute', (routeOptions) => {
        const { path, method } = routeOptions;
        console.log({ path, method });
      });
      done();
    });

    これを次のようにします

    await fastify.register((instance, opts, done) => {
      instance.addHook('onRoute', (routeOptions) => {
        const { path, method } = routeOptions;
        console.log({ path, method });
      });
      done();
    });

注意: コードモッドを使用してawait register(...)を次の例に変更します

npx codemod@latest fastify/4/await-register-calls

オプションのURLパラメータ

暗黙的に省略可能なパラメータをすでに使用している場合は、ルートにアクセスしようとすると404エラーが発生します。これからは、省略可能なパラメータを明示的に宣言する必要があります。

たとえば、投稿のリストと表示に同じルートを使用する場合、これをリファクタリングします

fastify.get('/posts/:id', (request, reply) => {
  const { id } = request.params;
});

これを次のようにします

fastify.get('/posts/:id?', (request, reply) => {
  const { id } = request.params;
});

非破壊的変更

.listen()署名のバリアディックの非推奨

fastify.listen()メソッドのバリアディック署名が非推奨になりました。

このリリース以前は、このメソッドの次の起動が有効でした

  • fastify.listen(8000)
  • fastify.listen(8000, ‘127.0.0.1’)
  • fastify.listen(8000, ‘127.0.0.1’, 511)
  • fastify.listen(8000, (err) => { if (err) throw err })
  • fastify.listen({ port: 8000 }, (err) => { if (err) throw err })

Fastify v4では、次の起動のみが有効です

  • fastify.listen()
  • fastify.listen({ port: 8000 })
  • fastify.listen({ port: 8000 }, (err) => { if (err) throw err })

複数の型のスキーマの変更

Fastify v4ではAjvがv8にアップグレードされたため、「null」以外の複数型を持つ「type」キーワードは禁止されています。

次のようなコンソール警告が表示されることがあります

strict mode: use allowUnionTypes to allow union type keyword at "#/properties/image" (strictTypes)

そのため、次のようなスキーマは次のように変更する必要があります

{
  type: 'object',
  properties: {
    api_key: { type: 'string' },
    image: { type: ['object', 'array'] }
  } 
}

次のようにします

{
  type: 'object',
  properties: {
    api_key: { type: 'string' },
    image: {
      anyOf: [
        { type: 'array' },
        { type: 'object' }
      ]
    }
  }
}

reply.trailers メソッドを追加する (#3794)​

Fastify が HTTP トレーラー 応答ヘッダーをサポートするようになりました。