MIP Validator


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

依赖与安装

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

``bash


编程方式访问，将会安装到 ./node_modules/mip-validator

npm install -S mip-validator

命令行接口

sudo npm install -g mip-validator
`

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

`bash
npm install mip-validator
`

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

使用方式

$3

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

`javascript
const Validator = require('mip-validator');

// 使用默认规则创建实例，等效于：Validator(Validator.rules);
var validator = Validator();
var errs = validator.validate('

')
console.log(errs);
`

$3

需要全局安装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 optional, specify the type of mip page
`

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

$3

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

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

$3

`
$ 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字符串。

例如：

`bash
curl localhost:4444/validate -X POST --data ''
`

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

$3

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

$3

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

####

可选，默认值：Validator.rules。

> 默认值的内容见rules.json，语法见[rules wiki][rules-syntax]。

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

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

$3

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

#### html

必选，类型为 String。

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

####

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

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

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

####

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

* "custom"：校验定制化 MIP。

例如：

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

$3

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

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

开发指南

$3

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

`bash
git clone xxx
npm install
`

$3

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

`bash


使用NPM Script

npm test

或者直接运行（需要安装mocha）：

mocha
`

$3

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

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

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

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

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

$3

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

`bash


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


make dist
`

$3

工具脚本位于bin目录下：

#### bin/cli.js

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

#### bin/benchmark.js

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

`bash
node bin/benchmark.js
``

#### bin/md-error.js

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

[wiki]: https://github.com/mipengine/mip-validator/wiki
[rules-syntax]: https://github.com/mipengine/mip-validator/wiki/%E8%A7%84%E5%88%99%E9%85%8D%E7%BD%AE%E8%AF%AD%E6%B3%95