{"id":19751147,"url":"https://github.com/mipengine/mip-validator","last_synced_at":"2025-02-28T00:49:20.982Z","repository":{"id":57298277,"uuid":"68980041","full_name":"mipengine/mip-validator","owner":"mipengine","description":"MIP validator","archived":false,"fork":false,"pushed_at":"2019-06-27T08:14:05.000Z","size":3809,"stargazers_count":10,"open_issues_count":5,"forks_count":11,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-05-01T23:58:10.737Z","etag":null,"topics":["cli","http","mip","socket","validator"],"latest_commit_sha":null,"homepage":"https://www.mipengine.org/validator/validate","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mipengine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-23T02:14:07.000Z","updated_at":"2024-05-01T23:58:10.738Z","dependencies_parsed_at":"2022-09-06T04:20:45.177Z","dependency_job_id":null,"html_url":"https://github.com/mipengine/mip-validator","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mipengine%2Fmip-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mipengine%2Fmip-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mipengine%2Fmip-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mipengine%2Fmip-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mipengine","download_url":"https://codeload.github.com/mipengine/mip-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241080831,"owners_count":19906356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","http","mip","socket","validator"],"created_at":"2024-11-12T02:42:38.148Z","updated_at":"2025-02-28T00:49:20.713Z","avatar_url":"https://github.com/mipengine.png","language":"HTML","readme":"# MIP Validator\n\n[![NPM version](https://img.shields.io/npm/v/mip-validator.svg?style=flat)](https://www.npmjs.org/package/mip-validator)\n[![Build Status](https://travis-ci.org/mipengine/mip-validator.svg?branch=master)](https://travis-ci.org/mipengine/mip-validator)\n[![Coverage Status](https://coveralls.io/repos/github/mipengine/mip-validator/badge.svg?branch=master)](https://coveralls.io/github/mipengine/mip-validator?branch=master)\n[![Dependency manager](https://david-dm.org/mipengine/mip-validator/status.svg)](https://david-dm.org/mipengine/mip-validator)\n\n本项目给出用于MIP校验的NPM软件包，支持编程方式、命令行接口、以及浏览器JS。\n本文档介绍MIP校验框架的使用和开发方式，其他相关文档请参考[Wiki][wiki]。\n\n## 依赖与安装\n\n确保安装了Node.js(版本\u003e=4)，然后使用npm安装`mip-validator`。\n\n```bash\n# 编程方式访问，将会安装到 ./node_modules/mip-validator\nnpm install -S mip-validator\n# 命令行接口\nsudo npm install -g mip-validator\n```\n\n注意：对于命令行接口，如果没有管理员权限可安装在本地（不加`-g`参数）：\n\n```bash\nnpm install mip-validator\n```\n\n以后使用时用本地的可执行文件`./node_modules/.bin/mip-validator`代替全局可执行文件`mip-validator`。\n\n## 使用方式\n\n### 编程接口\n\n在本地安装`mip-validator`（即安装于`node_modules`目录下）。\n使用`mip-validator`创建一个实例，即可用来验证MIP HTML。\n\n```javascript\nconst Validator = require('mip-validator');\n\n// 使用默认规则创建实例，等效于：Validator(Validator.rules);\nvar validator = Validator(); \nvar errs = validator.validate('\u003chtml\u003e\u003cdiv\u003e\u003c/div\u003e\u003c/html\u003e')\nconsole.log(errs);\n```\n\n### 命令行接口\n\n需要全局安装`mip-validator`（见上一节）。输入输出：\n\n* 使用标准输入HTML（String类型）\n* 标准输出的错误列表（JSON格式）\n\n例如：\n\n```\n$ mip-validator \u003c a.html                # 校验 a.html\n$ mip-validator \u003c a.html -t custom      # 校验 a.html\n$ mip-validator \u003c a.html \u003e a.html.json  # 也可将验证结果重定向至文件\n$ mip-validator --help                  # 查看更多参数\n\n  Usage: cli [options]\n\n  Options:\n\n    -h, --help         output usage information\n    -V, --version      output the version number\n    -c, --conf [path]  validator configuration file [rules.json]\n    -f, --fast         use fast mode, abort on first error\n    -t, --type \u003ctype\u003e  optional, specify the type of mip page\n```\n\n\u003e 例如定制化 MIP 通过 `mip-validator -t custom` 来校验。\n\n### 浏览器JS\n\nMIP校验框架可以在浏览器端使用，通过`window.MIPValidator`提供API。\n将`dist/mip-validator.js`引入页面后，在页面脚本中可直接使用，用法与Node.js端完全相同：\n\n```javascript\nvar Validator = window.MIPValidator;\nvar validator = Validator();\n```\n\n### HTTP Service\n\n```\n$ mip-validator-http\n```\n\n\u003e 端口与主机可以通过参数更改，更多信息请运行`mip-validator-http -h`。\n\n然后访问`http://localhost:4444`，可以看到简单的使用说明。\n示例客户端程序见：[demo/http.js](demo/http.js)。\n\n* 校验HTML文档：POST `/validate`，Request Body为待校验HTML字符串。\n* 快速校验HTML文档：POST `/validate?fast=true`，Request Body为待校验HTML字符串。\n\n例如：\n\n```bash\ncurl localhost:4444/validate -X POST --data '\u003chtml\u003e\u003c/html\u003e'\n```\n\n\u003e 开启快速校验时，只能获得第一个校验错误。因此运行也稍快。\n\n### Socket Service\n\nSocket服务只支持快速校验模式，不需要设置。\n\n```\n$ mip-validator-socket\n```\n\n创建Socket Client并连接到`localhost:4445`，逐个发送HTML。\nHTML文本之间以`__baidu_mip_validator__`分隔，\n返回的字符串也以`__baidu_mip_validator__`分隔。\n对于每个HTML，将按顺序返回一个字符串序列化的JSON。\n示例客户端程序见：[demo/socket.js](demo/socket.js)。\n\n* 统一使用UTF-8编码。\n* 协议仍待增强（字符串Escape未实现）。\n\n\u003e 端口与主机可以通过参数更改，更多信息请运行`mip-validator-socket -h`。\n\n## API\n\n### `new Validator(\u003crules\u003e)`\n\n根据传入的校验规则，以及校验器配置返回一个校验器实例。\n\n#### `\u003crules\u003e`\n\n可选，默认值：`Validator.rules`。\n\n\u003e 默认值的内容见[rules.json](rules.json)，语法见[rules wiki][rules-syntax]。\n\n为`false`, `undefined`, `null`时会应用默认值，\n为Object（例如`{}`）时会应用该规则定义对象。\n如果你希望使用旧版规则（rules.json），或者希望探索MIP校验框架内部的逻辑，\n或者在发明新的校验规则，可以使用此参数。\n\n```javascript\nvar rules = {\n    div: {\n        mandatory: true\n    }\n};\nvar validator = Validator(rules);\n```\n\n### `.validate(html, \u003cconfig\u003e)`\n\n传入HTML字符串，返回错误列表（如果完全正确，则返回空数组）。`config` 可选。\n\n#### `html`\n\n必选，类型为 `String`。\n\n传入待校验的 HTML 字符串，应该是完整的被校验 HTML 内容。\n\n#### `\u003cconfig.fastMode\u003e`\n\n可选，类型为 `Boolean`，默认值：`false`\n\n为`true`时mip-validator在第一个错误发生就立即返回。\n否则mip-validator会找到所有错误。例如：\n\n```javascript\nvalidator.validate(html, {fastMode: true});\n```\n\n#### `\u003cconfig.type\u003e`\n\n可选，类型为 `String`，无默认值。取值列表：\n\n* `\"custom\"`：校验定制化 MIP。\n\n例如：\n\n```javascript\nvalidator.validate(html, {type: 'custom'});\n```\n\n### `Validator.rules`\n\n默认的MIP校验规则（`\u003crules\u003e`的默认值），可在其基础上进行定制，例如：\n\n```javascript\nvar rules = Validator.rules;\nrules.div = {\n    mandatory: rules.iframe.mandatory\n};\nvar validator = Validator(rules);\n```\n\n## 开发指南\n\n### 环境准备\n\n确保安装了Node.js(\u003e=4)，然后克隆仓库并安装依赖。\n\n```bash\ngit clone xxx\nnpm install\n```\n\n### 单元测试\n\n可以使用NPM Script进行测试，也可以全局安装`mocha`后直接运行Mocha。\n\n```bash\n# 使用NPM Script\nnpm test\n\n# 或者直接运行（需要安装mocha）：\nmocha\n```\n\n### 集成测试\n\n目前利用Makefile可以方便地校验`cases/`下的样例文件，其中：\n\n* `cases/*.html`: 样例HTML\n* `cases/*.json`: 对应样例HTML的校验结果\n\n集成测试我们用 Git 来管理，生成集成测试结果：\n\n```bash\nmake cases\ngit diff        # 对，就是用 Git 来查看 😀\n```\n\n如果`cases/*.json`存在 Diff，说明校验有问题或者要升级。\n如果是前者那就继续调试，如果是后者那就直接 Commit。\n\n### 构建浏览器JS\n\nmip-validator依赖于Node.js 4以上，\n但本项目通过Browserify提供了在浏览器JS。\n可通过下列命令重新生成：\n\n```bash\n# 输出到 dist/ 目录：mip-validator.min.js, mip-validator.js\nmake dist\n```\n\n### 工具脚本\n\n工具脚本位于[bin](bin)目录下：\n\n#### bin/cli.js\n\n命令行接口，通过package.json暴露给NPM。\n\n#### bin/benchmark.js\n\n简单的性能测试，运行[cases/htmls](cases/htmls)下的所有样例，\n并统计运行时间。使用方式：\n\n```bash\nnode bin/benchmark.js\n```\n\n#### bin/md-error.js\n\n将[错误代码](src/error/dfn.json)转换为Markdown文件，用于Wiki或其他Doc。\n\n[wiki]: https://github.com/mipengine/mip-validator/wiki\n[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\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmipengine%2Fmip-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmipengine%2Fmip-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmipengine%2Fmip-validator/lists"}