# 打造高质量 Web 管理端前端 — 开发标准 > 基于 vue-vben-admin（v5，★★★★★ Vue 标准标杆）、ant-design-pro（v6，★★★★★ React 标准标杆）、 > soybean-admin（v2.3，★★★★☆ 强烈推荐）、vue-pure-admin（v7，★★★★☆ 推荐）四大纯前端标杆提炼， > gin-vue-admin（★★☆☆☆ 仅作全栈功能对照）。 > > 生成时间：2026-10-22 ｜ 修订：2026-10-22 定位为通用开发标准（去项目化） --- ## 📖 文档定位（先读这一段） 本文件是一份**前端开发标准**（Standard），不是教程： 1. **用途**：放入新项目仓库（如 `docs/`，并被 AGENTS.md / CLAUDE.md 引用），供 **AI 编程助手与开发者**阅读——AI 在编码、Review、重构时以此为基准**对比并优化**目标代码；与本文冲突的既有代码即为待改进项。 2. **范围**：Vue 3 与 React 的管理端 / 中后台 Web 前端（新项目优先）；后端为 Gin / FastAPI 等任意 REST 服务均可——本标准只约定前端结构与 HTTP 契约，不绑定后端框架。 3. **效力**：条款分「必须 / 禁止」「推荐 / 避免」「可选」三级（见规范用语约定）。 4. **证据**：所有规范条目均标注出处（五项目的具体文件路径），不是凭空偏好。 5. **用法**：每章末尾有「AI 检查清单」——对比目标工程时逐项核对，不合格项即为优化任务。 --- ## 📚 文档目录 | 序号 | 文件名 | 主题 | 核心内容 | | -- | ----------------- | ---- | -------------------------------------------- | | 01 | `01-框架选型与技术栈.md` | 框架选型 | 默认技术栈、UI 库对比、TS 采用策略、何时允许偏离 | | 02 | `02-项目架构与目录结构.md` | 项目架构 | 按功能域组织、页面 co-location、可裁剪分层、命名规范 | | 03 | `03-请求层与数据流.md` | 通信架构 | 统一响应契约、拦截器链、refresh 单飞队列、401 三范式、状态分层 | | 04 | `04-路由与权限控制.md` | 路由权限 | meta 规范、动态路由三模式、守卫链、RBAC 三粒度、菜单生成 | | 05 | `05-布局系统与导航设计.md` | 布局导航 | 布局分层、侧栏/标签页/面包屑、Keep-Alive 链路、页面模板 | | 06 | `06-主题系统与视觉设计.md` | 主题视觉 | 设计 Token、暗色模式、CSS 变量换肤、品牌定制、死 CSS 治理 | | 07 | `07-组件设计与交互反馈.md` | 组件交互 | 组件分层与晋升、命令式弹层、表单/表格范式、反馈分级、巨型文件拆分 | | 08 | `08-工程化与质量保障.md` | 工程实践 | Vite 配置、env 分层、lint 流水线、测试金字塔、性能、双端一致性、CI/CD | --- ## 🏆 核心结论速览 ### 默认技术栈（新项目从这里开始） | 端 | 默认栈 | 参照 | | --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | **Vue 3** | Vue 3 + Vite + TypeScript（允许渐进）+ Element Plus + Pinia + Vue Router | 同栈实操对照 vue-pure-admin；架构对照 vben；规范写法对照 soybean | | **React** | React + Vite + TypeScript strict + antd（重 CRUD 加 ProComponents）或 shadcn/ui + Zustand + TanStack Query | 工程与组件对照 ant-design-pro | 包管理器一律 **pnpm**（`preinstall: only-allow pnpm`）。偏离默认栈的条件与程序见 01 章 1.4。 ### 单栈优先与双栈迁移策略 ``` 新项目 ──▶ 必须单栈（Vue 或 React 二选一） 迁移期（存量重构）──▶ 允许双栈并存，但必须遵守三条纪律： 1. 功能以主端为准，副端只做「对齐」同步，不抢先实现新功能 2. 契约先统一命名：token key / 主题 key / 权限码 / 响应格式，两端同名 （推荐命名空间：.auth.token / .theme.mode） 3. 不共享代码，只共享一份契约文档——不为双栈引入 monorepo ``` （monorepo 的适用性判断见 01 章 1.3；双端一致性细则见 08 章第五节） ### 参考项目定位（五项目三级） **首选参考 ★★★★★ —— Vue 看 vben，React 看 adp** | 项目 | 技术栈 | 定位 | 主要借鉴点 | | ------------------ | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | | **vue-vben-admin** | Vue 3 + TS monorepo（pnpm + Turbo） | **Vue 标准标杆** | RequestClient + 预设拦截器、refresh 单飞队列、HSL Token + Tailwind 桥接、Preferences 偏好系统、三层布局架构、Vite 配置工厂、VITE_GLOB 运行时配置 | | **ant-design-pro** | Umi Max + React 19 + antd v6 + ProComponents | **React 标准标杆** | 响应契约与错误分级（ErrorShowType）、access 权限纯函数、页面 co-location 五件套、React Query 数据流、Biome + commitlint 工程底线、测试范式 | **强烈推荐 / 推荐 ★★★★☆ —— Vue 侧第二、第三参考** | 项目 | 技术栈 | 定位 | 主要借鉴点 | | ------------------ | ----------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **soybean-admin** | Vue 3.5 + Naive UI + UnoCSS + Vite（轻 workspace） | 强烈推荐：**代码规范与架构清晰** | @elegant-router 文件路由（目录即路由、类型即生成物）、请求五钩子契约 + flat 返回、store「index + shared」纯函数分离、hasAuth 极简权限、主题三端同步、最严格的 Lint/Commit 体系 | | **vue-pure-admin** | Vue 3.5 + Element Plus + Tailwind v4（单包） | 推荐：**干净轻量，有官方精简版 thin** | 页面内聚五件套（index + form + utils/hook）、PureHttp 196 行请求类、ReDialog 命令式弹窗、EP↔Tailwind 变量桥接、两级按钮权限（v-auth/v-perms）、中文注释密度极高 | **仅作对照 ★★☆☆☆ —— 功能参考，不作前端标准** | 项目 | 技术栈 | 定位 | 可借鉴的模式 | | ----------------- | ------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- | | **gin-vue-admin** | Vue 3 + Element Plus + Pinia + Vite（Gin 全栈） | Gin 全栈闭环 / 后端对接示例 | 后端菜单→`import.meta.glob` 动态路由、`defineOptions name` 与 keep-alive 链路、loading 防抖计数器 | > gva 的价值在于「Gin 后端 + Vue 前端」同仓配套的全栈闭环，适合做整体功能对照； > 其前端工程化、代码规范整体弱于上面 4 个纯前端项目（拦截器 `return error` 未 reject、EP 全量引入、无测试）。 > **前端实现分歧时以 vben（架构）/ soybean（规范）/ pure（同栈 EP 实操）为准，gva 只当功能实现方式对照，前端写法不照搬。** ### 按维度查哪个项目 | 维度 | 优先看 | 说明 | | ---------------- | --------------------- | ----------------------------------------------------------------------- | | 目录结构与分层 | vben > soybean > pure | vben monorepo 分层最值得学；soybean 文件路由清晰；pure 传统但干净 | | 请求封装 | vben / soybean / pure | 错误处理、Token 刷新、类型定义三家都成熟，见 03 章对照 | | 权限系统 | vben > soybean > pure | vben 动态路由 + 细粒度最完整；soybean 静态/动态一键切换；pure 两级按钮权限 | | Lint / Commit 规范 | vben / soybean | 配置最严格完整，直接抄它们的配置文件 | | 组件二次封装 | vben / pure / adp | vben schema 驱动且多 UI；pure hook + 命令式弹窗实用；adp ProTable/ProForm 是 React 标杆 | | TypeScript 类型组织 | vben / soybean / adp | 类型集中、接口返回类型完整；soybean 的全局 namespace + 键级类型最易迁移到 JS 工程 | ### 管理端前端十大黄金法则 ``` ┌────────────────────────────────────────────────────────────────┐ │ 01. 一切 IO 走统一请求层 —— 组件不直接碰 axios/fetch │ │ 02. 响应契约全局唯一 —— code/data/msg + 错误分级 │ │ 03. 401 只有一个入口 —— 单飞刷新 + 队列重放，不竞态 │ │ 04. meta 驱动一切 UI 行为 —— 菜单/缓存/权限/标题单源维护 │ │ 05. 权限三态 —— 不可见 / 可见但 403 / 放行 │ │ 06. 页面私有代码不出页面目录 —— 复用第三次才晋升公共组件 │ │ 07. 反馈分级、少弹框 —— 成功静默、失败必现、危险确认 │ │ 08. 换肤只改 CSS 变量 —— 不重编译、不引第二套样式系统 │ │ 09. 列表/表单/详情有模板 —— 新页面从模板起步，不自由发挥 │ │ 10. 双栈契约优先 —— 同产品双端实现时 key、权限码、 │ │ 响应格式两端同名 │ └────────────────────────────────────────────────────────────────┘ ``` ### 质量红线（违反即技术债） - 单文件组件 ≤ **400 行**（视图）/ ≤ **300 行**（工具、请求层），超限必须拆分 - 样式必须有唯一入口引用链，**无入口的 CSS 一律删除**（存量工程常见 2000+ 行死 CSS 的考古层） - 生产构建**零 console.log**，尤其禁止打印 token 片段 - 组件不绕过 API 层直接调用请求实例 - 文档与实现同 PR 更新，禁止「描述已删除组件」的漂移文档 ### 规范用语约定（必须遵守 vs 推荐） | 标记 | 含义 | 违反后果 | | ----------- | ------------------------------------ | --------------------- | | **必须 / 禁止** | 强制规范（MUST / MUST NOT） | Code review 拒绝，视同 bug | | **推荐 / 避免** | 默认采纳（SHOULD / SHOULD NOT），允许有充分理由的例外 | 例外需在 PR 描述中说明原因 | | **可选** | 按需采用（MAY） | 无 | 正文中加粗的「必须 / 禁止」条款为强制项；各章「AI 检查清单」是带优先级（P0/P1/P2）的对比执行队列。 ### 文档维护与更新规则 1. 实现与文档不一致 = 文档 bug，同一 PR 修复（详见 08 章文档治理） 2. 参考项目大版本升级（vben / soybean / pure / adp）后，复核对应章节引用的证据文件路径 3. 新增规范先以「推荐」落地，被 ≥2 个模块实际验证后再升级为「必须」 4. 修订历史以 git commit 为准 --- ## 🎯 适用场景 - 🏗️ **可裁剪底座 / 脚手架** — 壳 / 系统 / 示例三层，fork 即用 - 🖥️ **管理后台 / 中台** — 用户、RBAC、审计、系统设置等系统级页面 - 📊 **运维监控平台** — 仪表盘、指标图表、实时日志（WebSocket/SSE） - ⏰ **任务调度控制台** — 定时任务 CRUD、执行历史、手动触发 - 🔄 **双栈迁移工程** — Vue→React 或反向迁移期间的对照参照 --- ## 📐 与兄弟指南的关系 | 指南 | 领域 | 分界 | | ----------------------- | -------------------- | ---------------------- | | `GUI-Development-Guide` | Electron/Tauri 桌面端 | 窗口、标题栏、IPC、自动更新 | | `CLI-Development-Guide` | Go 命令行 / TUI / Agent | Cobra、Bubble Tea、审批流 | | **本指南** | **浏览器 Web 管理端** | **请求层、路由权限、布局主题、组件工程** | 三份指南共享同一套写作范式：每个专题按「原理 → 标杆代码 → 最佳实践 → AI 检查清单」四层展开。 --- > 💡 **阅读建议**：开发者先通读本文件，写新页面前读 05（页面模板）和 07（组件规范）；搭新模块前读 02（架构）和 04（路由权限）；排查线上问题读 03（请求层）和 08（工程化）。 > **AI 助手**：编码前读 02/04/05/07；Review 与重构时按各章末「AI 检查清单」逐项对比目标代码，不合格项即输出为优化建议。 > 查阅标杆实现时：**Vue 架构问题对照 vben、规范写法对照 soybean、同栈（Element Plus）实操对照 pure、React 问题对照 adp，gva 仅作功能对照。**