接口与后端对接

标准响应

除文件流外，前端期望服务端返回：

json

{
  "code": 0,
  "msg": "success",
  "data": {},
  "ui": {
    "showSuccessMessage": false,
    "successPrompt": "message",
    "errorPrompt": "message"
  }
}

当前实现以 code === 0 为业务成功，以 code === 401 为未授权。这里的 code 是响应体中的业务状态码，与 HTTP 状态码不是同一个概念。HTTP 层仍应使用语义正确的 2xx、4xx、5xx；不要始终返回 HTTP 200 后只靠业务码表达所有错误。

ui 可选，服务端返回的字段优先于 API 调用处配置。未返回的字段继续使用调用处配置。提示载体支持 message、notification、modal 或数组组合。

鉴权与续签

默认请求头：

http

Authorization: Bearer <token>

响应头若包含 VITE_NEW_TOKEN_KEY 指定的字段，前端会更新 Token。后端跨域时需通过 Access-Control-Expose-Headers 暴露该响应头。

收到 HTTP 401 或业务码 401 后，前端会防抖提示、清除 Token、重置用户状态并跳转到 /login?redirect=原地址。

定义接口

import http from '@/utils/http'
import type { PageResult } from '@/types/page-result'

export const queryListApi = (params: Record<string, unknown>) =>
  http.get<PageResult<UserRow>>({
    url: '/api/users',
    params,
  })

export const createApi = (data: UserForm) =>
  http.post<void>({
    url: '/api/users',
    data,
    showSuccessMessage: true,
  })

也可以使用 http.request 显式传入 method。API 函数应返回 data 的业务类型，而不是让页面感知 AxiosResponse。

请求行为

配置	默认行为
`dedup`	`true`；相同 method、service、URL、params、data 的并发请求复用 Promise
`cancelOnRouteChange`	`true`；切页时取消仍在进行的请求
`retries`	GET 遇超时或 5xx 重试 2 次；写请求不重试
`showLoading`	`false`；可选消息条或全屏遮罩
`showErrorMessage`	默认显示统一错误提示
`showSuccessMessage`	默认不显示，写接口可显式开启
`service`	`default`，使用主 API 地址并携带 Token

包含 File 或 Blob 的对象会自动转换为 FormData，数组使用 key[i]、嵌套对象使用 key[child]。文件下载需要设置 responseType: 'blob' 或 arraybuffer，此时不解析标准响应信封。

多后端服务

在 src/utils/http/services.ts 注册服务：

export const apiServices = {
  default: { baseURL: env.VITE_API_URL, withToken: true },
  file: { baseURL: env.VITE_API_URL_FILE, withToken: true },
  external: { baseURL: env.VITE_API_URL_EXTERNAL, withToken: false },
}

调用时传 service: 'file'。第三方域名务必设置 withToken: false，防止泄露本系统凭据。

后端最小接口集合

要完成登录和框架初始化，至少实现：

登录：返回访问 Token（可放在 data，再由登录逻辑保存）。
当前用户详情：昵称、账号、头像、邮箱、手机等。
当前用户菜单：路由、组件、显示属性和操作码。
当前用户角色 ID。
系统信息：标题、Logo、备案等。
全量字典：按字典类型分组。
密码校验：用于锁屏登录密码解锁。

已知接入点

项目当前 queryRoleIdsApi 的 URL 指向了 query-menu-list.json，真实接入前应改为 api/info/query-role-ids 对应接口。演示 CRUD 也统一使用 GET，生产接入时必须调整为正确 HTTP 方法。

接口与后端对接 ​

标准响应 ​

鉴权与续签 ​

定义接口 ​

请求行为 ​

多后端服务 ​

后端最小接口集合 ​