Upgrade auf Express v5

Express 5 unterscheidet sich nicht sehr von Express 4; obwohl es die gleiche grundlegende API hat, gibt es immer noch Änderungen, die die Kompatibilität mit der vorherigen Version stören. Daher könnte eine Anwendung mit Express 4 nicht funktionieren, wenn Sie sie auf Express 5 aktualisieren.

Installation

Um diese Version zu installieren, benötigst du eine Node.js Version 18 oder höher. Führen Sie dann den folgenden Befehl in Ihrem Anwendungsverzeichnis aus:

npm install "express@5"

Sie können dann Ihre automatisierten Tests durchführen, um zu sehen, was fehlschlägt, und Probleme gemäß den unten aufgeführten Updates beheben. Nach dem Beheben von Testfehlern führen Sie Ihre App aus, um zu sehen, welche Fehler auftreten. Sie werden sofort erfahren, ob die App Methoden oder Eigenschaften verwendet, die nicht unterstützt werden.

Express 5 Codemoden

Um Ihnen zu helfen, Ihren Expressserver zu migrieren Wir haben eine Reihe von Codemods erstellt, die Ihnen helfen, Ihren Code automatisch auf die neueste Version von Express zu aktualisieren.

Führen Sie den folgenden Befehl aus, um alle verfügbaren Codemods auszuführen:

npx codemod@latest @expressjs/v5-migration-recipe

Wenn du eine bestimmte Codemod ausführen möchtest, kannst du folgenden Befehl ausführen:

npx codemod@latest @expressjs/name-of-the-codemod

Du findest die Liste der verfügbaren Codemoden here.

Entfernte Methoden und Eigenschaften

Wenn du eine dieser Methoden oder Eigenschaften in deiner App verwendest, stürzt sie ab. Also müssen Sie Ihre App nach dem Update auf Version 5 ändern.

app.del()

Express 5 unterstützt nicht mehr die app.del() Funktion. Wenn Sie diese Funktion verwenden, wird ein Fehler geworfen. Um HTTP DELETE Routen zu registrieren, benutze stattdessen die app.delete() Funktion.

Anfangs wurde del anstelle von delete verwendet, da delete ein reserviertes Schlüsselwort in JavaScript ist. Jedoch können ECMAScript 6, delete und andere reservierte Schlüsselwörter legal als Eigenschaftsnamen verwendet werden.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/route-del-to-delete

Oder Sie können Ihren Code manuell aktualisieren:

app.del('/user/:id', (req, res) => {
app.delete('/user/:id', (req, res) => {
  res.send(`DELETE /user/${req.params.id}`);
});

app.param(fn)

Die Signatur app.param(fn) wurde verwendet, um das Verhalten der app.param(name, fn) Funktion zu ändern. Es ist seit v4.11.0 veraltet und Express 5 unterstützt es überhaupt nicht mehr.

Pluralisierte Methodennamen

Die folgenden Methodennamen wurden pluralisiert. In Express 4 führte die Verwendung der alten Methoden zu einer Deprecation Warnung. Express 5 unterstützt sie nicht mehr:

req.acceptsCharset() wird durch req.acceptsCharsets() ersetzt.

req.acceptsEncoding() wird durch req.acceptsEncodings() ersetzt.

req.acceptsLanguage() wird durch req.acceptsLanguages() ersetzt.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/pluralize-method-names

Oder Sie können Ihren Code manuell aktualisieren:

app.all('/', (req, res) => {
  req.acceptsCharset('utf-8');
  req.acceptsEncoding('br');
  req.acceptsLanguage('en');
  req.acceptsCharsets('utf-8');
  req.acceptsEncodings('br');
  req.acceptsLanguages('en');

  // ...
});

Führender Doppelpunkt (:) im Namen von app.param(name, fn)

Ein führendes Doppelzeichen (:) im Namen der app. aram(name, fn) Funktion ist ein Überbleibsel von Express 3, und um der Abwärtskompatibilität willen hat Express 4 sie mit einer Veraltungsmeldung unterstützt. Express 5 ignoriert es stillschweigend und verwendet den Namensparameter, ohne ihn mit einem Doppelpunkt zu präfixieren.

Dies sollte deinen Code nicht beeinflussen, wenn du der Express-4-Dokumentation von [app.param]folgst (/en/4x/api#app.param), da es keine Erwähnung des führenden Doppelpunkts.

req.param(Name)

Diese potenziell verwirrende und gefährliche Methode zum Abrufen von Formulardaten wurde entfernt. Sie müssen nun gezielt nach dem übermittelten Parameternamen im req.params, req.body oder req.query Objekt suchen.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/explicit-request-params

Oder Sie können Ihren Code manuell aktualisieren:

app.post('/user', (req, res) => {
  const id = req.param('id');
  const body = req.param('body');
  const query = req.param('query');
  const id = req.params.id;
  const body = req.body;
  const query = req.query;

  // ...
});

res.json(obj, Status)

Express 5 unterstützt nicht mehr die Signatur res.json(obj, status). Setze stattdessen den Status und verkette ihn auf die Methode res.json() wie folgt: res.status(status).json(obj).

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/status-send-order

Oder Sie können Ihren Code manuell aktualisieren:

app.post('/user', (req, res) => {
  res.json({ name: 'Ruben' }, 201);
  res.status(201).json({ name: 'Ruben' });
});

res.jsonp(obj, status)

Express 5 unterstützt nicht mehr die Signatur res.jsonp(obj, status). Setze stattdessen den Status und verkette ihn auf die res.jsonp() Methode wie folgt: res.status(status).jsonp(obj).

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/status-send-order

Oder Sie können Ihren Code manuell aktualisieren:

app.post('/user', (req, res) => {
  res.jsonp({ name: 'Ruben' }, 201);
  res.status(201).jsonp({ name: 'Ruben' });
});

res.redirect(url, Status)

Express 5 unterstützt nicht mehr die Signatur res.redirect(url, status). Verwenden Sie stattdessen die folgende Signatur: res.redirect(status, url).

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/redirect-arg-order

Oder Sie können Ihren Code manuell aktualisieren:

app.get('/user', (req, res) => {
  res.redirect('/users', 301);
  res.redirect(301, '/users');
});

res.redirect(‘back’) und res.location(‘back’)

Express 5 unterstützt nicht mehr den magischen String back in den Methoden res.redirect() und res.location(). Verwenden Sie stattdessen den req.get('Referrer') || '/' Wert, um zurück zur vorherigen Seite zu leiten. In Express 4 wurden die Methoden res.redirect('back') und res.location('back') veraltet.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/back-redirect-deprecated

Oder Sie können Ihren Code manuell aktualisieren:

app.get('/user', (req, res) => {
  res.redirect('back');
  res.redirect(req.get('Referrer') || '/');
});

res.send(Körper, Status)

Express 5 unterstützt nicht mehr die Signatur res.send(obj, status). Setze stattdessen den Status und verkette ihn auf die Methode res.send() wie folgt: res.status(status).send(obj).

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/status-send-order

Oder Sie können Ihren Code manuell aktualisieren:

app.get('/user', (req, res) => {
  res.send({ name: 'Ruben' }, 200);
  res.status(200).send({ name: 'Ruben' });
});

res.send(Status)

Express 5 unterstützt nicht mehr die Signatur res.send(status), wobei status eine Zahl ist. Verwenden Sie stattdessen die res. endStatus(statusCode) Funktion, die den HTTP-Antwort-Header-Statuscode setzt und die Textversion des Codes sendet: “Nicht gefunden”, “Interner Server-Fehler”, und so weiter. Wenn Sie eine Nummer mit Hilfe der res senden müssen. end() Funktion, zitiert die Zahl, um sie in einen String zu konvertieren, so dass Express es nicht als Versuch interpretiert, die nicht unterstützte alte Signatur zu verwenden.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/status-send-order

Oder Sie können Ihren Code manuell aktualisieren:

app.get('/user', (req, res) => {
  res.send(200);
  res.sendStatus(200);
});

res.sendfile()

Die res.sendfile() Funktion wurde durch eine camel-cased Version res.sendFile() in Express 5 ersetzt.

Wie aktualisiere ich

Sie können Ihren Code automatisch aktualisieren, indem Sie den folgenden Befehl ausführen:

npx codemod@latest @expressjs/camelcase-sendfile

Oder Sie können Ihren Code manuell aktualisieren:

app.get('/user', (req, res) => {
  res.sendfile('/path/to/file');
  res.sendFile('/path/to/file');
});

res.sendFile() Optionen

Die hidden und from Optionen für res.sendFile() werden nicht mehr unterstützt. Benutze stattdessen dotfiles und root.

Wie aktualisiere ich

app.get('/files/:name', (req, res) => {
  res.sendFile(req.params.name, { hidden: true, from: '/uploads' });
  res.sendFile(req.params.name, { dotfiles: 'allow', root: '/uploads' });
});

express.static() Optionen

Die hidden und from Optionen für express.static() werden nicht mehr unterstützt. Benutze stattdessen dotfiles und root. Beachte, dass from nie in der API dokumentiert wurde, aber als Alias für root akzeptiert wurde. Der Standardwert von dotfiles ist jetzt "ignore".

Wie aktualisiere ich

const express = require('express');
const app = express();

app.use(express.static('public', { hidden: true }));
app.use(express.static('public', { dotfiles: 'allow' }));

router.param(fn)

Die Signatur router.param(fn) wurde verwendet, um das Verhalten der router.param(name, fn) Funktion zu ändern. Es ist seit v4.11.0 veraltet und Express 5 unterstützt es überhaupt nicht mehr.

express.static.mime

In Express 5 ist mime nicht mehr eine exportierte Eigenschaft des static Feldes. Benutze das mime-types package, um mit MIME Werte zu arbeiten.

Wie aktualisiere ich

express.static.mime.lookup('json');
const mime = require('mime-types');
mime.lookup('json');

MIME-Typ-Änderungen

Mehrere MIME-Typen haben sich aufgrund von Aktualisierungen in [mime-db]geändert (https://github.com/jshttp/mime-db). Diese Änderungen betreffen nur express.static() und res.sendFile(). Eine vollständige Liste der Änderungen findest du in der mime-db changelog.

Express 4 verwendet mime-db Version 1.52.0, während Express 5 neuere Versionen verwendet, die Aktualisierungen auf IANA und andere MIME Spezifikationen widerspiegeln. Die bemerkenswerteste Änderung ist, dass JavaScript-Dateien (.js) jetzt als text/javascript anstelle von application/javascript ausgeliefert werden.

In Express 5 gelten Änderungen an MIME-Typen von mime-db Updates nicht als Abbruch von Änderungen also seien Sie vorsichtig, wenn Sie Ihre Abhängigkeiten aktualisieren, da sich MIME-Typen zwischen kleineren oder Patch-Versionen ändern können.

express:router Debug-Logs

Router-Bearbeitungslogik wird nun durch eine separate Abhängigkeit (router) des Express-Teams ausgeführt so dass Debug-Protokolle in einen anderen Namensraum verschoben wurden. Vor Express 5.1 existierten diese Debug-Logs nicht. Um sie zu erhalten, aktualisiere auf eine aktuelle Express 5-Version oder aktualisiere das router Paket in deinem package-lock.json:

v4	v5
`Express:router`	’router’
`Express:router:layer`	`router:layer`
`Express:router:route`	`router:route`
`Express:*` (beinhaltet alle)	`Express:` + `router` + `router:`

Wie aktualisiere ich

DEBUG=express:* node index.js
DEBUG=express:*,router,router:* node index.js

Geändert

Diese APIs existieren noch, aber ihr Verhalten hat sich geändert. Überprüfen Sie diese Änderungen, um sicherzustellen, dass Ihre App wie erwartet funktioniert.

Pfad Route übereinstimmende Syntax

Syntax für Pfadrouten ist, wenn als erster Parameter app.all(), app.use(), app.METHOD(), router.all(), router.METHOD() und router.use() APIs angegeben wird. Die folgenden Änderungen wurden vorgenommen, wie der Pfad-String auf eine eingehende Anfrage abgestimmt wird:

Das Platzhalter * muss einen Namen haben, passend zum Verhalten der Parameter :, verwende /*splat statt /*
```
app.get('/*', async (req, res) => {
app.get('/*splat', async (req, res) => {
  res.send('ok');
});
```
Note
*splat entspricht jedem Pfad ohne den Wurzelpfad. Wenn du den Wurzelpfad auch / anpassen musst, kannst du /{*splat} verwenden, indem du den Platzhalter in Klammern verpackst.
app.get('/{*splat}', async (req, res) => { res.send('ok'); });

Das optionale Zeichen ? wird nicht mehr unterstützt, verwende stattdessen Klammern.

app.get('/:file.:ext?', async (req, res) => {
app.get('/:file{.:ext}', async (req, res) => {
  res.send('ok');
});

Regexp Zeichen werden nicht unterstützt. Zum Beispiel:

app.get('/[discussion|page]/:slug', async (req, res) => {
app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => {
  res.status(200).send('ok');
});

Einige Zeichen wurden reserviert, um Verwirrung während des Upgrades zu vermeiden (()[]?+!), verwenden Sie \ um sie zu maskieren.
Parameternamen unterstützen nun gültige JavaScript-Identifikatoren oder zitiert wie :"this.

Abgelehnte Versprechen von Middleware und Handlern

Fordern Sie Middleware und Handler an, die abgelehnte Versprechungen zurückgeben, werden nun durch die Weiterleitung des zurückgewiesenen Wertes als Error an die Fehlerbehandlung Middleware behandelt. Das bedeutet, dass die Verwendung von async Funktionen als Middleware und Handler einfacher ist als je zuvor. Wenn ein Fehler in einer async-Funktion oder einem abgewiesenen Versprechen geworfen wird, wird erwartet in einer async-Funktion, diese Fehler werden an den Fehlerhandler übergeben, als ob next(err)` aufgerufen würde.

Details darüber, wie Express mit Fehlern umgeht, finden Sie in der Dokumentation zur Fehlerbehandlung.

Wie aktualisiere ich

Du kannst nun async/await direkt verwenden, ohne manuell Fehler zu fangen. Wenn getUserById einen Fehler oder eine Ablehnung, wird next automatisch mit dem zurückgewiesenen Wert aufgerufen.

app.get('/user/:id', (req, res, next) => {
  getUserById(req.params.id)
    .then((user) => res.send(user))
    .catch(next);
});
app.get('/user/:id', async (req, res) => {
  const user = await getUserById(req.params.id);
  res.send(user);
});

express.urlencoded

Die express.urlencoded Methode erzeugt standardmäßig die extended Option false.

Wie aktualisiere ich

Wenn deine Anwendung sich auf das extended Verhalten stützt, setze es explizit auf true:

app.use(express.urlencoded());
app.use(express.urlencoded({ extended: true }));

express.static dotfiles

Die express.static Middleware-Option dotfiles ist nun standardmäßig "ignore. In Express 4 wurden Dotfiles standardmäßig geliefert. Als Ergebnis sind Dateien in einem Verzeichnis, das mit einem Punkt (.) beginnt, wie . ell-known, wird nicht mehr erreichbar sein und einen 404 Nicht gefunden Fehler zurückgeben. Dies kann die Funktionalität beeinträchtigen, die von der Bereitstellung von Dot-Verzeichnissen abhängt, wie Android App Links und Apple Universal Links.

Wie aktualisiere ich

Servieren Sie spezifische dot-Verzeichnisse explizit mit der Option dotfiles: "allow" . So können Sie sicher nur die vorgesehenen dot-Verzeichnisse ausführen, während Sie das standardmäßige sichere Verhalten für andere dotfiles beibehalten.

app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' }));
app.use(express.static('public'));

app.hören

In Express 5 ruft die app.listen Methode die vom Benutzer zur Verfügung gestellte Callback-Funktion auf, wenn der Server ein Fehlerereignis erhält. In Express 4 würden solche Fehler aufgeworfen. Diese Änderung verlagert die Verantwortung für die Fehlerbehandlung auf die Callback-Funktion in Express 5. Wenn ein Fehler auftritt, wird er als Argument an den Callback übergeben. Zum Beispiel:

const server = app.listen(8080, '0.0.0.0', (error) => {
  if (error) {
    throw error; // e.g. EADDRINUSE
  }
  console.log(`Listening on ${JSON.stringify(server.address())}`);
});

app.router

Das app.router Objekt, das in Express 4 entfernt wurde, hat ein Comeback in Express 5 gemacht. In der neuen Version ist dieses Objekt nur eine Referenz auf den Basis-Express-Router, im Gegensatz zu Express 3, wo eine App sie explizit laden musste.

req.body

Die Eigenschaft req.body gibt undefined zurück, wenn der Body nicht analysiert wurde. In Express 4 gibt es standardmäßig {} zurück.

app.post('/user', (req, res) => {
  console.dir(req.body);
  // Express 4
  // => {}
  // Express 5
  // => undefined
});

req.host

In Express 4 hat die req.host Funktion die Portnummer falsch entfernt, wenn sie vorhanden war. In Express 5 wird die Portnummer beibehalten.

req.params

Das req.params Objekt hat nun einen null Prototyp wenn man String Pfade benutzt. Wenn der Pfad jedoch mit einem regulären Ausdruck definiert ist, bleibt req.params ein Standardobjekt mit einem normalen Prototyp. Zusätzlich gibt es zwei wichtige Verhaltensänderungen:

Wildcard-Parameter sind jetzt Arrays:

Platzhalter (z.B. /*splat) erfassen Pfadsegmente als Array anstelle eines einzelnen Strings.

app.get('/*splat', (req, res) => {
  // GET /foo/bar
  console.dir(req.params);
  // => [Object: null prototype] { splat: [ 'foo', 'bar' ] }
});

Unübereinstimmende Parameter werden weggelassen:

In Express 4 waren unpassende Platzhalter leere Zeichenketten ('') und optionale : Parameter (mit ?) hatten einen Schlüssel mit dem Wert undefiniert. In Express 5 werden unübertroffene Parameter vollständig aus req.params entfernt.

// v4: unmatched wildcard is empty string
app.get('/*', (req, res) => {
  // GET /
  console.dir(req.params);
  // => { '0': '' }
});

// v4: unmatched optional param is undefined
app.get('/:file.:ext?', (req, res) => {
  // GET /image
  console.dir(req.params);
  // => { file: 'image', ext: undefined }
});

// v5: unmatched optional param is omitted
app.get('/:file{.:ext}', (req, res) => {
  // GET /image
  console.dir(req.params);
  // => [Object: null prototype] { file: 'image' }
});

req.query

Die Eigenschaft req.query ist keine beschreibbare Eigenschaft mehr und ist stattdessen ein Getter. Der Standard-Query-Parser wurde von “extended” auf “simple” geändert.

app.get('/search', (req, res) => {
  // This is no longer possible in Express 5
  req.query.page = 1;
});

res.clearCookie

Die Methode res.clearCookie ignoriert die vom Benutzer bereitgestellten maxAge und expires Optionen.

app.get('/logout', (req, res) => {
  res.clearCookie('session', { maxAge: 0, expires: new Date(0) });
  res.clearCookie('session');
});

res.status

Die res.status Methode akzeptiert nur ganze Zahlen im Bereich 100 bis 999, gefolgt von dem von Knoten definierten Verhalten. , und gibt einen Fehler zurück, wenn der Statuscode keine Ganzzahl ist.

app.get('/user', (req, res) => {
  res.status(99); // Throws an error
  res.status(200); // OK
});

res.variieren

Das res.vary wirft einen Fehler auf, wenn das field Argument fehlt. In Express 4, wenn das Argument weggelassen wurde, gab es eine Warnung in der Konsole.

app.get('/user', (req, res) => {
  res.vary(); // Throws an error
  res.vary('Accept'); // OK
});