flow

flow的使用

2016-12-18

facebook 推出的 js 静态类型检查工具。

flow可以在代码运行前对类型错误进行检查，包括：

  • 类型错误
  • 对null的引用
  • 以及可怕的 “undefined is not a function”
    flow 允许我们给变量添加类型

flow 的安装和使用

安装：
由于 flow 是用 OCaml 语言写的，npm 上只有对应的二进制包。

1
npm install --save-dev flow-bin

1.基本使用

安装完成后我们在要执行静态检查的文件跟目录下执行一下 flow init ，之后会发现多处一个.flowconfig文件，这个文件告诉 Flow 在这个目录下开始检测。此外 .flowconfig 文件可以进行一下更为高级的配置，比如仅包含一些目录、忽略一下目录等等（更深入的了解，请戳官网）。

对于需要使用 flow 进行类型检查的 js 文件，在开头加入 @flow 的注释

1
2
3
4
5
/* @flow */ 只要带有这个注释，都会进行类型检测
或者
/* @flow weak */ 只对有加类型注解的变量进行类型检测

例如：

1
2
3
4
5
6
7
8
9
10
11
12
/* @flow */
function multiple10 (num) {
  return num * 10
}
multiple10('20')
function getLength (str) {
  return str.length
}
getLength('3')
getLength([1,2,3])

接下来执行 flow check 看一下结果

1
2
3
4
3: return num * 10
          ^^^ string. The operand of an arithmetic operation must be a number.
Found 1 error

multiple10 函数中的类型转换被 flow 标记出。

2.类型注解

注意上面例子中 flow 的报错，只有 multiple10 中静态类型错误被检测中。对于 getLength 函数中参数 str 的类型是什么呢？ 从函数本身来分析，只要包含 length 属性就都是合法的。 对于这种情况则可以为其添加“类型注解”，来明确的告诉 flow 这个值的类型。

1
2
3
4
5
function getLength (str: string) {
  return str.length
}
getLength('3')
getLength([1,2,3])

再来运行一下 flow check , 这时结果会提示我们[1,2,3]这个参数类型不对。

1
2
3
4
12: getLength([1,2,3])
              ^^^^^^^ array literal. This type is incompatible with the expected param type of
 8: function getLength (str: string) {
                             ^^^^^^ string

3.自定义类型

很多时候，除了 number 、 string 这些基础类型外，我们还会有一些自定义的类型，比如：

1
2
3
4
var someData = {
	id: 1,
	text: '选项1'
}

这时候可以在一个单独的文件中将 someData 申明了一个自定义类型。方式如下：

1
2
3
4
5
/* /decls/data.js.flow */
declare type SomeData = {
  id: number;
  text: strin;
}

然后在 .flowconfig 文件中引入该申明文件

1
2
[libs]
decls/

flow server

在大型项目中，如果每修改完代码，就执行以下 flow check ，然后等待看结果，显然会被逼疯的。flow 为我们提供了一个 flow server ，支持在后台运行，并且只监测有修改的文件。方法很简单，只有一个命令

1
2
3
$> flow # 开启一个后台服务，输出首次检测结果
$> flow # 第二次使用flow，连接正在运行的后台服务，输出检测结果
$> flow stop # 关闭flow server

babel+flow

由于 flow 中类型注解的语法不属于 javascript 规范中的内容。所以在最终的代码中，我们需要移除flow的内容。flow 提供了 flow-remove-types 和 babel 插件两种方式，推荐使用 babel 插件来完成这项工作。

  • flow-remove-types
    这种方法比较简单粗暴: 安装 flow-remove-types，然后执行命令。

    1
    2
    $> npm install -g flow-remove-types
    $> flow-remove-types src/ --out-dir build/

  • babel插件
    安装 babel 插件

    1
    $> npm install babel-plugin-transform-flow-strip-types

babel 的 plugin 中加入该插件

1
2
3
4
5
  {
  "presets": ["es2015", "stage-2"],
  "plugins": ["transform-runtime", "transform-flow-strip-types"],
  "comments": false
}

注意：在 babel6 的 babel-preset-react 的插件中已经内置了 transform-flow-strip-types（https://flowtype.org/docs/syntax.html），如果使用了 babel-preset-react 那么无需再引入transform-flow-strip-types

eslint

eslint-plugin-flowtype 插件，可以让我们在 eslint 代码检查中加入 flow 的书写规范化检查。使用方式也很简单：

  1. 安装

    1
    $> npm install eslint-plugin-flowtype

  2. 在 .eslintrc.js 中设置 parser 为 babel-eslint

  3. plugin 中加入 flowtype
  4. eslint-plugin-flowtype 插件中默认提供了一份基于优秀实践总结出的 flow type 书写规范配置，在 .eslintrc 文件的 extend 中加入 “plugin:flowtype/recommended” 即可直接使用。
1
2
3
4
5
6
7
8
9
{
  "extends": [
    "standard",
    "plugin:flowtype/recommended"
  ],
  "plugins": [
    "flowtype"
  ]
}

完成后我们来看看效果。下面的代码

1
2
3
4
function getLength (str:string) {
  return str.length
}
getLength('3')

eslint 检查结果会抛出一个错误：类型注解的冒号后面丢失了空格。

1
2
3
4
5
6
  ✘  https://google.com/#q=flowtype%2Fspace-after-type-colon  There must be a space after "str" parameter type annotation colon
  /Users/didi/xiaoju/src/static-h5-src/750/driver/feedback/src/main.js:2:21
  function getLength (str:string) {
                       ^
✘ 1 problem (1 error, 0 warnings)

因为推荐的规范中：类型注解冒号后需要一个空格

1
2
3
4
5
6
7
8
"rules": {
  ...
"flowtype/space-after-type-colon": [
  2,
  "always"
],
...
}

flow type 规范配置如：函数返回类型是否必须、类型注解冒号前后的空格、自定义的type 的名称的命名方式等等，官方给出了很详细说明和例子。注：针对flow的的规范规则配置前添加“flowtype/”

配置名称 作用
boolean-style 类型注解中布尔值使用boolean还是bool
define-flow-type 将类型注解标记为已定义，no-undef的检查中不会出现报错
delimiter-dangle Object和Tuple类型定义中分隔符使用规范
generic-spacing 泛型对象的尖括号中类型前后的空格规范
space-before-generic-bracket 泛型对象的尖括号前的空格规范
no-dupe-keys object类型的定义中是否有重复的属性值
no-primitive-constructor-types 禁止使用原生的类型
no-weak-types 是否可以使用弱类型any、Object、Function
object-type-delimiter Object类型定义中，属性之前分割符为分号/逗号(注：该属性已被废弃，需要使用分号来分割)
require-parameter-type 函数的参数是否需要类型注解
require-return-type 函数返回值是否需要类型注解
require-valid-file-annotation 文件开头@flow的写法
require-variable-type 什么样的变量是需要类型注解
semi 使用type自定义类型语句结尾是否需要分号结尾
sort-keys Object类型定义中属性排列顺序
space-after-type-colon 类型注解分号后的空格规范
space-before-type-colon 类型注解分号前的空格规范
type-id-match 使用type自定义类型的名称规范
union-intersection-spacing union类型、intersection类型连接符号\ 、&之间的空格规范
use-flow-type 将通过declare定义的自定义类型标记为已经被使用过，no-unused-vars的检查中不会出现报错

#####名词说明

文中一些中文词直接从英文文档中翻译过来，可能有不准确的地方，这里给出原文，避免歧义。

  • 类型注解：原文为 type annotations ,标记变量的类型

  • 自定义类型：原文为 type aliases, 类似C语言中的typedef，可以为已有类型定义一个新的名称，或将一个复杂类型进行封装，如

    1
    2
    3
    4
    5
     type a = Array<String>
     type Person = {
    	  name: string,
    	  age: number
    };

#####相关链接
flow 官网(关于 flow 的各种用法官网给出了详细的例子)：https://flowtype.org/

flow 简短教程：https://www.youtube.com/watch?v=xWMuAUbXcdQ

阅读全部
本文为原创，对知识的理解有疏漏或者错误的地方，欢迎指正。如有问题，欢迎开issue。