如何让 fetch 变得类型安全

11 months ago
Coding
xLogBack

前言

fetch("https://jsonplaceholder.typicode.com/todos/1")
  .then((response) => response.json())
  .then((json) => console.log(json));

当你直接使用如上的代码来发起网络请求时,你会发现你的 IDE 无法给你提供任何关于 json 的类型提示。这很合理,没人知道这个接口会返回什么格式的数据。于是你需要进行如下几个步骤:

  1. 手动测试这个接口,获取返回值
  2. 根据返回值的内容,利用如 transform.tools 之类的工具生成对应的类型定义
  3. 将类型定义复制到你的项目中
  4. 使用 as 来标识返回值的类型

这样下来你也只是能获得接口正常返回时 json 的类型而已,还有很多问题需要被解决:

  1. 手动请求得到返回值不够准确,比如调用接口出错时,返回值的类型可能会发生变化
  2. 请求的 url 和输入的参数没有任何类型提示
  3. 当后端接口变动时,tsc 无法给出报错

解决方案的基础

ts 中有个非常好用的功能是 as const 断言,给变量添加这个断言后,变量的类型会被推断为更具体的字面量类型,同时会禁止对变量的修改。下面是一个简单的例子,可以看到 navigateTo 这个函数的参数变的更加安全了,我们不能传递一个未被定义的路由名称字符串。

const routes = {
  home: "/",
  about: "/about",
} as const;

declare function navigateTo(route: keyof typeof routes): void;

navigateTo("404");
// Argument of type '"404"' is not assignable to parameter of type '"home" | "about"'.

这就是我们能实现类型安全的 fetch 的基础。

定义路由结构

首先我们需要定义一个路由结构,这个结构包含了一个接口的全部必要信息(请求路径,输入,输入,以及可能出现的错误码)。同时这里我们使用 zod 来进行运行时的数据格式校验。

// add.ts
import { z } from "zod";

export const path = "/add" as const;

export const input = z.object({
  a: z.number(),
  b: z.number(),
});

export const data = z.object({
  result: z.number(),
});

export const errCode = ["NO_LOGIN"] as const;

定义多个接口之后,在 index.ts 中导出所有的接口。

// index.ts
export * as Add from "./add";

然后我们就能拿到全部的路由信息

import * as routesWithoutPrefixObj from "./interface/index";

const routesWithoutPrefix = Object.values(
  routesWithoutPrefixObj
) as ValueOfObjectArray<typeof routesWithoutPrefixObj>;

定义公共类型

定义通用返回结构,公共前缀和未知错误码。我们并不是接口直接返回数据,而是返回一个包含了错误码和数据的对象。

const routesWithoutPrefix = Object.values(
  routesWithoutPrefixObj
) as ValueOfObjectArray<typeof routesWithoutPrefixObj>;

export const prefix = "/api";
export type Prefix = typeof prefix;
export const unknownError = "UNKNOWN_ERROR" as const;

export type OutputType<T, Err extends readonly string[]> =
  | {
      err: ArrayToUnion<Err> | typeof unknownError;
      data: null;
    }
  | {
      err: null;
      data: T;
    };

计算出带前缀的实际路由

export const routes = routesWithoutPrefix.map((r) => {
  return {
    ...r,
    path: `${prefix}${r.path}`,
  };
}) as unknown as AddPathPrefixForRoutes<typeof routesWithoutPrefix>;

转换路由结构

到此为止,我们只是拿到了全部路由对象组成的数组,这对于我们实现类型安全的 fetch 来说并不方便。我们需要将这个数组转换成一个对象,这个对象的 key 是路由的请求路径,value 是路由的其它信息。如此,调用 fetch 时,我们就能获得更好的补全体验,在输入确定的路径之后,能得到正确的输入类型和输出类型。

type RouteItem = {
  readonly path: string;
  input: z.AnyZodObject;
  data: z.AnyZodObject;
  errCode: readonly string[];
};

type Helper<T> = T extends RouteItem
  ? Record<
      T["path"],
      {
        input: z.infer<T["input"]>;
        data: z.infer<T["data"]>;
        errCode: T["errCode"];
        output: OutputType<z.infer<T["data"]>, T["errCode"]>;
      }
    >
  : never;

export type DistributedHelper<T> = T extends RouteItem ? Helper<T> : never;

export type Route = UnionToIntersection<
  DistributedHelper<ArrayToUnion<typeof routes>>
>;

如此我们就能得到最终包含全部路由信息的类型 Route,这个类型的大致结构如下:

type Route = Record<"/api/add", {
    input: {
        a: number;
        b: number;
    };
    data: {
        result: number;
    };
    errCode: readonly ["NO_LOGIN"];
    output: OutputType<{
        result: number;
    }, readonly ["NO_LOGIN"]>;
}> & Record<"/api/dataSet/delDataSet", {
    ...;
}> & ... 13 more ... & Record<...>

为 fetch 添加类型

可以看到,只需要约束 fetch 的第一个参数 path 为 keyof Route,第二个参数为对应路由的输入类型,就能得到正确的输出类型。为了实现上的简单,所有的 http 请求都使用 POST 方法,所有的输入参数都从 body 中传递。

export const myFetch = async <Path extends keyof Route>(
  path: Path,
  input: Route[Path]["input"]
) => {
  try {
    const res = await fetch(path, {
      method: "POST",
      headers: headers,
      body: input instanceof FormData ? input : JSON.stringify(input),
    });
    const data = await (res.json() as Promise<Route[Path]["output"]>);
    if (data.err) {
      throw new CustomError(data.err);
    }
    return data.data as Route[Path]["data"];
  } catch (err) {
    if (err instanceof CustomError) {
      throw err;
    }

    if (err instanceof Error) {
      throw new CustomError(err.message);
    }

    throw new CustomError(unknownError);
  }
};

class CustomError<T extends string> extends Error {
  errorCode: T;

  constructor(msg: string) {
    super(msg);
    Object.setPrototypeOf(this, CustomError.prototype);
    this.errorCode = msg as T;
  }
}

nice,让我们来看看使用效果吧。

ScreenShot 2023-08-09 12.38.53.gif

最后

文章写到这里就算是结束了,取决你自己的需求,你还可以做如下事情:

  1. 将它和 useSWR 组合起来,这样你就不必为每个网络接口单独封装函数了
  2. 在 fetch 中封装更多逻辑,比如自动携带登录所需的 token 和在登录状态过期时自动的路由拦截
  3. 单独处理非 json 交互的接口,比如文件上传下载
  4. 说服你的后端,让它用 ts 来给你写接口,这样这些路由定义就不需要你手动写了,也更安全

如果你感谢兴趣,以下是一些被用到但是没有在文章中展开的类型计算。当然,这份实现未必是最好的,如果你有任何改进的想法,欢迎与我讨论,非常感谢。

export type ValueOfObjectArray<
  T,
  RestKey extends unknown[] = UnionToTuple<keyof T>
> = RestKey extends []
  ? []
  : RestKey extends [infer First, ...infer Rest]
  ? First extends keyof T
    ? [T[First], ...ValueOfObjectArray<T, Rest>]
    : never
  : never;

// https://github.com/type-challenges/type-challenges/issues/2835
type LastUnion<T> = UnionToIntersection<
  T extends any ? (x: T) => any : never
> extends (x: infer L) => any
  ? L
  : never;

type UnionToTuple<T, Last = LastUnion<T>> = [T] extends [never]
  ? []
  : [...UnionToTuple<Exclude<T, Last>>, Last];

type AddPrefix<T, P extends string = ""> = T extends RouteItem
  ? {
      path: `${P}${T["path"]}`;
      input: T["input"];
      data: T["data"];
      errCode: T["errCode"];
    }
  : never;

export type AddPrefixForArray<Arr> = Arr extends readonly []
  ? []
  : Arr extends readonly [infer A, ...infer B]
  ? [AddPrefix<A, Prefix>, ...AddPrefixForArray<B>]
  : never;

export type DistributedHelper<T> = T extends RouteItem ? Helper<T> : never;

export type ArrayToUnion<T extends readonly any[]> = T[number];

export type UnionToIntersection<U> = (
  U extends any ? (k: U) => void : never
) extends (k: infer I) => void
  ? I
  : never;

Comments

Comment send here will be anonymous, you can login your account in xLog and comment there.

Theme

Accent color

Gray color

Appearance

Radius

Scaling

Panel background