淺談 TS 運行時類型檢查

What - 什麼是運行時類型檢查？

編譯時類型檢查（靜態類型檢查）：

在編譯階段對變量類型進行靜態檢查，編譯後的代碼不保留任何類型標註信息，對實際代碼運行沒有影響

運行時類型檢查（動態類型檢查）：

在代碼實際運行過程中對數據類型進行檢查，一般會用在約束函數參數、返回值這類內外部之間傳遞數據

Why - 爲什麼需要運行時類型檢查？

TypeScript 對於前端項目可維護性提升很大，也能幫我們保障內部編碼時的類型安全，但在和外部進行數據傳遞時，僅僅有編譯期類型檢查還是免不了出一些問題，以我遇過的兩次事故爲例：

1. 對內輸入數據：線上接口返回的視頻 id 字段類型由 string 變爲 number 後前端獲取後丟失精度，導致頁面異常

2. 向外輸出數據：項目迭代需求時邏輯改動導致某個埋點字段丟失，過了很久要分析數據才發現，白白浪費了時間

如果我們在運行時做了相應的類型檢查，發現異常上報監控，問題就能更早解決了，還有其他能想到的一些需要運行時類型檢查的場景：

1. 表單場景類型校驗

2. 爲 API/JSB 接口編寫測試

3. 上報參數過濾敏感信息字段

可以看出，在涉及 IO 數據場景時額外的運行時檢查是有必要的，以使數據類型不符合預期時，我們能及時發現問題。

How - 怎麼做運行時類型檢查？

interface MyDataType {
    video_id: string;
    user_info: {
        user_id: number;
        email: string;
    };
    image_list: {
        url: string
    }[];
}

const data: MyDataType = await fetchMyData()

if (
    typeof data.video_id === 'string' &&
    data.user_info &&
    typeof data.user_info.user_id === 'number' &&
    typeof data.user_info.email === 'string' &&
    Array.isArray(data.image_list) &&
    data.image_list.every((image) => typeof image.url === 'string')
    ...
) {
    // do something
}

如上，我們可以手動編寫一份運行時類型檢查代碼，但這樣寫起來效率低、維護性差，而且沒有用上已有的 TS 類型，導致我們要同時維護兩份類型，保證之間的同步。

下面向大家介紹業內幾種類型檢查方案，個人認爲一個好方案至少要滿足兩點：

1. 只需維護一份類型規則即可享有靜態類型提示和運行時檢查校驗

2. 在靜態和運行時的類型檢查能力等價（起碼運行時不能比靜態檢查寬鬆，不然會出線上 bug）

方案 1 - 動態 to 靜態

編寫運行時校驗規則，並從中提取出靜態類型

JSON 形式

通過編寫 JSON 來描述校驗規則，典型的有 ajv、tv4，用法如下：

import Ajv, { JTDDataType } from "ajv/dist/jtd"

const ajv = new Ajv()
const schema = {
    properties: {
        video_id: { type: "string" },
        user_info: {
            properties: {
                user_id: { type: "int32" },
                email: { type: "string" }
            }
        },
        image_list: {
            elements: {
                properties: {
                    url: { type: "string" },
                }
            }
        }
    }
} as const
type MyDataType = JTDDataType<typeof schema>
// type MyDataType = {
//     video_id: string;
//     user_info: {
//         user_id: number;
//         email: string;
//     } & {};
//     image_list: ({
//         url: string;
//     } & {})[];
// } & {}

const data: MyDataType = await fetchMyData()

const validate = ajv.compile(schema)
validate(data)
if (validate.errors) {
    // do something
}

優點：

• JTD 支持從已有的 schema 提取 TS 類型，避免維護兩份類型定義

• 校驗庫都會提供一些常用的高級校驗規則（如日期範圍、郵箱格式等）

• JSON 格式易存儲傳輸，甚至其他語言也能用，可以做到動態下發校驗規則

缺點：

• Schema 格式有額外學習成本，JSON 寫起來太過冗長枯燥提示也不友好

實現原理：

• 類型檢查：根據 schema 規則遍歷比較數據字段

• 提取類型：結合 extends、infer、in keyof、遞歸等語法

API 形式

通過調用 API 來描述組成校驗規則，典型例子有 zod 、superstruct、io-ts，用法如下：

import { z } from "zod";

const schema = z.object({
    video_id: z.string(),
    user_info: z.object({
        user_id: z.number().positive(),
        email: z.string().email()
    }),
    image_list: z.array(z.object({
        url: z.string()
    }))
  });

type MyDataType = z.infer<typeof schema>
// type MyDataType = {
//     video_id: string;
//     user_info: {
//         user_id: number;
//         email: string;
//     };
//     image_list: {
//         url: string;
//     }[];
// }

const data: MyDataType = await fetchMyData()

const parseRes = schema.safeParse(data)
if (parseRes.error) {
    // do something
}

優點：

• 通過 API 組裝類型的形式相比 JSON 更靈活和易編寫

• 提供一些常用的高級校驗規則（如日期範圍、郵箱格式等）

• 支持從已有的 schema 提取 TS 類型，避免維護兩份類型定義

缺點：

• 有一些額外學習成本，不能直接運用我們已掌握的 TS 語法描述類型

實現原理：

和 JSON 形式類似，但實現更輕量（ajv 有 35k，zod 只有 10k）

方案 2 - 靜態 + 動態

把靜態類型和動態類型檢查寫在一起

主要是基於類屬性裝飾器來生成校驗規則，典型例子有 class-validator、typeorm，用法如下：

import 'reflect-metadata'
import { plainToClass, Type } from "class-transformer";
import { 
    validate,
    IsString,
    IsInt,
    IsEmail,
    IsObject,
    IsArray,
    ValidateNested,
} from "class-validator";

class UserInfo {
    @IsInt()
    user_id: number;
    @Length(10, 20,{message: 'name的長度不能小於10不能大於20'})
    @IsEmail()
    email: string;
}

class LargeImage {
    @IsString()
    url: string
}

class MyData {
    @IsString()
    @IsNotEmpty({message:'video_id 不能爲空'})
    video_id: string;

    @IsObject()
    @ValidateNested()
    @Type(() => UserInfo)
    user_info: UserInfo;

    @IsArray({message:'數組 不能爲空'})
    @ValidateNested({each: true})
    @Type(() => LargeImage)
    image_list: LargeImage[];
}

const data: MyData = await fetchMyData()

const dataAsClassInstance = plainToClass(
    MyData, data
);

validate(dataAsClassInstance).then(message => {
    // do something
});

優點：

• 強迫分原子類型，ORM 風格，適合服務端場景使用

• 提供一些常用的高級校驗規則（如日期範圍、郵箱格式等）

• 校驗屬性值的報錯信息可以自定義，如 @IsArray({message:'數組 不能爲空'})

缺點：

• 運行時檢查類型和 TS 類型都要寫，但寫在一塊起碼方便同步

• 校驗規則需要聲明 class，特別是有嵌套對象時，寫起來麻煩

• 只能檢查類的實例，普通對象要配合 class-transformer 轉換

實現原理：

裝飾器 + 反射（通過裝飾器給字段加入類型規則元數據，運行時再通過反射獲取這些元數據做校驗）

方案 3 - 靜態 to 動態

通過處理 TS 類型，使之在運行時可用

TS 類型自動轉換 JSON Schema

典型例子有 typescript-json-schema，用法如下：

優點：

• 不需要手動維護兩份類型定義

缺點：

• 本身不提供檢查能力，需要配合額外校驗庫

• 部分 TS 類型語法不支持轉換（如聯合類型）

• 有些規則需要另外學習它的註釋語法，寫起來也不方便

實現原理：

解析處理 TypeScript AST https://github.com/YousefED/typescript-json-schema/blob/master/typescript-json-schema.ts

編譯期從 TS 類型生成檢查代碼

在編譯期將 TS 代碼轉成類型檢查能力等價的 JS 代碼，典型例子有 typescript-is、ts-auto-guard，用法如下：

配置 ts-loader 插件：

import typescriptIsTransformer from 'typescript-is/lib/transform-inline/transformer'

...
{
    test: /.ts$/,
    exclude: /node_modules/,
    loader: 'ts-loader',
    options: {
        getCustomTransformers: program => ({
            before: [typescriptIsTransformer(program)]
        })
    }
}
...

編譯前源代碼：

import { is } from "typescript-is"

interface MyDataType {
    gid: number;
    user_info: {
        user_id: number;
        email: string;
    };
    large_image_list: {
        url: string;
    }[];
}
const data: MyDataType = fetchMyData()
const isRightType = is<MyDataType>(data)

編譯產物代碼：

Object.defineProperty(exports, "__esModule", { value: true });
const typescript_is_1 = require("typescript-is");
const data = (0, fetchMyData)();
const isRightType = (0, typescript_is_1.is)(data, object => { function _number(object) { ; if (typeof object !== "number")
    return {};
else
    return null; } function _string(object) { ; if (typeof object !== "string")
    return {};
else
    return null; } function _1(object) { ; if (typeof object !== "object" || object === null || Array.isArray(object))
    return {}; {
    if ("user_id" in object) {
        var error = _number(object["user_id"]);
        if (error)
            return error;
    }
    else
        return {};
} {
    if ("email" in object) {
        var error = _string(object["email"]);
        if (error)
            return error;
    }
    else
        return {};
} return null; } function _4(object) { ; if (typeof object !== "object" || object === null || Array.isArray(object))
    return {}; {
    if ("url" in object) {
        var error = _string(object["url"]);
        if (error)
            return error;
    }
    else
        return {};
} return null; } function sa__4_ea_4(object) { ; if (!Array.isArray(object))
    return {}; for (let i = 0; i < object.length; i++) {
    var error = _4(object[i]);
    if (error)
        return error;
} return null; } function _0(object) { ; if (typeof object !== "object" || object === null || Array.isArray(object))
    return {}; {
    if ("video_id" in object) {
        var error = _number(object["video_id"]);
        if (error)
            return error;
    }
    else
        return {};
} {
    if ("user_info" in object) {
        var error = _1(object["user_info"]);
        if (error)
            return error;
    }
    else
        return {};
} {
    if ("image_list" in object) {
        var error = sa__4_ea_4(object["image_list"]);
        if (error)
            return error;
    }
    else
        return {};
} return null; } return _0(object); });

優點：

• 使用方便，無需維護兩份類型和學習額外校驗規則，只寫 TS 代碼就行

缺點：

• 每次會生成大片檢查代碼（即使類型存在複用），導致代碼產物體積膨脹

• 校驗能力完全依賴 TS 類型檢查，不像校驗庫有一些高級規則（如日期範圍、郵箱格式等）

實現原理：

編寫 TypeScript Transformer Plugin，運行機制類似 babel 插件（源碼 -> 解析語法樹 -> 修改語法樹 -> 轉換）

提取 TS 類型信息在運行時動態檢查

典型的方案有 DeepKit，基本上是把 TS 類型系統帶到了 JS 運行時：

編譯前源代碼：

import { is } from '@deepkit/type'

interface MyDataType {
    video_id: string;
    user_info: {
        user_id: number;
        email: string;
    };
    image_list: {
        url: string;
    }[];
}
const data: MyDataType = await fetchMyData()
const isRightType = is<MyDataType>(data)

編譯產物代碼：

Object.defineProperty(exports, "__esModule", ({ value: true }));
const type_1 = __webpack_require__(/*! @deepkit/type */ "@deepkit/type");
const __ΩMyDataType = ['video_id', 'user_id', 'email', 'user_info', 'url', 'image_list', 'P&4!P&4"'4#&4$M4%P&4&MF4'M'];
const data = (0, fetchMyData)();
const isRes = (0, type_1.is)(data, undefined, undefined, [() => __ΩMyDataType, 'n!']);
console.log('deepkit', isRes);

優點：

• 使用方便，無需維護兩份類型，且提供郵箱格式等高級校驗能力

• 類型校驗規則編譯後生成的運行時代碼很少，體積不容易膨脹

缺點：

• 項目較新，還沒有被大範圍使用，穩定性未知

• 運行時的類型解釋器可能比較重，性能開銷未知

實現原理：

在編譯期將 TypeScript 類型信息轉換成字節碼（Bytecode），TS 類型信息都被完整保留到了運行時，之後在運行時用一個解釋器計算出類型信息，我們在運行時也能使用它提供的豐富 API 反射類型信息，用在如生成 Mock 數據的場景。

import { typeOf, ReflectionKind } from '@deepkit/type';

typeOf<string>(); // {kind: ReflectionKind.string}
typeOf<number>(); // {kind: ReflectionKind.number}
typeOf<boolean>(); // {kind: ReflectionKind.boolean}

typeOf<string | number>(); 
// {kind: ReflectionKind.union, types: [{kind: ReflectionKind.string}, {kind: ReflectionKind.number}]}

class MyClass {
    id: number = 0;
}
typeOf<MyClass>();
//{kind: ReflectionKind.class, classType: MyClass, types: [
//    {kind: ReflectionKind.property, name: 'id', type: {kind: ReflectionKind.number}, default: () => 0}
//]}

import { ReflectionClass } from '@deepkit/type';

class MyClass {
    id: number = 0;
    doIt(arg: string): void {}
}

const reflection = ReflectionClass.from(MyClass);
reflection.getProperty('id').type; // {kind: ReflectionKind.number}
reflection.getProperty('id').isOptional(); //false
reflection.getPropertyNames(): ['id'];

reflection.getMethod('doIt').getReturnType(); //{kind: ReflectionKind.void}
reflection.getMethod('doIt').getParameter('arg').type; //{kind: ReflectionKind.string}

//works with interfaces as well
interface User {
    id: number;
}
const reflection = ReflectionClass.from<User>();

總結

沒有十全十美的方案，綜合來看當下使用如 zod 這類 API 形式的校驗庫會比較好，既成熟強大，也兼具靈活和易。，着眼未來 deepkit 似乎很有潛力，它其實是一整套 Web 開發方案，校驗只是其中一部分，還有很多充分利用了運行時類型的功能特性。

那以後 TypeScript 會支持運行時類型檢查嗎？github 上也一直有人提相關的 issue，甚至有人專門建了一個請願頁面，但基本不太可能，因爲 design goal 中已明確表示過不會增加任何運行時代碼：

Add or rely on run-time type information in programs, or emit different code based on the results of the type system. Instead, encourage programming patterns that do not require run-time metadata.

關於我們

我們來自字節跳動，是旗下西瓜視頻前端部門，負責西瓜視頻的產品研發工作。

我們致力於分享產品內的業務實踐，爲業界提供經驗價值。包括但不限於營銷搭建、互動玩法、工程能力、穩定性、Nodejs、中後臺等方向。

歡迎關注我們的公衆號：xiguafe，閱讀更多精品文章。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/ZVogIzND-5uHm0NpI5GuDw