如何在TypeScript中解析POST请求体并捕获类型不匹配错误

问题背景 #

我们的后端API期望请求体符合以下TypeScript类型：

type taskslistrequest = {
    clientgroupcode: string[];
    startindex: number;
    pagesize: number;
}

当前解析请求体的代码为：

const tasklistreq: taskslistrequest = req.body.taskslistrequest as taskslistrequest;

但通过Postman发送如下请求体时，TypeScript并未抛出错误：

{
    "taskslistrequest": {
        "clientgroupcode": [
            "AAB",
            "AAC",
            "AAD"
        ],
        "startindex": "0",
        "pagesize": "50"
    }
}

需要实现解析请求体时捕获类型不匹配的问题，使用的技术版本：

• TypeScript 5.3.3
• NodeJS 20.10.0
• Express 4.18.2

问题原因 #

TypeScript的类型断言（as）仅在编译阶段起作用，编译后的JavaScript代码会丢失所有类型信息。而请求体是JSON格式，解析后startindex和pagesize会被识别为字符串类型，TypeScript无法在运行时自动校验这些类型是否符合定义，因此不会报错。

解决方案 #

方案1：手动编写校验函数 #

编写运行时校验函数，逐个检查字段的类型是否符合要求，不符合则抛出错误：

function validateTasksListRequest(data: unknown): data is taskslistrequest {
    if (!data || typeof data !== 'object') return false;
    
    const req = data as taskslistrequest;
    return (
        // 校验clientgroupcode是字符串数组
        Array.isArray(req.clientgroupcode) &&
        req.clientgroupcode.every(item => typeof item === 'string') &&
        // 校验startindex和pagesize是数字类型
        typeof req.startindex === 'number' &&
        typeof req.pagesize === 'number'
    );
}

// 使用示例
const rawRequest = req.body.taskslistrequest;
if (!validateTasksListRequest(rawRequest)) {
    throw new Error('请求体格式错误：startindex和pagesize必须为数字类型');
}
const tasklistreq: taskslistrequest = rawRequest;

方案2：使用Schema校验库（推荐） #

借助Zod、Joi等库实现编译时+运行时的双重校验，代码更简洁且扩展性更强。以Zod为例：

1. 先安装Zod：

npm install zod

2. 定义Schema并校验：

import { z } from 'zod';

// 定义Schema，同时生成对应的TypeScript类型
const TasksListRequestSchema = z.object({
    clientgroupcode: z.array(z.string()),
    startindex: z.number(),
    pagesize: z.number(),
});

type taskslistrequest = z.infer<typeof TasksListRequestSchema>;

// 解析并校验请求体
try {
    const tasklistreq = TasksListRequestSchema.parse(req.body.taskslistrequest);
    // 校验通过，继续业务逻辑
} catch (error) {
    throw new Error(`请求体格式错误：${error.message}`);
}

内容的提问来源于stack exchange，提问作者Ranjeet