TypeScript 项目中基于 Axios 的后端接口封装实战

作者：后端茶话时间：2026-10-31 11:15:01浏览：328

本文详细记录在 TypeScript 项目中封装 Axios 的全过程。从定义全局配置与认证逻辑入手，通过创建 ApiClient 类统一处理请求拦截、错误处理及 401 跳转。结合统一返回值接口 ApiResponse，实现类型安全的接口调用，并提供具体服务层示例，提升代码可维护性与开发体验。

前言

原本计划发布 Next.js 开发笔记，但考虑到内容涉及面较广，决定将其拆分并单独整理发布。

本文主要记录在 TypeScript 项目中封装 Axios 的具体过程。此前在开发 StarBlog-Admin 时已进行过类似封装，但当时使用的是 JavaScript，与 TypeScript 的实现细节存在差异。

此外，在参考 Next.js 官方文档时，注意到推荐使用 @tanstack/react-query 来封装请求类操作。简要阅读文档后认为该方案效果良好，后续将在项目中加以实践。

定义配置

首先创建一个全局配置文件 src/utilities/global.ts。

export default class Global {
  static baseUrl = process.env.NEXT_PUBLIC_BASE_URL
}

在 Next.js 项目中，可直接利用 Next 规定的环境变量；其他类型的项目可根据实际情况进行相应调整。

封装认证逻辑

认证部分虽与 Axios 关联不大，但由于在 Axios 封装中需要调用相关逻辑，因此一并在此展示。

创建 src/utilities/auth.ts 文件。

/**
 * 登录信息
 */
export interface LoginProps {
  token: string
  username: string
  expiration: string
}

/**
 * 认证授权工具类
 */
export default abstract class Auth {
  static get storage(): Storage | null {
    if (typeof window !== 'undefined') {
      return window.localStorage
    }
    return null
  }

  /**
     * 检查是否已登录
     * @return boolean
     */
  public static isLogin() {
    let token = this.storage?.getItem('token')
    let userName = this.storage?.getItem('user')

    if (!token || token.length === 0) return false
    if (!userName || userName.length === 0) return false
    return !this.isExpired();
  }

  /**
     * 检查登录是否过期
     * @return boolean
     */
  public static isExpired = () => {
    let expiration = this.storage?.getItem('expiration')
    if (expiration) {
      let now = new Date()
      let expirationTime = new Date(expiration)
      if (now > expirationTime) return true
    }

    return false
  }

  /**
     * 读取保存的token
     * @return string
     */
  public static getToken = () => {
    return this.storage?.getItem('token')
  }

  /**
     * 保存登录信息
     * @param props
     */
  public static login = (props: LoginProps) => {
    this.storage?.setItem('token', props.token)
    this.storage?.setItem('user', props.username)
    this.storage?.setItem('expiration', props.expiration)
  }

  /**
     * 注销
     */
  public static logout = () => {
    this.storage?.removeItem('token')
    this.storage?.removeItem('user')
    this.storage?.removeItem('expiration')
  }
}

所有与认证相关的逻辑均封装在 Auth 类中。

为了在 Next.js 环境中顺畅运行，需进行特殊处理，例如增加 storage 属性，并在读取时先判断 window 是否存在。

封装 Axios

所有 API 相关的代码均存放于 src/services 目录下。

创建 src/services/api.ts 文件，由于代码较长，将分块介绍。可以看到，相比之前的 JavaScript 版本，此处增加了更多配置项，这对 IDE 的自动补全功能非常友好。

先进行导入操作。

import axios, {AxiosInstance, AxiosRequestConfig, AxiosResponse, CreateAxiosDefaults} from "axios";
import Global from '@/utilities/global'
import Auth from "@/utilities/auth";

Axios 配置

定义 Axios 的基础配置。

const config: CreateAxiosDefaults<any> = {
  method: 'get',
  // 基础url前缀
  baseURL: `${Global.baseUrl}/`,
  // 请求头信息
  headers: {
    'Content-Type': 'application/json;charset=UTF-8'
  },
  // 参数
  data: {},
  // 设置超时时间
  timeout: 10000,
  // 携带凭证
  withCredentials: true,
  // 返回数据类型
  responseType: 'json'
}

统一接口返回值

设置统一的接口返回值格式，这与我在 StarBlog 后端中封装的标准一致，目前已成为我编写后端的标准返回值规范。同时，已发布 CodeLab.Share NuGet 包，可快捷引入该统一返回值组件。

// 统一接口返回值
export interface ApiResponse {
  data: any
  errorData: any
  message: string
  statusCode: number
  successful: boolean
}

定义 `ApiClient`

最后定义了 ApiClient 类，其设计思路有点模仿 C# 中 HttpClient 的风格。

该实现中使用了 Axios 的拦截器：发起请求时在 Header 中添加认证信息；返回时检查是否存在错误，若状态码为 401 unauthorized，则跳转至登录页面。

export class ApiClient {
  private readonly api: AxiosInstance
  constructor() {
    this.api = axios.create({
      ...config,
    })
    this.api.interceptors.request.use(
      config => {
        config.headers.Authorization = `Bearer ${Auth.getToken()}`
        return config
      },
      error => {
        return error
      })
    this.api.interceptors.response.use(
      response => {
        return response
      },
      error => {
        let reason = error
        if (error && error.response) {
          if (error.response.data) {
            reason = error.response.data
            if (!reason.message) reason.message = error.message
          }
          if (error.response.status === 401) {
            location.href = '/login'
          }
        }
        return Promise.reject(reason)
      }
    )
  }
  public request(options: AxiosRequestConfig): Promise<ApiResponse> {
    return new Promise((resolve, reject) => {
      this.api(options).then((res: AxiosResponse<ApiResponse>) => {
        resolve(res.data)
        return false
      }).catch(error => {
        reject(error)
      })
    })
  }
}
export const api = new ApiClient()
export default api

相比之前在 StarBlog-Admin 中的实现，代码更为简洁，旨在以较少的代码实现所需功能。

编写具体接口调用

所有接口调用均编写为 Service 形式（基于后端开发思维）。

此处以发送短信接口为例进行说明。

创建 src/services/common.ts 文件，从之前定义的 api.ts 中引入 ApiClient 的对象，直接调用 request 方法即可完成调用。

参数类型为 AxiosRequestConfig，不对 Axios 本身做额外修改，这种实现方式感觉比之前使用 Antd Pro 魔改的接口更加舒适。

import {api} from './api'
export class SmsChannel {
  static local = 0
  static aliyun = 1
  static tencent = 2
}
export default abstract class CommonService {
  public static getSmsCode(phone: string, channel: number = SmsChannel.local) {
    return api.request({
      url: `api/common/getSmsCode`,
      params: {phone, channel}
    })
  }
}