如何在gcloud functions中正确处理请求参数类型安全

gcloud functions的HTTP触发器默认使用Express的Request/Response类型，原生支持通过泛型自定义params/body/query的类型，不需要额外依赖就能实现编译阶段的类型安全。

基础用法：通过泛型指定参数类型 #

Express的Request类型接收4个泛型参数，顺序固定为：
Request<路径参数Params类型, 响应体类型, 请求体Body类型, 查询参数Query类型>

针对示例中的req.query场景，实现步骤如下：

1. 先定义查询参数对应的类型结构，注意：query和path params默认解析结果都是字符串类型，不要直接定义为number/boolean，避免类型和运行时实际值不符：

   type CreateUsersQuery = {
     email: string;
     nDevices: string;
     role: string;
     isAdmin: string;
     userLvl: string;
   }
   

2. 将定义好的类型传入Request泛型对应位置，替换默认的宽松ParsedQs类型：

   import * as functions from "@google-cloud/functions-framework";
   import type { Request, Response } from "express";
   
   export const createUsers = functions.http("createUsers", async (
     req: Request<{}, any, any, CreateUsersQuery>,
     res: Response
   ) => {
     // 此处解构出的字段会自动推导为你定义的string类型，获得完整类型提示
     const {
       email,
       nDevices,
       role,
       isAdmin,
       userLvl,
     } = req.query;
   
     // 需要数字/布尔类型时，显式做转换即可
     const parsedNDevices = Number(nDevices);
     const parsedIsAdmin = isAdmin === "true";
   });
   

多场景扩展：同时定义params/body类型 #

如果接口同时需要路径参数、请求体的类型提示，只需要按泛型顺序传入对应类型即可，示例：

// 路径参数类型
type UserDetailParams = {
  userId: string;
}
// POST请求体类型
type UpdateUserBody = {
  nickname: string;
  tags: string[];
}
// 查询参数类型
type UserDetailQuery = {
  withStats: string;
}

// 传入对应泛型后，req.params/req.body/req.query都会获得对应类型提示
req: Request<UserDetailParams, any, UpdateUserBody, UserDetailQuery>

注意事项 #

• TypeScript类型仅在编译阶段生效，无法拦截非法的请求入参，生产环境建议补充简单的运行时校验，比如校验必填字段是否存在、格式是否合法，校验不通过直接返回400错误，避免非法参数导致业务逻辑报错：

  if (!email || !email.includes("@")) {
    res.status(400).send("email参数非法");
    return;
  }
  if (isNaN(parsedNDevices)) {
    res.status(400).send("nDevices必须为合法数字");
    return;
  }
  

• 不要直接给query/params字段定义number/boolean类型，Express默认的query解析器不会自动做类型转换，直接写这类类型会导致编译类型和运行时实际值不一致，埋下隐患。

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