使用 TypeScript 进行类型安全的 API 调用：综合指南

在现代 Web 开发中，与 API 交互是一项基本任务。 TypeScript 凭借其强大的类型系统，在通过实现类型安全的 API 调用来确保应用程序的可靠性和可维护性方面具有显着的优势。 本指南将探讨如何利用 TypeScript 的功能来构建健壮且无错误的 API 交互，涵盖最佳实践、高级技术和实际示例。

为什么类型安全对 API 调用很重要

使用 API 时，您本质上是在处理来自外部源的数据。 此数据可能并不总是您期望的格式，从而导致运行时错误和意外行为。 类型安全提供了一层关键保护，通过验证您收到的数据是否符合预定义的结构，从而在开发过程的早期捕获潜在问题。

• 减少运行时错误：编译时的类型检查有助于在发布之前识别和修复与类型相关的错误。
• 提高代码可维护性：清晰的类型定义使您的代码更易于理解和修改，从而降低了在重构过程中引入错误的风险。
• 增强代码可读性：类型注释提供了宝贵的文档，使开发人员更容易理解预期的数据结构。
• 更好的开发者体验：IDE 对类型检查和自动完成的支持显着提高了开发人员体验，并降低了出错的可能性。

设置您的 TypeScript 项目

在深入研究 API 调用之前，请确保您已设置好 TypeScript 项目。 如果您是从头开始，可以使用以下命令初始化一个新项目：

npm init -y
npm install typescript --save-dev
tsc --init

这将创建一个带有默认 TypeScript 编译器选项的 `tsconfig.json` 文件。 您可以自定义这些选项以满足您项目的需求。 例如，您可能希望启用严格模式以进行更严格的类型检查：

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

为 API 响应定义类型

实现类型安全的 API 调用的第一步是定义 TypeScript 类型，这些类型表示您期望从 API 接收的数据的结构。 这通常使用 `interface` 或 `type` 声明来完成。

使用接口

接口是定义对象形状的强大方法。 例如，如果您从 API 获取用户列表，则可以定义如下接口：

interface User {
  id: number;
  name: string;
  email: string;
  address?: string; // 可选属性
  phone?: string; // 可选属性
  website?: string; // 可选属性
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
}

属性名称后的 `?` 表示该属性是可选的。 这对于处理某些字段可能缺失的 API 响应很有用。

使用类型

类型与接口类似，但提供了更大的灵活性，包括定义联合类型和交叉类型的能力。 您可以使用类型实现与上述接口相同的结果：

type User = {
  id: number;
  name: string;
  email: string;
  address?: string; // 可选属性
  phone?: string; // 可选属性
  website?: string; // 可选属性
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
};

对于简单的对象结构，接口和类型通常可以互换。 但是，在处理更复杂的情况时，类型会变得更加强大。

使用 Axios 进行 API 调用

Axios 是一个流行的 HTTP 客户端，用于在 JavaScript 和 TypeScript 中进行 API 请求。 它提供了一个清晰直观的 API，使您可以轻松处理不同的 HTTP 方法、请求标头和响应数据。

安装 Axios

npm install axios

进行类型化的 API 调用

要使用 Axios 进行类型安全的 API 调用，您可以使用 `axios.get` 方法，并使用泛型指定预期的响应类型：

import axios from 'axios';

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('获取用户时出错:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

在此示例中，`axios.get('...')` 告诉 TypeScript，响应数据应为 `User` 对象数组。 这允许 TypeScript 在处理响应数据时提供类型检查和自动完成功能。

处理不同的 HTTP 方法

Axios 支持各种 HTTP 方法，包括 `GET`、`POST`、`PUT`、`DELETE` 和 `PATCH`。 您可以使用相应的方法进行不同类型的 API 请求。 例如，要创建新用户，您可以使用 `axios.post` 方法：

async function createUser(user: Omit): Promise {
  try {
    const response = await axios.post('https://jsonplaceholder.typicode.com/users', user);
    return response.data;
  } catch (error) {
    console.error('创建用户时出错:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Leading the way',
    bs: 'Innovative solutions'
  }
};

createUser(newUser).then(user => {
  console.log('创建用户:', user);
});

在此示例中，`Omit` 创建了一个类型，该类型与 `User` 相同，但没有 `id` 属性。 这很有用，因为 `id` 通常在创建新用户时由服务器生成。

使用 Fetch API

Fetch API 是一个内置的 JavaScript API，用于进行 HTTP 请求。 虽然它比 Axios 更基础，但也可以与 TypeScript 一起使用以实现类型安全的 API 调用。 如果它符合您的需求，您可能更喜欢它，以避免添加依赖项。

使用 Fetch 进行类型化的 API 调用

要使用 Fetch 进行类型安全的 API 调用，您可以使用 `fetch` 函数，然后将响应解析为 JSON，指定预期的响应类型：

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP 错误！ 状态：${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('获取用户时出错:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

在此示例中，`const data: User[] = await response.json();` 告诉 TypeScript 响应数据应被视为 `User` 对象数组。 这允许 TypeScript 执行类型检查和自动完成。

使用 Fetch 处理不同的 HTTP 方法

要使用 Fetch 进行不同类型的 API 请求，您可以使用带有不同选项的 `fetch` 函数，例如 `method` 和 `body` 选项。 例如，要创建新用户，您可以使用以下代码：

async function createUser(user: Omit): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(user)
    });
    if (!response.ok) {
      throw new Error(`HTTP 错误！ 状态：${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('创建用户时出错:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Leading the way',
    bs: 'Innovative solutions'
  }
};

createUser(newUser).then(user => {
  console.log('创建用户:', user);
});

处理 API 错误

错误处理是 API 调用的一个关键方面。 API 可能会因多种原因而失败，包括网络连接问题、服务器错误和无效请求。 妥善处理这些错误对于防止您的应用程序崩溃或显示意外行为至关重要。

使用 Try-Catch 块

处理异步代码中错误的最常见方法是使用 try-catch 块。 这允许您捕获在 API 调用期间抛出的任何异常并适当地处理它们。

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('获取用户时出错:', error);
    // 处理错误，例如，向用户显示错误消息
    throw error; // 重新抛出错误，以便调用代码也能处理它
  }
}

处理特定错误代码

API 经常返回特定的错误代码以指示发生的错误类型。 您可以使用这些错误代码来提供更具体的错误处理。 例如，您可能希望为 404 Not Found 错误显示与 500 Internal Server Error 不同的错误消息。

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      console.log(`未找到 ID 为 ${id} 的用户。`);
      return null; // 或抛出一个自定义错误
    } else {
      console.error('获取用户时出错:', error);
      throw error;
    }
  }
}

创建自定义错误类型

对于更复杂的错误处理方案，您可以创建自定义错误类型来表示不同类型的 API 错误。 这允许您提供更结构化的错误信息并更有效地处理错误。

class ApiError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
    this.name = 'ApiError';
  }
}

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      throw new ApiError(404, `未找到 ID 为 ${id} 的用户。`);
    } else {
      console.error('获取用户时出错:', error);
      throw new ApiError(500, 'Internal Server Error'); //或任何其他合适的 HTTP 状态码
    }
  }
}

数据验证

即使使用 TypeScript 的类型系统，在运行时验证您从 API 接收的数据也至关重要。 API 可能会在没有通知的情况下更改其响应结构，并且您的 TypeScript 类型可能并不总是与 API 的实际响应完全同步。

使用 Zod 进行运行时验证

Zod 是一个流行的 TypeScript 库，用于运行时数据验证。 它允许您定义描述数据预期结构的模式，然后在运行时根据这些模式验证数据。

安装 Zod

npm install zod

使用 Zod 验证 API 响应

要使用 Zod 验证 API 响应，您可以定义一个对应于您的 TypeScript 类型的 Zod 模式，然后使用 `parse` 方法来验证数据。

import { z } from 'zod';

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  address: z.string().optional(),
  phone: z.string().optional(),
  website: z.string().optional(),
  company: z.object({
    name: z.string(),
    catchPhrase: z.string(),
    bs: z.string(),
  }).optional(),
});

type User = z.infer;

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    const data = z.array(userSchema).parse(response.data);
    return data;
  } catch (error) {
    console.error('获取用户时出错:', error);
    throw error;
  }
}

在此示例中，`z.array(userSchema).parse(response.data)` 验证响应数据是否是符合 `userSchema` 的对象数组。 如果数据不符合模式，Zod 将抛出错误，然后您可以适当地处理该错误。

高级技术

使用泛型实现可重用的 API 函数

泛型允许您编写可重用的 API 函数，这些函数可以处理不同类型的数据。 例如，您可以创建一个通用 `fetchData` 函数，该函数可以从任何 API 终点获取数据，并以正确的类型返回它。

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`从 ${url} 获取数据时出错:`, error);
    throw error;
  }
}

使用拦截器进行全局错误处理

Axios 提供了拦截器，允许您在代码处理请求和响应之前拦截它们。 您可以使用拦截器来实现全局错误处理，例如记录错误或向用户显示错误消息。

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('全局错误处理程序:', error);
    // 向用户显示错误消息
    return Promise.reject(error);
  }
);

使用环境变量进行 API URL

为了避免在代码中硬编码 API URL，您可以使用环境变量来存储 URL。 这使得更容易为不同的环境（例如开发、过渡和生产）配置您的应用程序。

使用 `.env` 文件和 `dotenv` 包的示例。

// .env
API_URL=https://api.example.com

// 安装 dotenv
npm install dotenv

// 导入并配置 dotenv
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // 提供一个默认值

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`从 ${apiUrl}/${endpoint} 获取数据时出错:`, error);
    throw error;
  }
}

结论

类型安全的 API 调用对于构建健壮、可维护且无错误的 Web 应用程序至关重要。 TypeScript 提供了强大的功能，使您能够为 API 响应定义类型、在运行时验证数据并妥善处理错误。 通过遵循本指南中概述的最佳实践和技术，您可以显着提高 API 交互的质量和可靠性。

通过使用 TypeScript 和 Axios 和 Zod 等库，您可以确保您的 API 调用是类型安全的，您的数据已验证，并且您的错误已得到妥善处理。 这将带来更强大且可维护的应用程序。

请记住始终在运行时验证您的数据，即使使用 TypeScript 的类型系统。 API 可能会更改，并且您的类型可能并不总是与 API 的实际响应完全同步。 通过在运行时验证您的数据，您可以在问题在您的应用程序中引起问题之前捕获潜在问题。

祝您编码愉快！