接口联调
本文面向需要完成前后端联调、定位接口异常或扩展业务接口的研发人员。重点不是列出接口地址，而是说明完整联调链路：
- 接口地址从哪里来
- Token 是谁加上的
- 刷新令牌是谁处理的
- 请求签名是什么时候加上的
- 某个接口报错时应该从前端哪一层查起
一条请求大致会经过哪些层
页面 / 组件
-> src/api/*.ts
-> src/utils/http/index.ts
-> /api/**
-> Java 后端或 Nest.js 后端理解这条链路后，可以把接口问题定位到页面、接口封装、请求层、代理规则或后端服务中的具体环节。
开发环境的请求入口
开发环境下最关键的变量是：
VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13001
# Nest.js 后端使用 http://localhost:13000；代理地址只启用一行浏览器里看到的请求路径通常是相对路径，实际由 Vite 代理到所选后端。Java 默认端口为 13001，Nest.js 默认端口为 13000。修改代理后重启前端，具体启动步骤见 快速开始。
请求层已经帮你做了什么
src/utils/http/index.ts 已经统一处理了以下能力：
- 自动携带
Authorization: Bearer <token> - 按后端公开安全配置，为需要签名的已登录请求追加 API 安全头
- 统一 JSON 请求处理
- 统一错误提示
- 401 时尝试刷新 Access Token
- 刷新失败时触发未授权处理
所以业务代码里通常只需要关心：
- 调哪个接口
- 传什么参数
- 是否要跳过接口安全
- 是否要静默处理某类错误
典型接口前缀
两个后端按共享前端的接口约定提供服务。接口前缀不是全部统一为 /api/v1，应以 src/api 中的当前定义为准，不要批量替换版本号。
常见示例：
- 登录：
/api/v1/auth/signin - 刷新：
/api/v1/auth/refresh - 当前用户：
/api/v1/user/info - 菜单列表：
/api/v3/system/menus - 公开站点配置：
/api/v1/site-settings/public
登录与刷新链路
登录时
前端会：
- 调用登录接口
- 接收 Access Token
- 后续请求自动带上 Bearer Token
刷新页面时
前端会尝试：
- 用 Refresh Token 恢复 Access Token
- 恢复成功后重新获取用户信息
- 再继续初始化菜单和路由
因此，刷新页面后登录状态失效通常需要优先排查鉴权链路，而不是直接修改业务页面。
已登录请求签名
src/utils/api-security.ts 从 /api/v1/crypto/security-config 读取公开配置。只有 enabled 和 signatureRequired 都为 true 时，applyApiSecurityHeaders 才会附加签名、时间戳、随机数和载荷摘要等请求头；业务页面不应根据后端语言自行判断。
| 情况 | 前端行为 |
|---|---|
Java 当前返回 signatureRequired: false | 保留 Bearer 登录态，不附加请求签名头 |
| Nest.js 后端要求签名 | 按公开安全配置生成请求签名头 |
| 登录、刷新等特殊请求 | 按接口封装中的 skipApiSecurity 跳过签名逻辑 |
未出现签名头不一定是异常，应先检查当前后端是否要求签名。请求签名与登录鉴权、接口权限是不同机制，Java 不要求签名不代表无需登录或授权；密码字段的 RSA 加密也不能与请求签名混为一谈。
站点配置接入方式
前端启动后会调用公开站点配置接口，并把后端返回的数据合并到前端默认展示值里。
这会影响：
- 站点名称
- 欢迎文案
- SEO 标题
- 水印文本
- 是否允许注册
所以遇到“文案明明改了却没生效”，优先查的是站点配置接口，而不是先怀疑页面组件。
推荐的接口排查顺序
1. 先看浏览器网络请求
重点确认：
- URL 是否正确
- 请求是否使用了对应接口的实际路径与版本号
- 请求头里是否有 Token
- 返回码是 401、403 还是 500
2. 再看请求封装配置
重点确认：
- 是否被
skipApiSecurity - 是否触发了刷新令牌
- 是否被静默错误处理吞掉了提示
3. 最后再看业务页面
不要直接把所有异常归因到页面组件，很多接口问题发生在请求封装、Token 刷新或 API 安全处理层。
最常见的几类联调问题
问题一：接口全部 404
通常是代理地址、后端端口或接口前缀不一致。
问题二：登录成功后接口仍然 401
通常是：
- Access Token 没正确写入状态
- 刷新链路失败
- 后端 Cookie 或代理配置不对
问题三：少量接口异常，其他都正常
通常要重点看该接口是否特殊处理了：
skipApiSecurity- 权限码
- 文件上传
FormData - 静默未授权
联调建议
- 业务接口统一收口在
src/api - 不要在页面中直接手写 Axios
- 登录、刷新、登出链路尽量不要绕开统一 HTTP 层
- 如果要接第三方接口，建议单独封装，避免污染当前业务请求规则
检查清单
完成接口联调后，建议确认：
- 登录、刷新、用户信息、菜单和站点配置的实际 URL 与
src/api定义一致。 - 已登录请求正确携带 Bearer Token；签名头是否附加与后端公开安全配置一致。
- 401、403、404、500 能按排查顺序定位到具体层级。
- 新增业务接口已收口在
src/api，页面中没有散落的临时请求实现。