接口联调

本文面向需要完成前后端联调、定位接口异常或扩展业务接口的研发人员。重点不是列出接口地址，而是说明完整联调链路：

• 接口地址从哪里来
• Token 是谁加上的
• 刷新令牌是谁处理的
• 请求签名是什么时候加上的
• 某个接口报错时应该从前端哪一层查起

一条请求大致会经过哪些层

页面 / 组件
  -> src/api/*.ts
  -> src/utils/http/index.ts
  -> /api/v1/**
  -> art-design-pro-server

理解这条链路后，可以把接口问题定位到页面、接口封装、请求层、代理规则或后端服务中的具体环节。

开发环境的请求入口

开发环境下最关键的变量是：

VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13000

因此浏览器里看到的请求路径通常是相对路径，而实际由 Vite 代理到后端 13000 端口。

请求层已经帮你做了什么

src/utils/http/index.ts 已经统一处理了以下能力：

• 自动携带 Authorization: Bearer <token>
• 已登录请求自动追加 API 安全头
• 统一 JSON 请求处理
• 统一错误提示
• 401 时尝试刷新 Access Token
• 刷新失败时触发未授权处理

所以业务代码里通常只需要关心：

• 调哪个接口
• 传什么参数
• 是否要跳过接口安全
• 是否要静默处理某类错误

典型接口前缀

商业版后端统一走：

/api/v1

常见示例：

• 登录：/api/v1/auth/signin
• 刷新：/api/v1/auth/refresh
• 当前用户：/api/v1/user/info

登录与刷新链路

登录时

前端会：

1. 调用登录接口
2. 接收 Access Token
3. 后续请求自动带上 Bearer Token

刷新页面时

前端会尝试：

1. 用 Refresh Token 恢复 Access Token
2. 恢复成功后重新获取用户信息
3. 再继续初始化菜单和路由

因此，刷新页面后登录状态失效通常需要优先排查鉴权链路，而不是直接修改业务页面。

已登录请求签名

商业版前端除 Bearer Token 外，还可能附加 API 安全头，用于：

• 防止简单重放
• 增强请求校验
• 提升开放环境下的安全性

如果某个接口本身属于登录、刷新等特殊场景，前端会显式跳过这部分逻辑。

站点配置接入方式

前端启动后会调用公开站点配置接口，并把后端返回的数据合并到前端默认展示值里。

这会影响：

• 站点名称
• 欢迎文案
• SEO 标题
• 水印文本
• 是否允许注册

所以遇到“文案明明改了却没生效”，优先查的是站点配置接口，而不是先怀疑页面组件。

推荐的接口排查顺序

1. 先看浏览器网络请求

重点确认：

• URL 是否正确
• 是否走到了 /api/v1
• 请求头里是否有 Token
• 返回码是 401、403 还是 500

2. 再看请求封装配置

重点确认：

• 是否被 skipApiSecurity
• 是否触发了刷新令牌
• 是否被静默错误处理吞掉了提示

3. 最后再看业务页面

不要直接把所有异常归因到页面组件，很多接口问题发生在请求封装、Token 刷新或 API 安全处理层。

最常见的几类联调问题

问题一：接口全部 404

通常是代理地址、后端端口或接口前缀不一致。

问题二：登录成功后接口仍然 401

通常是：

• Access Token 没正确写入状态
• 刷新链路失败
• 后端 Cookie 或代理配置不对

问题三：少量接口异常，其他都正常

通常要重点看该接口是否特殊处理了：

• skipApiSecurity
• 权限码
• 文件上传 FormData
• 静默未授权

联调建议

• 业务接口统一收口在 src/api
• 不要在页面中直接手写 Axios
• 登录、刷新、登出链路尽量不要绕开统一 HTTP 层
• 如果要接第三方接口，建议单独封装，避免污染当前业务请求规则

检查清单

完成接口联调后，建议确认：

• 登录、刷新、用户信息、菜单和站点配置接口均使用 /api/v1 前缀。
• 已登录请求能正确携带 Bearer Token 和必要的 API 安全头。
• 401、403、404、500 能按排查顺序定位到具体层级。
• 新增业务接口已收口在 src/api，页面中没有散落的临时请求实现。