TypeScript strikt in einem großen Projekt: Schritt-für-Schritt-Migration, ohne die Entwicklung anzuhalten
Warum können Sie Strict nicht einfach aktivieren?
In einem Projekt mit mehreren hundert Dateien erzeugt "strict": true Tausende von Fehlern. Sie mit einem Zweig zu korrigieren bedeutet, wochenlang eine PR zu führen, die mit allen in Konflikt steht und die niemand richtig überprüfen kann. Es ist auch unmöglich, die Entwicklung in dieser Zeit zu stoppen. Wir brauchen ein Schema, bei dem der neue Code sofort streng geschrieben und der alte Code in Teilen übersetzt wird.
Was in strict enthalten ist
Das Flag strict besteht aus einer Reihe separater Prüfungen, die jeweils unabhängig aktiviert werden können:
noImplicitAny– Parameter und Variablen ohne Typ, der nicht abgeleitet werden kann, werden zu einem Fehler und nicht zuany.strictNullChecks-nullundundefinedsind keine gültigen Werte jeglichen Typs mehr. Normalerweise führt dies zu den meisten Fehlern und dem größten Nutzen.strictFunctionTypes,strictBindCallApply,strictPropertyInitialization,noImplicitThis,alwaysStrict,useUnknownInCatchVariables.
Ein weiteres nützliches Flag, das nicht in strict enthalten ist, ist noUncheckedIndexedAccess: Der Zugriff auf arr[i] und record[key] gibt T | undefined zurück. Es sollte als separater Schritt am Ende eingefügt werden.
Strategie 1: Flags einzeln markieren
Das einfachste Schema für mittelgroße Projekte:
- 1.Aktivieren Sie Flags, die wenige Fehler verursachen (
alwaysStrict,strictBindCallApply,noImplicitThis) – normalerweise bedeutet dies Dutzende von Änderungen. - 2.
noImplicitAny: mechanische Fehler, schnell, teilweise automatisch korrigiert. - 3.
strictNullChecks– Hauptbühne. Bequemer geht es mit der zweiten Strategie. - 4.Aktivieren Sie
strict: trueund entfernen Sie einzelne Flags.
Jeder Schritt ist ein separater kleiner PR, der leicht eingefüllt werden kann.
Strategie 2: Strikte Konfiguration für übersetzte Dateien
Der Haupt-tsconfig.json bleibt nicht strikt, daneben erscheint jedoch ein strikter Code, der nur den übersetzten Teil überprüft:
// tsconfig.strict.json
{
"extends": "./tsconfig.json",
"compilerOptions": { "strict": true, "noEmit": true },
"include": [
"src/shared/lib/**/*",
"src/entities/user/**/*",
"next-env.d.ts"
]
}Hier liegt eine wichtige Falle. tsc prüft nicht nur die Dateien von include, sondern auch alles, was sie importieren. Wenn ein übersetztes Modul ein unübersetztes Modul importiert, werden in der Ausgabe auch Fehler aus dem unübersetzten Modul angezeigt. Daher werden sie von unten nach oben übersetzt (zuerst Dienstprogramme und Modelle, dann was sie verwendet), und die Ausgabe wird entsprechend der Liste der übersetzten Pfade gefiltert:
// scripts/check-strict.mjs
import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";
const cfg = JSON.parse(readFileSync("tsconfig.strict.json", "utf8"));
const prefixes = cfg.include.map((p) => p.replace(/\*\*.*$/, ""));
let out = "";
try {
execSync("npx tsc -p tsconfig.strict.json --pretty false", { encoding: "utf8" });
} catch (e) {
out = e.stdout ?? "";
}
const errors = out.split("\n").filter((l) => /error TS\d+/.test(l) && prefixes.some((p) => l.startsWith(p)));
for (const e of errors) console.error(e);
process.exit(errors.length ? 1 : 0);Das Skript geht mit obligatorischer Überprüfung an CI. Ich habe den Ordner zu include hinzugefügt – er ist für immer vor Regression geschützt.
Für den gleichen Ansatz mit umgekehrter Logik gibt es ein fertiges Tool: Mit typescript-strict-plugin können Sie strict für das gesamte Projekt aktivieren, indem Sie nicht übersetzte Dateien mit einem Kommentar // @ts-strict-ignore markieren und dies in CI mit dem Befehl tsc-strict überprüfen. Dies ist praktisch, wenn bereits mehr als die Hälfte der übersetzten Dateien vorhanden sind.
Strategie 3: Ratchet nach Anzahl der Fehler
Wenn es wichtiger ist, eine Verschlechterung der Situation zu verhindern, als alles schnell zu beheben, reicht es aus, die Fehler eines vollständigen strengen Laufs zu zählen und zu verhindern, dass ihre Zahl wächst:
COUNT=$(npx tsc -p tsconfig.strict-all.json --noEmit --pretty false | grep -c "error TS" || true) BASELINE=$(cat .strict-baseline) if [ "$COUNT" -gt "$BASELINE" ]; then echo "strict errors: $COUNT > baseline $BASELINE"; exit 1 fi echo "$COUNT" > .strict-baseline # закоммитьте уменьшение в том же PR
Jeder PR ändert die Zahl entweder nicht oder verringert sie. Das betterer-Tool macht das Gleiche auf eine übersichtlichere Art und Weise: Es verfolgt Fehler nach Datei und nicht nur nach der Gesamtzahl, sodass ein Fix an einer Stelle nicht einen neuen Fehler an einer anderen verdeckt.
So beheben Sie das Problem, damit es nicht noch schlimmer wird
Das Ziel besteht nicht darin, die rote Unterstreichung zu entfernen, sondern die Typen wahrheitsgetreu darzustellen.
- `!` (Nicht-Null-Behauptung) verwandelt einen Kompilierungsfehler in einen Laufzeitfehler. Dies ist nur dann akzeptabel, wenn tatsächlich eine Garantie besteht und diese erklärt werden kann. Ansonsten - eine explizite Prüfung mit vorzeitigem Ausstieg.
- `any` → `unknown` für externe Daten (JSON, API-Antworten,
catch (e)) und anschließende Eingrenzung durch Prüfungen oder Validierungsschemata. - `@ts-expect-error` anstelle von `@ts-ignore`. Der erste Fehler fällt, wenn der Fehler nicht mehr vorliegt, und verhindert, dass vorübergehende Unterdrückungen für immer bestehen bleiben. Immer mit einem Kommentar warum.
- Optionale Felder in Modellen. Wenn ein Feld in der Datenbank
NOT NULList, sollte es im Typ nicht?sein, nur weil es einfacher ist, das Objekt im Test zu initialisieren.
Die ESLint-Regeln @typescript-eslint/no-explicit-any und @typescript-eslint/no-non-null-assertion im Fehlermodus für übersetzte Verzeichnisse verhindern die Rückkehr alter Gewohnheiten.
Arbeitsorganisation
- Kleine PRs in einem Ordner, ohne sie mit funktionalen Änderungen zu vermischen – sie sind einfach zu überprüfen und rückgängig zu machen.
- Neue Dateien werden sofort an die strenge Zone gesendet. Andernfalls wächst der unübersetzte Teil schneller als er abnimmt.
- Beginnen Sie mit dem Code, bei dem Fehler am teuersten sind: Arbeiten mit Geld, Zugriffsrechten, Parsen externer Daten.
Wann man es nicht übertreiben sollte
Migrationsskripte, einmalige Dienstprogramme und Prototypen, die bald gelöscht werden, müssen nicht übersetzt werden – schließen Sie sie aus der strengen Zone aus. Und wenn das Projekt ohne aktive Entwicklung im Support-Modus ist, reicht die Ratsche: Sie verhindert eine Verschlechterung, ohne dass ein separates Migrationsprojekt erforderlich ist.