构建具备认证、权限、数据管理与测试能力的企业级后台前端

方案简介

方案简介

Antd Admin 是面向企业后台场景的生产级管理模板方案，定位是提供一套 AI-friendly enterprise front-end best practices。它以 React 19、Ant Design 6 和现代前端工具链为基础，覆盖认证、权限、路由、数据请求、表格状态、主题和测试等后台应用常见能力。

方案适合需要快速搭建管理后台、仪表盘或 CRUD 型企业前端的团队，也适合希望先脱离真实后端进行页面开发的项目。项目采用 mock-first development，因此可以在后端尚未完成时先验证登录、菜单、权限和数据交互流程；同时提供独立脚手架 CLI，可从官方模板生成 standalone app。模板包括 English-only 的 basic，以及支持 en 与 zh 的 with-lingui 双语模板。

亮点与能力

亮点与能力

• JWT 登录：提供 access/refresh flow，覆盖后台系统常见的登录令牌流程。
• 后端驱动菜单与权限：菜单和 permission guards 可由后端数据驱动。
• URL 同步表格状态：分页、排序和搜索状态可以同步到 URL。
• 主题切换：支持 dark mode theme switching。
• Mock-first 开发：无需后端即可开展本地开发。
• 类型化 API 与 CRUD：提供 typed API boundaries 和可复用的 CRUD patterns。
• 国际化模板：with-lingui 提供 en 与 zh 双语工作流。
• E2E 测试：使用 Playwright 提供端到端覆盖。

组成与分工

组成与分工

• React 19：作为后台前端应用的核心 UI 框架。
• Ant Design 6：提供管理后台所需的界面组件基础。
• TanStack Router：承担应用路由能力，并与后台页面导航结合。
• TanStack Query：承担查询和服务端数据管理，与类型化 API 边界配合。
• Zustand：承担前端状态管理。
• Zod：参与类型化 API 边界，帮助形成更明确的数据约束。
• JWT：实现 access/refresh 登录认证流程。
• Mock-first development：让本地开发不依赖后端服务。
• Playwright：为后台流程提供 E2E 覆盖。
• init-antd-admin：从官方模板生成独立应用，支持 basic 与 with-lingui 模板。

前置要求

前置要求

需要准备 JavaScript 包管理器，并通过 init-antd-admin 使用官方模板创建 standalone app。CLI 支持 npm、pnpm、yarn 和 bun；如果希望使用双语工作流，应选择 with-lingui 模板。

交互式创建命令如下：

npx init-antd-admin@latest
pnpm dlx init-antd-admin@latest
yarn dlx init-antd-admin@latest
bunx init-antd-admin@latest

非交互式创建可直接指定目录、模板和包管理器：

pnpm dlx init-antd-admin@latest my-app --example basic -m pnpm
pnpm dlx init-antd-admin@latest my-app --example with-lingui --skip-install

实施步骤

实施步骤

1. 选择模板并生成项目

根据语言需求选择模板：英文后台使用 basic，需要 en 与 zh 双语时使用 with-lingui。可以使用交互式命令，也可以直接执行非交互式命令。

2. 选择包管理器和安装策略

非交互式示例使用 pnpm 生成 my-app。如果暂时不安装依赖，可以使用 --skip-install；如果不希望执行模板改写，可以使用 --skip-transforms。

3. 进入生成的应用并进行项目开发

围绕模板已有能力继续实现业务页面，将后端驱动菜单、权限守卫、JWT access/refresh 流程、可复用 CRUD 和类型化 API 边界接入具体业务。

4. 在无后端条件下验证前端流程

利用 mock-first local development 先验证管理后台页面、表格 URL 状态、主题切换和权限相关流程；待后端接口具备后，再替换或衔接真实数据边界。

5. 使用 Playwright 验证关键流程

将登录、菜单权限和核心 CRUD 等实际后台流程纳入 E2E 覆盖，以保持模板的 practical testing coverage。

使用与配置要点

使用与配置要点

模板选择

• basic：English-only setup，适合只需要英文界面的管理后台。
• with-lingui：Bilingual setup，提供 en + zh，适合需要 Lingui 国际化工作流的项目。

CLI 常用选项

• [project-directory]：指定目标目录。
• -e, --example ：指定示例或模板来源。
• --example-path ：指定远程仓库内的子路径。
• -m, --package-manager ：选择 npm、pnpm、yarn 或 bun。
• --skip-install：跳过依赖安装。
• --skip-transforms：跳过重写转换。
• --no-git：跳过 Git 初始化。

运行后的验证重点

应用跑通后，可重点检查 JWT access/refresh 登录流程、后端驱动菜单和 permission guards、分页排序搜索的 URL 同步、暗色主题切换，以及 mock 数据下的 CRUD 交互。对于双语模板，还应检查 en 与 zh 工作流；对于质量验证，应检查 Playwright 的 E2E 覆盖。

注意事项与常见问题

注意事项与常见问题

• 不要把模板当作单一固定页面：项目提供 basic 和 with-lingui 两种官方模板，应先根据语言需求选择。
• 后端未就绪并不阻塞前端开发：方案明确支持 mock-first local development，但接入真实后端时仍需对接类型化 API 边界、认证流程和后端驱动权限数据。
• 脚手架参数要确认：--skip-install 会跳过依赖安装；--no-git 会跳过 Git 初始化；--skip-transforms 会跳过重写转换，使用前应确认是否符合生成目标。
• 详细 CLI 行为：README 指向 packages/create/README.md，生产文档位于 https://antd-admin-doc.zuiidea.top。
• 许可证：项目采用 MIT License。

优缺点

• ✓ 支持无后端Mock开发
• ✓ 具备端到端测试覆盖

出处

本方案挖掘自开源项目 zuiidea/antd-admin，方案内容与实施命令均来自其 README 原文。