MIP Validator

本项目给出用于MIP校验的NPM软件包，支持编程方式、命令行接口、以及浏览器JS。
本文档介绍MIP校验框架的使用和开发方式，其他相关文档请参考Wiki。

依赖与安装

确保安装了Node.js(版本>=4)，然后使用npm安装mip-validator。

# 编程方式访问，将会安装到 ./node_modules/mip-validator
npm install -S mip-validator
# 命令行接口
sudo npm install -g mip-validator

注意：对于命令行接口，如果没有管理员权限可安装在本地（不加-g参数）：

npm install mip-validator

以后使用时用本地的可执行文件./node_modules/.bin/mip-validator代替全局可执行文件mip-validator。

使用方式

编程接口

在本地安装mip-validator（即安装于node_modules目录下）。
使用mip-validator创建一个实例，即可用来验证MIP HTML。

const Validator = require('mip-validator');
// 使用默认规则创建实例，等效于：Validator(Validator.rules);
var validator = Validator(); 
var errs = validator.validate('<html><div></div></html>')
console.log(errs);

命令行接口

需要全局安装mip-validator（见上一节）。输入输出：

使用标准输入HTML（String类型）
标准输出的错误列表（JSON格式）

例如：

$ mip-validator < a.html                # 校验 a.html
$ mip-validator < a.html -t custom      # 校验 a.html
$ mip-validator < a.html > a.html.json  # 也可将验证结果重定向至文件
$ mip-validator --help                  # 查看更多参数
  Usage: cli [options]
  Options:
    -h, --help         output usage information
    -V, --version      output the version number
    -c, --conf [path]  validator configuration file [rules.json]
    -f, --fast         use fast mode, abort on first error
    -t, --type <type>  optional, specify the type of mip page

例如定制化 MIP 通过 mip-validator -t custom 来校验。

浏览器JS

MIP校验框架可以在浏览器端使用，通过window.MIPValidator提供API。
将dist/mip-validator.js引入页面后，在页面脚本中可直接使用，用法与Node.js端完全相同：

var Validator = window.MIPValidator;
var validator = Validator();

HTTP Service

$ mip-validator-http

端口与主机可以通过参数更改，更多信息请运行mip-validator-http -h。

然后访问http://localhost:4444，可以看到简单的使用说明。
示例客户端程序见：demo/http.js。

校验HTML文档：POST /validate，Request Body为待校验HTML字符串。
快速校验HTML文档：POST /validate?fast=true，Request Body为待校验HTML字符串。

例如：

curl localhost:4444/validate -X POST --data '<html></html>'

开启快速校验时，只能获得第一个校验错误。因此运行也稍快。

Socket Service

Socket服务只支持快速校验模式，不需要设置。

$ mip-validator-socket

创建Socket Client并连接到localhost:4445，逐个发送HTML。
HTML文本之间以__baidu_mip_validator__分隔，
返回的字符串也以__baidu_mip_validator__分隔。
对于每个HTML，将按顺序返回一个字符串序列化的JSON。
示例客户端程序见：demo/socket.js。

统一使用UTF-8编码。
协议仍待增强（字符串Escape未实现）。

端口与主机可以通过参数更改，更多信息请运行mip-validator-socket -h。

API

`new Validator(<rules>)`

根据传入的校验规则，以及校验器配置返回一个校验器实例。

`<rules>`

可选，默认值：Validator.rules。

默认值的内容见rules.json，语法见rules wiki。

为false, undefined, null时会应用默认值，
为Object（例如{}）时会应用该规则定义对象。
如果你希望使用旧版规则（rules.json），或者希望探索MIP校验框架内部的逻辑，
或者在发明新的校验规则，可以使用此参数。

var rules = {
    div: {
        mandatory: true
    }
};
var validator = Validator(rules);

`.validate(html, <config>)`

传入HTML字符串，返回错误列表（如果完全正确，则返回空数组）。config 可选。

`html`

必选，类型为 String。

传入待校验的 HTML 字符串，应该是完整的被校验 HTML 内容。

`<config.fastMode>`

可选，类型为 Boolean，默认值：false

为true时mip-validator在第一个错误发生就立即返回。
否则mip-validator会找到所有错误。例如：

validator.validate(html, {fastMode: true});

`<config.type>`

可选，类型为 String，无默认值。取值列表：

"custom"：校验定制化 MIP。

例如：

validator.validate(html, {type: 'custom'});

`Validator.rules`

默认的MIP校验规则（<rules>的默认值），可在其基础上进行定制，例如：

var rules = Validator.rules;
rules.div = {
    mandatory: rules.iframe.mandatory
};
var validator = Validator(rules);

开发指南

环境准备

确保安装了Node.js(>=4)，然后克隆仓库并安装依赖。

git clone xxx
npm install

单元测试

可以使用NPM Script进行测试，也可以全局安装mocha后直接运行Mocha。

# 使用NPM Script
npm test
# 或者直接运行（需要安装mocha）：
mocha

集成测试

目前利用Makefile可以方便地校验cases/下的样例文件，其中：

cases/*.html: 样例HTML
cases/*.json: 对应样例HTML的校验结果

集成测试我们用 Git 来管理，生成集成测试结果：

make cases
git diff        # 对，就是用 Git 来查看 😀

如果cases/*.json存在 Diff，说明校验有问题或者要升级。
如果是前者那就继续调试，如果是后者那就直接 Commit。

构建浏览器JS

mip-validator依赖于Node.js 4以上，
但本项目通过Browserify提供了在浏览器JS。
可通过下列命令重新生成：

# 输出到 dist/ 目录：mip-validator.min.js, mip-validator.js
make dist

工具脚本

工具脚本位于bin目录下：

bin/cli.js

命令行接口，通过package.json暴露给NPM。

bin/benchmark.js

简单的性能测试，运行cases/htmls下的所有样例，
并统计运行时间。使用方式：

node bin/benchmark.js

bin/md-error.js

将错误代码转换为Markdown文件，用于Wiki或其他Doc。