😫 后端接口写好跑通了，但前端页面一片空白，菜单都找不到在哪加
上次我们把会议纪要的后端接口写好了，controller.py 里路由定义得清清楚楚，Swagger 文档里增删改查接口全部调试通过，心里美滋滋。
结果打开前端后台管理页面，左侧菜单里根本找不到“会议纪要”的入口。我愣了几分钟，刷新了几次页面，又重启了几遍服务，啥变化都没有。
后来才明白：FastapiAdmin 后端的接口是纯数据接口，前端是一个独立的 Vue3 工程，后端写完了 ≠ 前端能看到。你得手动配置菜单、写 API 请求层、开发 Vue 页面组件。这套流程我踩了一路的坑，今天就全部整理出来。
📌 本文能帮你解决什么
✅ 搞懂 FastapiAdmin 后端接口和前端页面之间的“连接逻辑”
✅ 手把手完成菜单配置、API 封装、页面开发的完整流程
✅ 避开菜单不显示、接口报 403、组件不渲染等高频翻车场景
🧭 主要内容脉络
前后端连接逻辑
➡️ 第1步：后端菜单配置
➡️ 第2步：前端 API 封装
➡️ 第3步：Vue 页面组件开发
➡️ 第4步：路由与权限联动
➡️ 常见翻车现场
1. 先把逻辑搞清楚：后端接口是怎么“变成”前端页面的？
FastapiAdmin 的前端基于 Vue3 + Vite5 + Pinia + Ant Design Vue，它的菜单是动态生成的：用户登录后，前端调用接口获取该用户有权访问的菜单树，然后动态注册路由、渲染左侧导航栏。
所以整个链路是这样的：
🔹 ① 后端菜单配置：在后台管理界面中创建一条菜单记录，填上路由路径、组件路径、权限标识。
🔹 ② 前端 API 封装：在 frontend/src/api/ 下写一个请求模块，封装对后端接口的 HTTP 调用。
🔹 ③ 页面组件开发：写一个 Vue 页面，用 Ant Design Vue 的表格和弹窗实现增删改查的 UI。
🔹 ④ 路由与权限联动：确保菜单里的组件路径和前端路由配置一致，权限标识和接口的 Depends 一致。
你可能会问：“为什么不能自动生成？”其实 FastapiAdmin 确实内置了代码生成器，可以一键生成前后端代码。但自动生成的东西不一定完全符合你的需求，理解手动流程能让你在定制化时心里有底。
2. 第1步：在后台管理界面配置菜单
登录后台 → 左侧菜单找“平台管理” → 点击“菜单管理”。你会看到一个树形结构的菜单列表。
点击“新增”，填以下信息：
📋 菜单名称：会议纪要
📋 菜单类型：菜单
📋 路由路径：/custom/meeting/
📋 组件路径：module_custom/meeting/index
📋 权限标识：custom:meeting:test
📋 图标：选一个合适的图标
📋 排序：自己定
保存后，如果非管理员用户使用，别忘了去“角色管理”里给当前角色分配这个新菜单的权限，否则你就算加了菜单也看不见。
这个坑我一脚踩进去过——菜单建好了，角色没分配，左侧导航栏就是不显示，试了半天才找到原因。
3. 第2步：在前端工程里封装 API 请求
打开前端目录 frontend/src/api/，FastapiAdmin 的惯例是每个业务模块一个请求文件。我们在 api/ 下新建 module_custom/meeting.ts：
import { request } from "@utils";
const API_PATH = "/custom/meeting";
const MeetingAPI = {
getTest() {
return request<ApiResponse>({
url: `${API_PATH}/`,
method: "get",
})
}
}
export default MeetingAPI注意这里的 request 是项目自己封装的 axios 实例，已经帮你处理好了 baseURL、token 注入、错误拦截这些通用逻辑。你别自己再 new 一个 axios 出来，不然 token 不会自动带上，请求全报 401。
4. 第3步：开发 Vue 页面组件（重头戏）
在 frontend/src/views/ 下新建 module_custom/meeting/index.vue（路径要和菜单里填的组件路径对上！）。
这里我们先编写一个简单的字串响应，中通逻辑再进行后续功能添加：
<script setup lang="ts">
import MeetingAPI from "@/api/module_custom/meeting";
import { ref } from "vue";
const info = ref("test");
onMounted(async () => {
await MeetingAPI.getTest()
.then((res) => {
console.log(res.data);
info.value = res.data["msg"];
})
.catch((err) => {
console.log("出错啦！");
console.log(err);
});
});
script>
<template>
<p>{{ info }}p>
template>后面有时间我们再研究下用 Ant Design Vue 的 a-table 做列表展示，用 a-modal 做新增/编辑弹窗。
5. 第4步：路由与权限的最后确认
页面写好之后，还有最后一道关卡：确保菜单里的路由路径和权限标识能对上。
🔹 菜单里填的 路由路径 /meeting ，必须和你页面文件的实际位置对应。FastapiAdmin 前端默认会动态注册路由，路径对不上就 404。
🔹 菜单里填的 权限标识 meeting:list，必须和你后端 controller 里 Depends(AuthPermission(["meeting:list"])) 完全一致。哪怕多一个空格都会导致前端拿到 403，然后界面上啥也不显示——这个错我查了一整个下午。
🔹 配置完菜单后，退出登录重新登录一次。因为菜单权限是登录时获取的，不刷新的话新菜单永远不会出现。
6. 常见翻车现场：这些错误我替你趟了
🔴 菜单加了但左侧不显示：十有八九是没给当前角色分配权限，去角色管理里勾上。还有一个可能是没重新登录。
🔴 页面打开了但一片空白：打开浏览器控制台看报错。常见原因：组件路径拼错了、Vue 文件不存在、或者路由懒加载失败。
🔴 接口能访问但数据不显示：检查后端返回的 JSON 结构是不是前端期望的。比如你后端直接 return 了一个列表，但前端期望的是 { data: { items: [], total: 0 } } 这种带分页信息的格式。
7. 我的血泪总结
FastapiAdmin 后端的那个 controller，只是定义了“数据怎么存取”。但一个完整的后台功能，还需要菜单配置 + 前端 API 封装 + 页面组件开发 + 角色权限分配四个环节全部走通。
好在这套流程跑顺一次之后，后面再加任何模块都是复制粘贴改参数的事。官方也提供了代码生成器，熟悉了手动流程再用工具提效，心里会更有底。
如果你时间紧，直接用代码生成器一键生成前后端代码，也是个不错的选择——生成出来的文件结构和我们手动写的几乎一样，只是帮你省了敲键盘的时间。
💬 如果你也在用 FastapiAdmin 做前后端联调，卡在菜单显示或者接口对接上，留言说说你遇到的坑。点赞收藏加关注，我们继续深入学习探讨～