Migration de JavaScript vers TypeScript

Migrer progressivement un projet JavaScript existant vers TypeScript.


Stratégie de migration

  1. Ajouter tsconfig.json
  2. Renommer .js en .ts
  3. Ajouter progressivement des annotations de type
  4. Activer le mode strict

Configurer tsconfig.json

tsconfig.json

{
    "compilerOptions": {
        // Étape initiale : configuration souple
        "target": "ES2020",
        "module": "commonjs",
        "strict": false,
        "noImplicitAny": false,
        "strictNullChecks": false,
        "skipLibCheck": true,

        // Autoriser les fichiers JS
        "allowJs": true,
        "checkJs": false,

        // Répertoire de sortie
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}

Activer progressivement les vérifications strictes

Activer par étapes

// Phase 1 : migration de base
{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false
    }
}

// Phase 2 : activer la vérification des types
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true
    }
}

// Phase 3 : entièrement strict
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": true
    }
}

Annotations de type JSDoc

Utilisez JSDoc en JavaScript pour ajouter des types.

utils.js

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */

function add(a, b) {
    return a + b;
}

/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 */


/**
 * @param {number} id
 * @returns {Promise<User>}
 */

function getUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
}

Sortie :

JSDoc 注释添加成功

Fichiers de déclaration de type

Créer des déclarations pour les modules sans définitions de type.

src/types/my-module.d.ts

declare module "my-module" {
    export function doSomething(param: string): void;
    export class MyClass {
        constructor(options: { name: string });
        name: string;
    }
}

Mot-clé declare

Exemple

// Déclarer une variable globale
declare var GLOBAL_CONFIG: {
    apiUrl: string;
    version: string;
};

// Déclarer une fonction globale
declare function myFunction(param: string): void;

// Déclarer un espace de noms
declare namespace MyNamespace {
    function doSomething(): void;
}

// Utilisation
console.log(GLOBAL_CONFIG.apiUrl);
myFunction("hello");
MyNamespace.doSomething();

Sortie :

Declaration successful

Outils de migration

  • tsc --allowJs:Compiler les fichiers JS
  • checkJs:Vérifier les types JS
  • // @ts-check:Vérification de type d'un seul fichier
  • // @ts-ignore:Ignorer les erreurs

legacy.js

// @ts-check
// @ts-ignore
var result = someLegacyFunction();

Bonnes pratiques

  1. Commencer la migration à partir des modules critiques
  2. Ajouter des tests unitaires
  3. Activer progressivement le mode strict
  4. Utiliser des commentaires JSDoc
  5. Créer des fichiers de déclaration de types

Résumé

  • Incrémental :Migration étape par étape
  • JSDoc:Annotations de type
  • Fichiers de déclaration :.d.ts
  • Mode strict :Activer par phases

Autres extensions