# 接口统一管理与类型定义

URL: https://caijiao.org/axios/best-practices/interface-manage
Source: docs/axios/best-practices/interface-manage.md
Description: 本章节介绍如何在前端项目中使用 Axios 统一管理接口请求，包括接口模块化、统一封装、请求类型定义、TypeScript 类型约束、接口文档维护及调用规范化。通过统一管理接口，提高代码可维护性、减少重复代码，并增强开发效率与项目可扩展性。

在大型项目中，接口众多且分散，容易出现重复请求、参数混乱或类型错误。
通过统一管理接口和使用类型定义，可以提升前端代码的可维护性和稳定性。

## 一、为什么需要统一管理接口

* 减少重复代码，提高可复用性；
* 易于维护接口变更；
* 支持统一拦截器和错误处理；
* 在团队协作中确保调用规范和类型安全。

## 二、接口模块化设计

将接口按功能模块划分，例如：

```txt
/api
  ├─ user.js
  ├─ product.js
  └─ order.js
```

每个模块负责封装相关接口请求：

```js
// api/user.js
import axios from "../axios-instance";

export function getUserList(params) {
  return axios.get("/users", { params });
}

export function createUser(data) {
  return axios.post("/users", data);
}
```

## 三、统一封装请求方法

创建 `request.js` 统一处理 Axios 请求：

```js
import axios from "./axios-instance";

export function request(config) {
  return axios(config)
    .then(res => res.data)
    .catch(err => Promise.reject(err));
}
```

调用模块：

```js
import { request } from "./request";
request({ url: "/users", method: "get", params: { page: 1 } });
```

## 四、TypeScript 类型定义（可选）

使用 [TypeScript](/ts/) 为请求和响应定义类型：

```ts
// types/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
}

export interface GetUserListResponse {
  users: User[];
  total: number;
}
```

在接口调用中引用类型：

```ts
import { GetUserListResponse } from "../types/user";

async function fetchUsers() {
  const res: GetUserListResponse = await request({ url: "/users", method: "get" });
  console.log(res.users);
}
```

## 五、接口文档维护

* 建议统一维护接口文档（如 swagger、YAPI）；
* 每个接口模块应附带请求方法、参数说明和返回值类型；
* 保证团队成员调用接口时可以快速理解和使用。

## 六、小结

统一管理接口和类型定义可以：

* 提升前端请求逻辑规范化；
* 增强可维护性和可扩展性；
* 与拦截器、缓存策略结合使用，可进一步优化请求流程；
* 对 TypeScript 项目，提供强类型约束，降低运行时错误。