Migración de TypeScript desde JavaScript

Migra gradualmente proyectos JavaScript existentes a TypeScript.


Estrategia de migración

  1. Agregar tsconfig.json
  2. Renombrar .js a .ts
  3. Agregar anotaciones de tipo gradualmente
  4. Habilitar modo estricto

Configurar tsconfig.json

tsconfig.json

{
    "compilerOptions": {
        // Etapa inicial: configuración flexible
        "target": "ES2020",
        "module": "commonjs",
        "strict": false,
        "noImplicitAny": false,
        "strictNullChecks": false,
        "skipLibCheck": true,

        // Permitir archivos JS
        "allowJs": true,
        "checkJs": false,

        // Directorio de salida
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}

Habilitar comprobaciones estrictas gradualmente

Habilitar por fases

// Etapa 1: Migración básica
{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false
    }
}

// Etapa 2: Habilitar verificación de tipos
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true
    }
}

// Etapa 3: Totalmente estricto
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": true
    }
}

Anotaciones de tipo JSDoc

Usa JSDoc en JavaScript para agregar tipos.

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());
}

Resultado de ejecución:

JSDoc 注释添加成功

Archivos de declaración de tipos

Crea declaraciones para módulos sin definiciones de tipos.

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;
    }
}

La palabra clave declare

Ejemplo

// Declarar variable global
declare var GLOBAL_CONFIG: {
    apiUrl: string;
    version: string;
};

// Declarar función global
declare function myFunction(param: string): void;

// Declarar espacio de nombres
declare namespace MyNamespace {
    function doSomething(): void;
}

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

Resultado de ejecución:

Declaración exitosa

Herramientas de migración

  • tsc --allowJs:Compilar archivos JS
  • checkJs:Comprobar tipos JS
  • // @ts-check:Verificación de tipos en un solo archivo
  • // @ts-ignore:Ignorar errores

legacy.js

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

Mejores prácticas

  1. Comienza la migración con los módulos clave
  2. Agregar pruebas unitarias
  3. Habilitar el modo estricto gradualmente
  4. Usar comentarios JSDoc
  5. Crear archivos de declaración de tipos

Resumen

  • Progresivo:Migración gradual
  • JSDoc:Anotaciones de tipo
  • Archivos de declaración:.d.ts
  • Modo estricto:Habilitar por fases

Otras extensiones