Ant Design Pro总结篇，中后台脚手架的目录约定与常用能力

中后台项目最没意思的部分是开头那两周：搭框架、配路由、写登录、做权限、调布局、接 mock。每个公司做一遍，每个人做一遍，做出来的东西还都差不多。Ant Design Pro 干的事就是把这两周的活儿预置好，你 clone 下来直接从第三周开始写业务。

这篇是我 2018 年用 Pro 做项目时整理的总结，覆盖目录结构、布局体系、路由和菜单的中心化配置、CSS Modules、请求分层、图表、业务图标、权限管理和构建发布。原文的写法和当时的 API 我原样保留着，另外在每一块后面补了它现在变成什么样，因为 antd 已经到 v5/v6，umi 也翻过好几个大版本，照着 2018 年的文档写新项目会踩坑。

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

• Pro 的目录约定分成哪几层，每一层放什么
• 三套内建布局怎么和路由配置绑在一起，什么时候需要自己加一套
• router.config.js 中心化管理路由和菜单的思路，以及带参数路由的处理
• 新增一个页面完整要动哪些文件
• CSS Modules 的原理、:global 的用法和样式文件的分类
• 从 UI 交互到服务端的完整链路，service 和 model 怎么分层
• 图表、业务图标、mock 联调这些日常需求的标准做法
• Authorized 权限组件的四种用法和登录后刷新权限的时机
• 构建发布、跨域代理、effect 里并发请求这几个实际问题
• 这套脚手架在 antd v5/v6 和新版 umi 下变成了什么样

# 一、简介

# 1.1 ant pro系统特性

• 基于 Ant Design 体系精心设计
• 使用 React/umi/dva/antd 等前端前沿技术开发
• 针对不同屏幕大小设计
• 可配置的主题满足多样化的品牌诉求
• Mock 数据实用的本地数据调试方案

这五条里，「可配置的主题」和「Mock 数据」是当年最省事的两块。主题变量改一行全站换色，mock 让前端不用等后端就能把页面做完。

# 1.2 模板

Pro 预置的页面模板是它真正的价值所在。这些不是空壳，每一个都带完整的交互和 mock 数据，做需求的时候找一个最接近的直接改，比从零写快得多。

- Dashboard
  - 分析页
  - 监控页
  - 工作台
- 表单页
  - 基础表单页
  - 分步表单页
  - 高级表单页
- 列表页
  - 查询表格
  - 标准列表
  - 卡片列表
  - 搜索列表（项目/应用/文章）
- 详情页
  - 基础详情页
  - 高级详情页
- 结果
  - 成功页
  - 失败页
- 异常
  - 403 无权限
  - 404 找不到
  - 500 服务器出错
- 个人页
  - 个人中心
  - 个人设置
- 帐户
  - 登录
  - 注册
  - 注册成功

异常页那三个（403/404/500）建议一开始就留着，请求拦截器里跳转要用。个人页和账户页用不上可以直接删，删之前记得同步删掉 router.config.js 里对应的配置，否则菜单会指向不存在的组件。

# 1.3 使用

两种起项目的方式，直接 clone 仓库或者用官方 cli。--depth=1 那个参数是只拉最近一次提交，Pro 的仓库历史很大，不加这个下载会很慢。

$ git clone --depth=1 https://github.com/ant-design/ant-design-pro.git my-project
$ cd my-project

或者

$ npm install ant-design-pro-cli -g
$ mkdir my-project && cd my-project
$ pro new  # 安装脚手架

# 1.4 目录结构

目录结构是整个脚手架的地图，摸清楚它，后面「这段代码该放哪」的问题就不用再想了。

整个项目的目录结构

├── mock                     # 本地模拟数据
├── node_modules             # 依赖库
├── public
│   ├── favicon.ico          # Favicon
│   └── index.html           # HTML 入口模板
├── src
│   ├── common               # 应用公用配置，如导航信息
│   ├── components           # 业务通用组件
│   ├── e2e                  # 集成测试用例
│   ├── layouts              # 通用布局
│   ├── models               # dva model
│   ├── routes               # 业务页面入口和常用模板
│   ├── services             # 后台接口服务
│   ├── utils                # 工具库
│   ├── g2.js                # 可视化图形配置
│   ├── polyfill.js          # 兼容性垫片
│   ├── theme.js             # 主题配置
│   ├── index.js             # 应用入口
│   ├── index.less           # 全局样式
│   └── router.js            # 路由入口
├── tests                    # 测试工具
├── .editorconfig            # 编辑器配置
├── .eslintrc                # js代码检测工具
├── .ga                      # 未知
├── .gitignore               # git版本配置
├── .roadhogrc               # roadhog配置
├── .roadhogrc.mock.js       # roadhog的模拟配置
├── .stylelintrc             # css代码审查配置
├── .travis.yml              # travis持续构建工具配置
├── package.json             # web前端项目配置文件
├── README.md
└──

这份结构里最该记住的是 src 下面那六个目录的分工。routes 是页面（后来改叫 pages），components 是可复用的业务组件，layouts 是页面外框，models 是 dva 数据流，services 是接口封装，utils 是工具函数。这条分层跟 dva 的实践是一脉相承的，model、service 怎么分工我在 Dva实践总结 里展开写过。

顺带说下现在的情况。Pro 后来的版本把 routes 改成了 pages（跟 umi 的约定对齐），路由配置从 src/router.js 挪到了 config/routes.ts，整个项目默认用 TypeScript，还多了 src/access.ts 这类约定文件。目录名对不上不代表这篇过时，分层的思路是一样的，只是位置换了。

# roadhog摘要介绍

• roadhog 是一个 cli 工具，提供 server、 build 和 test 三个命令，分别用于本地调试和构建，并且提供了特别易用的 mock 功能。命令行体验和 create-react-app 一致，配置略有不同，比如默认开启 css modules，然后还提供了 JSON 格式的配置方式。
• 重点介绍roadhog有关的几个配置项，主要是在ant design pro的代码中用到了这些配置项

entry

• 指定 webpack 入口文件，支持 glob 格式。
• 如果你的项目是多页类型，会希望把 src/pages 的文件作为入口。可以这样配：

"entry": "src/pages/*.js"

env

针对特定的环境进行配置。server 的环境变量是 development，build 的环境变量是 production。

比如：

"extraBabelPlugins": ["transform-runtime"],
"env": {
  "development": {
    "extraBabelPlugins": ["dva-hmr"]
  }
}

这样，开发环境下的 extraBabelPlugins 是 ["transform-runtime", "dva-hmr"]，而生产环境下是 ["transform-runtime"]。

"env": {
  "development": {
    "extraBabelPlugins": [
      "dva-hmr",
      "transform-runtime",
      "transform-decorators-legacy",
      "transform-class-properties",
      ["import", { "libraryName": "antd", "style": true }]
    ]
  },
  "production": {
    "extraBabelPlugins": [
      "transform-runtime",
      "transform-decorators-legacy",
      "transform-class-properties",
      ["import", { "libraryName": "antd", "style": true }]
    ]
  }
}

在这段代码中，开发环境和生产环境分别配置，其中开发环境使用了dva-hmr插件

那几个 babel 插件各有分工，transform-decorators-legacy 支持 @connect 这类装饰器语法，transform-class-properties 支持类属性写法（state = {} 而不用写在构造函数里），import 就是 antd 的按需加载。开发环境多出来的 dva-hmr 负责 model 的热更新，改 reducer 不用刷新页面。

roadhog 这个工具现在已经不用了，它的能力被 umi 吸收进去，Pro 从比较早的版本起就直接用 umi 构建，配置文件也从 .roadhogrc 换成了 config/config.ts。上面这段留着是给你看老项目用的，新项目不会再出现 .roadhogrc。同理，antd v5 开始换成 cssinjs 之后，babel-plugin-import 也不需要配了。

# 二、布局

页面整体布局是一个产品最外层的框架结构，往往会包含导航、页脚、侧边栏、通知栏以及内容等。在页面之中，也有很多区块的布局结构。在真实项目中，页面布局通常统领整个应用的界面，有非常重要的作用

# 2.1 Ant Design Pro 的布局

在 Ant Design Pro 中，我们抽离了使用过程中的通用布局，都放在 layouts 目录中，分别为

BasicLayout：基础页面布局，包含了头部导航，侧边栏和通知栏

绝大多数业务页面都跑在这套布局里，登录之后看到的就是它。

UserLayout：抽离出用于登陆注册页面的通用布局

登录、注册、注册成功这几个页面用它，因为这些页面不该有侧边栏和菜单，用户还没登录呢。

BlankLayout：空白的布局

第三套是空白布局，什么都不加。适合做全屏的大屏展示页，或者要嵌到别人 iframe 里的页面。

# 2.2 如何使用 Ant Design Pro 布局

通常布局是和路由系统紧密结合的，Ant Design Pro 的路由使用了 Umi 的路由方案，为了统一方便的管理路由和页面的关系，我们将配置信息统一抽离到 config/router.config.js 下，通过如下配置定义每个页面的布局