项目readme(1)

环境准备

首先需要安装 node，并确保 node 版本是 10.x 版本或以上。推荐使用 nvm 来管理 node 版本，windows 用户可以参考 nvm-windows 进行安装。以 mac 安装为例：

$ curl https://raw.githubusercontent.com/cnpm/nvm/master/install.sh | bash

# 增加以下内容到 ~/.bashrc 或者 ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

# 生效 nvm
bash: source ~/.bashrc
zsh: source ~/.zshrc
ksh: . ~/.profile

# 使用 nvm 安装 node 的 10.15.0 版本
$ nvm install 10.15.0

# 使用 10.15.0 版本
$ nvm use 10.15.0

# 验证 node 是否安装成功
$ node -v
v10.15.0
$ npm -v
6.4.1

nrm – NPM registry manager

如果经常需要切换 npm 镜像源，推荐使用 nrm 进行管理，默认包含：

• npm
• yarn
• cnpm
• taobao
• nj
• npmMirror

全局安装

$ npm install -g nrm

参考示例

$ nrm ls

* npm -----  https://registry.npmjs.org/
  yarn ----- https://registry.yarnpkg.com
  cnpm ----  http://r.cnpmjs.org/
  taobao --  https://registry.npm.taobao.org/
  nj ------  https://registry.nodejitsu.com/
  npmMirror -- https://skimdb.npmjs.com/registry/

$ nrm use cnpm  //switch registry to cnpm

    Registry has been set to: http://r.cnpmjs.org/

使用方法

Usage: nrm [options] [command]

  Commands:

    ls                                    List all the registries
    current                               Show current registry name
    use <registry>                        Change registry to registry
    add <registry> <url> [home]           Add one custom registry
    login <registry> [value]              Set authorize information for a registry with a base64 encoded string or username and pasword
      -a  --always-auth                     Set is always auth
      -u  --username <username>             Your user name for this registry
      -p  --password <password>             Your password for this registry
      -e  --email <email>                   Your email for this registry
    set-hosted-repo <registry> <value>    Set hosted npm repository for a custom registry to publish packages
    del <registry>                        Delete one custom registry
    home <registry> [browser]             Open the homepage of registry with optional browser
    test [registry]                       Show the response time for one or all registries
    publish [<tarball>|<folder>]          Publish package to current registry if current registry is a custom registry.  if you\'re not using custom registry, this command will run npm publish directly
      -t --tag [tag]                        Add tag
      -a --access <public|restricted>       Set access
      -o --otp [otpcode]                    Set otpcode
      -dr --dry-run                         Set is dry run
    help                                  Print this help

  Options:

    -h, --help     output usage information
    -V, --version  output the version number

镜像源

• npm
• yarn
• cnpm
• taobao
• nj(nodejitsu)
• npmMirror

快速上手

host 映射

127.0.0.1    local.xxxx.com

安装依赖

$ npm install

启动项目

$ npm run dev

✔ Webpack
  Compiled successfully in 16.02s



 DONE  Compiled successfully in 16130ms

启动同步调试

$ npm run sync

✔ Webpack
  Compiled successfully in 15.15s



 DONE  Compiled successfully in 15266ms                                                                                                        4:05:01 PM

[Browsersync] Proxying: http://localhost:8081
[Browsersync] Access URLs:
 -----------------------------------
       Local: http://localhost:3000
    External: http://10.73.15.6:3000
 -----------------------------------
          UI: http://localhost:3001
 UI External: http://localhost:3001
 -----------------------------------

部署发布

构建

$ npm run prod

✔ Webpack
  Compiled successfully in 19.56s

发布

• dev

$ npm run build-dev
$ npm run gulp-sftp-dev

• sit

$ npm run build-sit
$ npm run gulp-sftp-sit

• uat

$ npm run build-uat
$ npm run gulp-sftp-uat

技术选型

React + React-router + React-intl + Ant Design + Axios + Mobx + Mock + Highcharts + D3

文档

• react
• react-router
• react-intl
• ant design
• axios
• mobx
• mock
• highcharts
• d3
• htmllint
• eslint
• jscpd
• coverage

目录结构

├─ dist/                          # 构建产物
├─ docs/                          # 文档
├─ report/                        # 报告
|   ├─ jscpd-badge.svg
|   └── jscpd-report.json
├─ src/                           # 源码
|  ├─ assets/                     # 静态文件夹
|  |  ├─ images/                  # 图片
|  ├─ components/      	          # 自定义业务组件
|  |  ├─ breadcrumb/              # 面包屑 通用组件
|  |     ├─ index.jsx             # 组件路口
|  |     ├─ index.less            # 组件样式
|  |     └─ __tests__/            # 测试用例
|  |  ├─ date-picker/             # 时间选择组件
|  |  ├─ header/                  # header 组件
|  |  ├─ highcharts/              # highchart 通用组件
|  |  ├─ icon/                    # 自定义 Icon 组件
|  |  ├─ loading/                 # 路由切换 loading
|  |  ├─ sidebar/                 # 侧边导航
|  |  ├─ table/                   # tabel 通用组件
|  ├─ hooks/                      # 自定义 hooks
|  |   └─ index.jsx
|  ├─ i18n/                       # 国际化目录
|  |  ├─ zh/                      # 中文
|  |  ├─ index.jsx                # 入口
|  ├─ interceptor/                # axios 全局配置
|  |   └─ index.js
|  ├─ mock/                       # 本地模拟数据
|  |   └─ index.jsx
|  ├─ routers/                    # 路由配置
|  |   └─ index.jsx
|  ├─ stores/                     # 状态管理
|  |   └─ index.jsx
|  ├─ templates/                  # 页面
|  |  ├─ Home/                    # Home 页面
|  |     ├─ index.jsx             # 页面入口
|  |     └─ index.less            # 页面样式
|  ├─ utils/                      # 工具
|  |   ├─ index.js		
|  |   └─ loadable.js
|  ├─ favicon.ico                 # favicon 图标
|  ├─ index.html                  # 应用入口 HTML
|  ├─ index.jsx                   # 应用入口
|  ├─ index.less                  # 全局样式
├─ .babelrc                       # babel 配置
├─ .eslintignore                  # eslint 忽略配置
├─ .eslintrc                      # eslint 配置
├─ .htmllintrc                    # htmllint 配置
├─ .postcssrc.js                  # postcss 配置
├─ .prettierrc                    # prettier 配置
├─ .stylelintcache                # stylelint 缓存
├─ .stylelintignore               # stylelint 忽略配置
├─ .stylelintrc                   # stylelint 配置
├─ commitlint.config.js           # commitlint 配置
├─ gulpfile.js                    # 发布配置
├─ package-lock.json
├─ package.json                   # 依赖管理
├─ README.md                      # 文档
├─ webpack.base.js                # webpack 基础配置
├─ webpack.dev.js                 # webpack 本地开发配置
├─ webpack.prod.js                # webpack 构建配置
├─ webpack.server.js              # webpack 开发配置
├─ webpack.sync.js                # webpack 同步调试配置

生命周期

class

class Example extends Component {
    // 构造函数
    constructor(props) {
        super(props);
        this.state = {};
    }

    // 当组件实例被创建、props 或 state 发生变化、forceUpdate
    // 替换 componentWillReceiveProps
    static getDerivedStateFromProps(nextProps, prevState) { }

    // props 或 state 发生变化，渲染前
    // 该方法通过返回 true 或者 false 来确定是否需要重新渲染
    shouldComponentUpdate() { }

    // render 之后，update 之前
    // 必须配合 componentDidUpdate 一起使用
    getSnapshotBeforeUpdate(prevProps, prevState) { }

    // 组件完成装载
    componentDidMount() { }
    
    // 渲染完成后
    componentDidUpdate() { }

    // 即将卸载
    componentWillUnmount() { }

    // 事件函数/普通函数
    handleClick = () => { }

    // 最后，render 方法
    render() { }
}

HOOK

  const Example = (props) => {
    // 声明一个新的叫做 “count” 的 state 变量
  	const [count, setCount] = useState(0);
    // 声明一个变量为 status, useState 传入一个函数，只会在组件第一次初始时执行一次
    const [status] = useState(() => props.status);
    // Similar to componentDidMount and componentDidUpdate
  	useEffect(() => {
  	    // Update the document title using the browser API
        document.title = `You clicked ${count} times`;
  	});
     // 仅在 props.status 发生变化时，重新订阅
  	useEffect(()=>{
        console.log("Status has change");
    },[props.status]);
  	
  	return (
  	  <>
  		  <div>
          <p>You clicked {count} times</p>
          <button onClick={() => setCount(count + 1)}>
            Click me
          </button>
        </div>
        {
            status ? <>{status} online</> : <>{status} offline</>
        }
      </>
  	)
  }

命名规范

项目命名

全部采用小写方式， 以中划线分隔。例：my-project-name

目录命名

参照项目命名规则。
有复数结构时，要采用复数命名法。
例：scripts、styles、images、data-models

HTML 文件命名

参照项目命名规则。
例：error-report.html

CSS 文件命名

参照项目命名规则。
例：retina-sprites.css

JS 文件命名

参照项目命名规则。
例：account-model.js

HTML 规范

语法

• 缩进使用 soft tab（2个空格）；
• 嵌套的节点应该缩进；
• 在属性上，使用双引号，不要使用单引号；
• 属性名全小写，用中划线做分隔符；
• 不要在自动闭合标签结尾处使用斜线（HTML5 规范指出他们是可选的）；
• 不要忽略可选的关闭标签，例：</li> 和 </body>。

HTML5 DOCTYPE

在页面开头使用这个简单地 DOCTYPE 来启用标准模式，使其在每个浏览器中尽可能一致的展现；

虽然 DOCTYPE 不区分大小写，但是按照惯例，DOCTYPE 大写 （关于 DOCTYPE 属性，大写还是小写）。

lang 属性

根据 HTML5 规范：

应在 html 标签上加上 lang 属性。这会给语音工具和翻译工具帮助，告诉它们应当怎么去发音和翻译。

更多关于 lang 属性的说明在这里；
在 sitepoint 上可以查到语言列表；
但 sitepoint 只是给出了语言的大类，例如中文只给出了zh，但是没有区分香港，台湾，大陆。而微软给出了一份更加详细的语言列表，其中细分了 zh-cn、 zh-hk、zh-tw。

字符编码

通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式，通常指定为 “UTF-8”。

IE 兼容模式

用 标签可以指定页面应该用什么版本的IE来渲染；
如果你想要了解更多，请点击这里；
不同 DOCTYPE 在不同浏览器下会触发不同的渲染模式（这篇文章总结的很到位）。

引入 CSS、JS

根据 HTML5 规范, 通常在引入 CSS 和 JS 时不需要指明 type，因为 text/css 和 text/javascript 分别是他们的默认值。

HTML5 规范链接

• 使用 link
• 使用 style
• 使用 script

属性顺序

属性应该按照特定的顺序出现以保证易读性；

• class
• id
• name
• data-*
• src、for、type、href、value、max-length、max、min、pattern
• placeholder、title、alt
• aria-*、role
• required、readonly、disabled

class 是为高可复用组件设计的，所以应处在第一位；
id 更加具体且应该尽量少使用，所以将它放在第二位。

boolean 属性

boolean 属性指不需要声明取值的属性，XHTML 需要每个属性声明取值，但是 HTML5 并不需要；

更多内容可以参考 WhatWG section on boolean attributes：

boolean 属性的存在表示取值为 true，不存在则表示取值为 false。

JS 生成标签

在 JS 文件中生成标签让内容变得更难查找，更难编辑，性能更差。
应该尽量避免这种情况的出现。

减少标签数量

在编写 HTML 代码时，需要尽量避免多余的父节点；
很多时候，需要通过迭代和重构来使 HTML 变得更少。

实用高于完美

尽量遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价；
任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。

CSS 规范

ClassName 的命名应该尽量精短、明确。严格使用 BEM 规则。

缩进

使用 soft tab（2个空格）。

分号

每个属性声明末尾都要加分号。

空格

以下几种情况不需要空格：

• 属性名后
• 多个规则的分隔符 “,” 前
• !important “!” 后
• 属性值中 “(” 后和 “)” 前
• 行末不要有多余的空格

以下几种情况需要空格：

• 属性值前
• 选择器 “>”、 “+”、“~” 前后
• “{” 前
• !important “!” 前
• @else 前后
• 属性值中的 “,” 后
• 注释 “/" 后和 "/” 前

空行

以下几种情况需要空行：

• 文件最后保留一个空行
• “}” 后最好跟一个空行，包括 scss 中嵌套的规则
• 属性之间需要适当的空行

换行

以下几种情况不需要换行：

• “{” 前

以下几种情况需要换行：

• “{” 后和 “}” 前
• 每个属性独占一行
• 多个规则的分隔符 “,” 后

注释

• 注释统一用 “/* */”（scss 中也不要用 “//”）
• 缩进与下一行代码保持一致
• 可位于一个代码行的末尾，与代码间隔一个空格

引号

• 最外层统一使用双引号
• url 的内容要用引号
• 属性选择器中的属性值需要引号

命名

• 类名使用小写字母，以中划线 “-” 分隔
• id 采用驼峰式命名
• scss 中的变量、函数、混合、placeholder 采用驼峰式命名

属性声明顺序

具体见 .stylelintrc

颜色

• 颜色十六进制用小写字母
• 颜色十六进制尽量用简写

属性简写

属性简写需要你非常清楚属性值的正确顺序，而且在大多数情况下并不需要设置属性简写中包含的所有值，所以建议尽量分开声明会更加清晰；
margin 和 padding 相反，需要使用简写；
常见的属性简写包括：

• font
• background
• transition
• animation

媒体查询

尽量将媒体查询的规则靠近与他们相关的规则，不要将他们一起放到一个独立的样式文件中，或者丢在文档的最底部，这样做只会让大家以后更容易忘记他们。

SCSS相关

提交的代码中不要有 @debug；
声明顺序：

• @extend
• 不包含 @content 的 @include
• 包含 @content 的 @include
• 自身属性

嵌套规则

• @import 引入的文件不需要开头的 “_” 和结尾的 “.scss”；
• 嵌套最多不能超过5层；
• @extend 中使用 placeholder 选择器；
• 去掉不必要的父级引用符号 “&”。

杂项

• 不允许有空的规则
• 元素选择器用小写字母
• 去掉数字中不必要的小数点和末尾的 0
• 属性值 “0” 后面不要加单位
• 同个属性不同前缀的写法需要在垂直方向保持对齐
• 无前缀的标准属性应该写在有前缀的属性后面
• 不要在同个规则里出现重复的属性，如果重复的属性是连续的则没关系
• 不要在一个文件里出现两个相同的规则
• 用 border: 0; 代替 border: none;
• 选择器不要超过 4 层（在 scss 中如果超过 4 层应该考虑用嵌套的方式来写）
• 发布的代码中不要有 @import
• 尽量少用 “*” 选择器

JavaScript 规范

缩进

使用 soft tab（2个空格）。

单行长度

不要超过 80，但如果编辑器开启 word wrap 可以不考虑单行长度。

分号

以下几种情况后需加分号：

• 变量声明
• 表达式
• return
• throw
• break
• continue
• do-while
• 空格

以下几种情况不需要空格：

• 对象的属性名后
• 前缀一元运算符后
• 后缀一元运算符前
• 函数调用括号前
• 无论是函数声明还是函数表达式，"("前不要空格
• 数组的"[“后和”]"前
• 对象的"{“后和”}"前
• 运算符"(“后和”)"前

以下几种情况需要空格：

• 二元运算符前后
• 三元运算符"?:"前后
• 代码块"{"前
• 下列关键字前：else、while、catch、finally
• 下列关键字后：if、else、for、while、do、switch、case、try、catch、finally、with、return、typeof
• 单行注释 “//” 后（若单行注释和代码同行，则 “//” 前也需要）
• 多行注释 “*” 后
• 对象的属性值前
• for 循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格
• 无论是函数声明还是函数表达式，“{” 前一定要有空格
• 函数的参数之间

空行

以下几种情况需要空行：

• 变量声明后（当变量声明在代码块的最后一行时，则无需空行）
• 注释前（当注释在代码块的第一行时，则无需空行）
• 代码块后（在函数调用、数组、对象中则无需空行）
• 文件最后保留一个空行

换行

换行的地方，行末必须有 “,” 或者运算符；

以下几种情况不需要换行：

• 下列关键字后：else、catch、finally
• 代码块 “{” 前

以下几种情况需要换行：

• 代码块 “{” 后和 “}” 前
• 变量赋值后

单行注释

• 双斜线后，必须跟一个空格
• 缩进与下一行代码保持一致
• 可位于一个代码行的末尾，与代码间隔一个空格

多行注释

最少三行, “*” 后跟一个空格；

建议在以下情况下使用：

• 难于理解的代码段
• 可能存在错误的代码段
• 浏览器特殊的HACK代码
• 业务逻辑强相关的代码

文档注释

各类标签 @param, @method 等请参考 usejsdoc 和 JSDoc Guide；

建议在以下情况下使用：

• 所有常量
• 所有函数
• 所有类

引号

最外层统一使用单引号。

变量命名

• 标准变量采用驼峰式命名（除了对象的属性外，主要是考虑到 cgi 返回的数据）
• “ID” 在变量名中全大写
• “URL” 在变量名中全大写
• “Android” 在变量名中大写第一个字母
• “iOS” 在变量名中小写第一个，大写后两个字母
• 常量全大写，用下划线连接
• 构造函数，大写第一个字母
• jquery 对象必须以 “$” 开头命名

变量声明

一个函数作用域中所有的变量声明尽量提到函数首部，用一个 var 声明，不允许出现两个连续的 var 声明。

函数

• 无论是函数声明还是函数表达式，“(” 前不要空格，但 “{” 前一定要有空格
• 函数调用括号前不需要空格
• 立即执行函数外必须包一层括号
• 不要给 inline function 命名
• 参数之间用 ", " 分隔，注意逗号后有一个空格

数组、对象

• 对象属性名不需要加引号
• 对象以缩进的形式书写，不要写在一行
• 数组、对象最后要有逗号

括号

下列关键字后必须有大括号（即使代码块的内容只有一行）：if、else、for、while、do、switch、try、catch、finally、with。

null

适用场景：

• 初始化一个将来可能被赋值为对象的变量
• 与已经初始化的变量做比较
• 作为一个参数为对象的函数的调用传参
• 作为一个返回对象的函数的返回值

不适用场景：

• 不要用 null 来判断函数调用时有无传参
• 不要与未初始化的变量做比较

undefined

永远不要直接使用 undefined 进行变量判断；
使用 typeof 和字符串 “undefined” 对变量进行判断。

eslint

• 用 “=“、”!” 代替 “==”、“!=”
• for-in 里一定要有 hasOwnProperty 的判断
• 不要在内置对象的原型上添加方法，如 Array、Date
• 不要在内层作用域的代码里声明了变量，之后却访问到了外层作用域的同名变量
• 变量不要先使用后声明
• 不要在一句代码中单单使用构造函数，记得将其赋值给某个变量
• 不要在同个作用域下声明同名变量
• 不要在一些不需要的地方加括号，例：delete(a.b)
• 不要使用未声明的变量（全局变量需要加到 .eslintrc 文件的 globals 属性里面）
• 不要声明了变量却不使用
• 不要在应该做比较的地方做赋值
• debugger 不要出现在提交的代码里
• 数组中不要存在空元素
• 不要在循环内部声明函数
• 不要像这样使用构造函数，例：new function () { … }, new Object

杂项

• 不要混用 tab 和 space
• 不要在一处使用多个 tab 或 space
• 换行符统一用 “LF”
• 对上下文 this 的引用只能使用 “_this”、“that”、“self” 其中一个来命名
• 行尾不要有空白字符
• switch 的 falling through 和 no default 的情况一定要有注释特别说明
• 不允许有空的代码块

静态检测

HTML 检测

HTML 需遵从 htmllint 规范, 具体配置见 .htmllintrc。

css 检测

项目使用 less 预处理。

样式需遵从 stylelint 规范, 具体配置见 .stylelintrc。

JavaScript 检测

JSX 是一个 JavaScript 的语法扩展。

js/jsx 需遵从 ESLint 规范，具体配置见 .eslintrc。

git 分支规范

• dev 版本迭代分支
• fix 缺陷修复分支
• sit 测试分支
• uat 预生产分支
• master 生产分支

commit 规范

<type>(<scope>): <subject> // 必填, 描述主要修改类型和内容。注意冒号后面有空格
<BLANK LINE>
<body> // 描述为什么修改, 做了什么样的修改, 以及开发的思路等等
<BLANK LINE>
<footer> // 放 Breaking Changes 或 Closed Issues

• type 必填，commit 的类型，主要包含下面几种：
  • feat 新功能
  • fix 修复bug
  • refactor 重构
  • style 格式修改
  • docs 文档修改
  • build 构建流程或依赖管理等修复
  • ci ci 相关的修改
  • test 测试用例修改
  • perf 性能提升
  • revert 回滚
• scope 选填，commit 影响的范围, 比如: route, component, utils, build…
• subject 必填，commit 的简短描述，格式可以参考 50/72 formatting
• body 选填，commit 的具体修改内容, 可以分为多行
• footer 选填，备注信息，通常是 Breaking Changes 或 Closed Issues