Миграция с JavaScript на TypeScript
Постепенно перенести существующий проект JavaScript на TypeScript.
Стратегия миграции
- Добавление tsconfig.json
- Переименование .js в .ts
- Постепенное добавление аннотаций типов
- Включение строгого режима
Настройка tsconfig.json
tsconfig.json
{
"compilerOptions": {
// Начальный этап: ослабленная конфигурация
"target": "ES2020",
"module": "commonjs",
"strict": false,
"noImplicitAny": false,
"strictNullChecks": false,
"skipLibCheck": true,
// Разрешить JS-файлы
"allowJs": true,
"checkJs": false,
// Каталог вывода
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
"compilerOptions": {
// Начальный этап: ослабленная конфигурация
"target": "ES2020",
"module": "commonjs",
"strict": false,
"noImplicitAny": false,
"strictNullChecks": false,
"skipLibCheck": true,
// Разрешить JS-файлы
"allowJs": true,
"checkJs": false,
// Каталог вывода
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
Постепенно включайте строгие проверки
Включайте поэтапно
// Этап 1: Базовая миграция
{
"compilerOptions": {
"strict": false,
"noImplicitAny": false
}
}
// Этап 2: Включить проверку типов
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true
}
}
// Этап 3: Полностью строгий режим
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictPropertyInitialization": true
}
}
{
"compilerOptions": {
"strict": false,
"noImplicitAny": false
}
}
// Этап 2: Включить проверку типов
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true
}
}
// Этап 3: Полностью строгий режим
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictPropertyInitialization": true
}
}
Аннотации типов JSDoc
Используйте JSDoc в JavaScript для добавления типов.
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());
}
* @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());
}
Вывод:
JSDoc 注释添加成功
Файлы деклараций типов
Создайте декларации для модулей без определений типов.
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;
}
}
export function doSomething(param: string): void;
export class MyClass {
constructor(options: { name: string });
name: string;
}
}
Ключевое слово declare
Пример
// Объявление глобальной переменной
declare var GLOBAL_CONFIG: {
apiUrl: string;
version: string;
};
// Объявление глобальной функции
declare function myFunction(param: string): void;
// Объявление пространства имён
declare namespace MyNamespace {
function doSomething(): void;
}
// Использование
console.log(GLOBAL_CONFIG.apiUrl);
myFunction("hello");
MyNamespace.doSomething();
declare var GLOBAL_CONFIG: {
apiUrl: string;
version: string;
};
// Объявление глобальной функции
declare function myFunction(param: string): void;
// Объявление пространства имён
declare namespace MyNamespace {
function doSomething(): void;
}
// Использование
console.log(GLOBAL_CONFIG.apiUrl);
myFunction("hello");
MyNamespace.doSomething();
Вывод:
Declaration successful
Инструменты миграции
- tsc --allowJs:Компиляция JS-файлов
- checkJs:Проверка типов JS
- // @ts-check:Проверка типов в одном файле
- // @ts-ignore:Игнорирование ошибок
legacy.js
// @ts-check
// @ts-ignore
var result = someLegacyFunction();
// @ts-ignore
var result = someLegacyFunction();
Лучшие практики
- Начать миграцию с критических модулей
- Добавить модульные тесты
- Постепенно включить строгий режим
- Использовать комментарии JSDoc
- Создать файлы объявлений типов
Итог
- Инкрементальный:Пошаговая миграция
- JSDoc:Аннотации типов
- Файлы объявлений:.d.ts
- Строгий режим:Включать поэтапно
Другие расширения