mm_validate 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 qww
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# mm_validate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一个轻量的 Node.js 参数验证模块。按 **JSON Schema 常用子集** 校验参数，校验失败时返回**首个**错误信息，并通过字段路径直接定位出错位置。
+
+- 入口：`index.js`（CommonJS）
+- 运行时依赖：无
+- 测试覆盖率：100%（见 `jest.config.js` 阈值）
+
+## 特性
+
+- **零依赖**：只依赖 Node.js 原生能力，安装体积小。
+- **短路返回**：按关键字顺序校验，命中第一个错误立即返回。
+- **路径提示**：嵌套对象与数组的错误信息自动附带路径，如 `user.age`、`[1].id`。
+- **递归校验**：支持 `properties` 与 `items` 的任意层级嵌套。
+- **结果简单**：通过返回空字符串 `''`，失败返回错误描述，便于直接用于 `if` 判断。
+
+## 安装
+
+```bash
+npm install mm_validate
+```
+
+## 环境要求
+
+- Node.js >= 16
+- 模块规范：CommonJS
+
+## 快速开始
+
+```js
+'use strict';
+
+const { Validate } = require('mm_validate');
+
+const schema = {
+  type: 'object',
+  required: ['name', 'age'],
+  properties: {
+    name: { type: 'string', min_length: 2, max_length: 20 },
+    age: { type: 'integer', minimum: 0, maximum: 150 },
+    role: { type: 'string', enum: ['admin', 'user'] },
+    tags: { type: 'array', items: { type: 'string' } }
+  }
+};
+
+const validate = new Validate(schema);
+
+console.log(validate.check({ name: '张三', age: 28, role: 'admin', tags: ['a'] }));
+// ''
+
+console.log(validate.check({ name: '张三' }));
+// 'age: required missing'
+
+console.log(validate.check({ name: '张三', age: 'x' }));
+// 'age: type expected "integer" but got "string"'
+```
+
+## API
+
+### `new Validate(config = {})`
+
+创建一个校验器。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `config` | `Object` | 校验配置（JSON Schema 常用子集）。传入非对象（如 `null`、数组）时不执行任何校验。 |
+
+校验器会按引用保存配置，可在创建后修改 `validate.config` 复用实例。
+
+### `check(params)`
+
+校验参数。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `params` | `*` | 待校验的参数。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `''` | 校验通过 |
+| `string` | 校验失败，返回首个错误信息（含字段路径） |
+
+## 支持的校验关键字
+
+| 关键字 | 适用类型 | 说明 | 错误示例 |
+| --- | --- | --- | --- |
+| `type` | 任意 | 数据类型：`null` / `array` / `object` / `string` / `number` / `integer` / `boolean`。`number` 不接受 `NaN`、`Infinity` | `type expected "string" but got "number"` |
+| `enum` | 任意 | 值必须属于枚举数组 | `enum expected ["admin","user"] but got "guest"` |
+| `const` | 任意 | 值必须严格等于指定值 | `const expected 1 but got 2` |
+| `min_length` | `string` | 字符串最小长度 | `min_length expected >= 3 but got 2` |
+| `max_length` | `string` | 字符串最大长度 | `max_length expected <= 1 but got 2` |
+| `minimum` | `number` | 数值下限（包含） | `minimum expected >= 3 but got 2` |
+| `maximum` | `number` | 数值上限（包含） | `maximum expected <= 1 but got 2` |
+| `pattern` | `string` | 正则表达式（字符串形式） | `pattern expected match /^[a-z]+$/ but got "qww123"` |
+| `required` | `object` | 必填字段名数组 | `name: required missing` |
+| `properties` | `object` | 子字段配置，递归校验 | `user.age: type expected "number" but got "string"` |
+| `items` | `array` | 数组元素配置，递归校验 | `[1].id: type expected "number" but got "string"` |
+
+校验顺序为：`type` → `enum` → `const` → `min_length` / `max_length` → `minimum` / `maximum` → `pattern` → `required` → `properties` → `items`。
+
+未声明或类型不符合要求的关键字会被跳过。例如 `min_length` 只对字符串生效，`required` 只对对象生效。
+
+## 错误信息与路径
+
+错误信息格式为 `路径: 错误详情`，顶层错误不带路径前缀。
+
+| 场景 | 路径示例 |
+| --- | --- |
+| 顶层字段 | `age` |
+| 嵌套对象 | `user.age` |
+| 数组元素 | `[1]` |
+| 对象数组元素字段 | `[1].id` |
+| 嵌套数组 | `[1][1]` |
+
+## 在接口中校验参数
+
+```js
+'use strict';
+
+const { Validate } = require('mm_validate');
+
+const ARTICLE_SCHEMA = {
+  type: 'object',
+  required: ['title', 'content', 'status'],
+  properties: {
+    title: { type: 'string', min_length: 2, max_length: 50 },
+    content: { type: 'string', min_length: 1 },
+    status: { type: 'string', enum: ['draft', 'published'] },
+    views: { type: 'integer', minimum: 0 },
+    tags: { type: 'array', items: { type: 'string', min_length: 1 } }
+  }
+};
+
+/**
+ * 校验接口请求参数
+ * @param {Object} params 请求参数
+ * @returns {{code: number, msg: string}} 校验结果
+ */
+function validateRequest(params) {
+  const tip = new Validate(ARTICLE_SCHEMA).check(params);
+  return tip === '' ? { code: 0, msg: 'ok' } : { code: 1, msg: tip };
+}
+
+console.log(
+  validateRequest({
+    title: 'mm_validate 使用说明',
+    content: '按 JSON Schema 常用子集校验参数。',
+    status: 'published'
+  })
+);
+// { code: 0, msg: 'ok' }
+
+console.log(validateRequest({ title: 'a', content: '', status: 'deleted' }));
+// { code: 1, msg: 'title: min_length expected >= 2 but got 1' }
+```
+
+## 运行示例
+
+```bash
+npm run demo
+```
+
+示例覆盖基础类型、对象嵌套、数组元素、接口参数四类场景，源码见 `example/index.js`。
+
+## 测试
+
+```bash
+npm test
+```
+
+使用 Jest 运行单元测试并生成覆盖率报告。`jest.config.js` 已配置语句、分支、函数、行覆盖率均为 **100%**，未达标时命令会失败。
+
+## 目录结构
+
+```
+mm_validate/
+├── index.js          # 入口，导出 Validate
+├── lib/
+│   └── validate.js   # 校验器实现
+├── example/
+│   └── index.js      # 使用示例
+├── test/
+│   ├── index.test.js
+│   └── validate.test.js
+├── jest.config.js
+└── package.json
+```
+
+## 许可证
+
+[ISC](LICENSE)

package/example/index.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const { Validate } = require('../index');
+
+const ARTICLE_SCHEMA = {
+  type: 'object',
+  required: ['title', 'content', 'status'],
+  properties: {
+    title: { type: 'string', min_length: 2, max_length: 50 },
+    content: { type: 'string', min_length: 1 },
+    status: { type: 'string', enum: ['draft', 'published'] },
+    views: { type: 'integer', minimum: 0 },
+    tags: { type: 'array', items: { type: 'string', min_length: 1 } }
+  }
+};
+
+/**
+ * 输出单次校验结果
+ * @param {string} title 场景名称
+ * @param {Object} schema 校验配置
+ * @param {*} params 调用参数
+ * @returns {void}
+ */
+function printResult(title, schema, params) {
+  const tip = new Validate(schema).check(params);
+  const result = tip === '' ? '通过' : tip;
+  console.log(`${title} -> ${result}`);
+}
+
+/**
+ * 基础类型校验
+ * @returns {void}
+ */
+function demoBasic() {
+  console.log('=== 基础类型校验 ===');
+  printResult('字符串通过', { type: 'string' }, 'hello');
+  printResult('字符串失败', { type: 'string' }, 100);
+  printResult('整数通过', { type: 'integer', minimum: 0, maximum: 150 }, 30);
+  printResult('整数失败', { type: 'integer', minimum: 0 }, 1.5);
+  printResult('枚举失败', { type: 'string', enum: ['admin', 'user'] }, 'guest');
+  printResult('正则失败', { type: 'string', pattern: '^[a-z]+$' }, 'qww123');
+}
+
+/**
+ * 对象与嵌套字段校验
+ * @returns {void}
+ */
+function demoObject() {
+  console.log('=== 对象校验 ===');
+  const schema = {
+    type: 'object',
+    required: ['name', 'age'],
+    properties: {
+      name: { type: 'string', min_length: 1 },
+      age: { type: 'integer', minimum: 0, maximum: 150 },
+      address: {
+        type: 'object',
+        required: ['city'],
+        properties: { city: { type: 'string' } }
+      }
+    }
+  };
+
+  printResult('对象通过', schema, { name: '张三', age: 28, address: { city: '广州' } });
+  printResult('缺少必填字段', schema, { name: '张三' });
+  printResult('嵌套字段错误', schema, { name: '张三', age: 28, address: {} });
+}
+
+/**
+ * 数组元素校验
+ * @returns {void}
+ */
+function demoArray() {
+  console.log('=== 数组校验 ===');
+  const schema = { type: 'array', items: { type: 'number' } };
+  printResult('数组通过', schema, [1, 2, 3]);
+  printResult('数组元素错误', schema, [1, 'x', 3]);
+}
+
+/**
+ * 校验接口请求参数并返回统一结构
+ * @param {Object} params 请求参数
+ * @returns {{code: number, msg: string}} 校验结果
+ */
+function validateRequest(params) {
+  const tip = new Validate(ARTICLE_SCHEMA).check(params);
+  return tip === '' ? { code: 0, msg: 'ok' } : { code: 1, msg: tip };
+}
+
+/**
+ * 接口参数校验场景
+ * @returns {void}
+ */
+function demoRequest() {
+  console.log('=== 接口参数校验 ===');
+  const ok_params = {
+    title: 'mm_validate 使用说明',
+    content: '按 JSON Schema 常用子集校验参数。',
+    status: 'published',
+    views: 100,
+    tags: ['nodejs', 'validate']
+  };
+  console.log('合法参数 ->', validateRequest(ok_params));
+
+  const bad_params = { title: 'a', content: '', status: 'deleted', views: -1, tags: [''] };
+  console.log('非法参数 ->', validateRequest(bad_params));
+}
+
+/**
+ * 运行全部示例
+ * @returns {void}
+ */
+function demo() {
+  demoBasic();
+  demoObject();
+  demoArray();
+  demoRequest();
+}
+
+demo();

package/index.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const Admin = require('mm_corejs').Admin;
+const Validate = require('./lib/validate');
+
+const admin = new Admin();
+admin.setClass(Validate);
+
+module.exports = {
+  Validate,
+  admin,
+  /**
+   * 获取指定作用域的校验器实例，不存在时创建
+   * @param {string} [scope] 作用域名称，缺省时使用 os
+   * @param {Object} [config] 校验配置（JSON Schema 常用子集）
+   * @returns {Validate} 校验器实例
+   */
+  validateAdmin(scope, config = {}) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/validate.js

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * 参数验证器 —— 按 JSON Schema 常用子集校验参数，返回首个错误信息。
+ *
+ * 支持的关键字：
+ *   type / enum / const / min_length / max_length / minimum / maximum
+ *   pattern / required / properties / items
+ *
+ * 用法：
+ *   new Validate(schema).check(params) === '' 表示通过。
+ */
+class Validate {
+  /**
+   * 构造函数
+   * @param {Object} config 校验配置（JSON Schema 常用子集），非对象时视为不校验
+   */
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * 校验参数
+   * @param {*} params 调用参数
+   * @returns {string} 验证通过返回空字符串，否则返回首个错误信息
+   */
+  check(params) {
+    return this._checkSchema(params, this.config, '');
+  }
+
+  // ---------- 校验编排 ----------
+  /**
+   * 按 schema 递归校验任意值，按关键字顺序短路返回首个错误
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkSchema(value, schema, path) {
+    if (!this._isObject(schema)) return '';
+    return (
+      this._checkType(value, schema, path) ||
+      this._checkEnum(value, schema, path) ||
+      this._checkConst(value, schema, path) ||
+      this._checkLength(value, schema, path) ||
+      this._checkRange(value, schema, path) ||
+      this._checkPattern(value, schema, path) ||
+      this._checkRequired(value, schema, path) ||
+      this._checkProperties(value, schema, path) ||
+      this._checkItems(value, schema, path)
+    );
+  }
+
+  // ---------- 关键字校验 ----------
+  /**
+   * 校验 type 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkType(value, schema, path) {
+    if (schema.type === undefined) return '';
+    if (this._isType(value, schema.type)) return '';
+    const detail = `type expected "${schema.type}" but got "${this._getTypeName(value)}"`;
+    return this._getPathMessage(path, detail);
+  }
+
+  /**
+   * 校验 enum 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkEnum(value, schema, path) {
+    if (!Array.isArray(schema.enum)) return '';
+    if (schema.enum.includes(value)) return '';
+    const detail = `enum expected ${JSON.stringify(schema.enum)} but got ${JSON.stringify(value)}`;
+    return this._getPathMessage(path, detail);
+  }
+
+  /**
+   * 校验 const 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkConst(value, schema, path) {
+    if (schema.const === undefined) return '';
+    if (value === schema.const) return '';
+    const detail = `const expected ${JSON.stringify(schema.const)} but got ${JSON.stringify(value)}`;
+    return this._getPathMessage(path, detail);
+  }
+
+  /**
+   * 校验 min_length / max_length 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkLength(value, schema, path) {
+    if (typeof value !== 'string') return '';
+    if (typeof schema.min_length === 'number' && value.length < schema.min_length) {
+      const detail = `min_length expected >= ${schema.min_length} but got ${value.length}`;
+      return this._getPathMessage(path, detail);
+    }
+    if (typeof schema.max_length === 'number' && value.length > schema.max_length) {
+      const detail = `max_length expected <= ${schema.max_length} but got ${value.length}`;
+      return this._getPathMessage(path, detail);
+    }
+    return '';
+  }
+
+  /**
+   * 校验 minimum / maximum 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkRange(value, schema, path) {
+    if (typeof value !== 'number') return '';
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+      const detail = `minimum expected >= ${schema.minimum} but got ${value}`;
+      return this._getPathMessage(path, detail);
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+      const detail = `maximum expected <= ${schema.maximum} but got ${value}`;
+      return this._getPathMessage(path, detail);
+    }
+    return '';
+  }
+
+  /**
+   * 校验 pattern 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkPattern(value, schema, path) {
+    if (typeof value !== 'string') return '';
+    if (typeof schema.pattern !== 'string') return '';
+    if (new RegExp(schema.pattern).test(value)) return '';
+    const detail = `pattern expected match /${schema.pattern}/ but got "${value}"`;
+    return this._getPathMessage(path, detail);
+  }
+
+  /**
+   * 校验 required 关键字
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkRequired(value, schema, path) {
+    if (!Array.isArray(schema.required)) return '';
+    if (!this._isObject(value)) return '';
+    for (const key of schema.required) {
+      if (this._isOwnProperty(value, key)) continue;
+      return this._getPathMessage(this._getKeyPath(path, key), 'required missing');
+    }
+    return '';
+  }
+
+  /**
+   * 校验 properties 关键字（递归）
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkProperties(value, schema, path) {
+    if (!this._isObject(schema.properties)) return '';
+    if (!this._isObject(value)) return '';
+    for (const key of Object.keys(schema.properties)) {
+      if (!this._isOwnProperty(value, key)) continue;
+      const tip = this._checkSchema(value[key], schema.properties[key], this._getKeyPath(path, key));
+      if (tip) return tip;
+    }
+    return '';
+  }
+
+  /**
+   * 校验 items 关键字（递归）
+   * @param {*} value 待校验值
+   * @param {Object} schema 校验配置
+   * @param {string} path 字段路径
+   * @returns {string} 错误信息或空字符串
+   */
+  _checkItems(value, schema, path) {
+    if (!this._isObject(schema.items)) return '';
+    if (!Array.isArray(value)) return '';
+    for (let i = 0; i < value.length; i++) {
+      const tip = this._checkSchema(value[i], schema.items, this._getArrayPath(path, i));
+      if (tip) return tip;
+    }
+    return '';
+  }
+
+  // ---------- 类型判定 ----------
+  /**
+   * 判断值是否匹配指定 JSON 类型
+   * @param {*} value 待判定值
+   * @param {string} type 类型名称
+   * @returns {boolean} 是否匹配
+   */
+  _isType(value, type) {
+    switch (type) {
+      case 'null':
+        return value === null;
+      case 'array':
+        return Array.isArray(value);
+      case 'object':
+        return this._isObject(value);
+      case 'string':
+        return typeof value === 'string';
+      case 'number':
+        return this._isFiniteNumber(value);
+      case 'integer':
+        return Number.isInteger(value);
+      case 'boolean':
+        return typeof value === 'boolean';
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * 获取值的 JSON 类型名称
+   * @param {*} value 待判定值
+   * @returns {string} 类型名称
+   */
+  _getTypeName(value) {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+  }
+
+  /**
+   * 判断值是否为有限数字（排除 NaN / Infinity）
+   * @param {*} value 待判定值
+   * @returns {boolean} 是否为有限数字
+   */
+  _isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+  }
+
+  /**
+   * 判断值是否为普通对象（排除 null 与数组）
+   * @param {*} value 待判定值
+   * @returns {boolean} 是否为普通对象
+   */
+  _isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+
+  // ---------- 路径与属性 ----------
+  /**
+   * 判断对象自身是否包含指定字段
+   * @param {Object} target 目标对象
+   * @param {string} key 字段名
+   * @returns {boolean} 是否包含该字段
+   */
+  _isOwnProperty(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key);
+  }
+
+  /**
+   * 拼接对象字段路径
+   * @param {string} path 父级路径
+   * @param {string} key 字段名
+   * @returns {string} 字段路径
+   */
+  _getKeyPath(path, key) {
+    return path ? `${path}.${key}` : key;
+  }
+
+  /**
+   * 拼接数组元素路径
+   * @param {string} path 父级路径
+   * @param {number} index 元素下标
+   * @returns {string} 元素路径
+   */
+  _getArrayPath(path, index) {
+    return `${path}[${index}]`;
+  }
+
+  /**
+   * 为错误详情附加路径前缀
+   * @param {string} path 字段路径
+   * @param {string} detail 错误详情
+   * @returns {string} 完整错误信息
+   */
+  _getPathMessage(path, detail) {
+    return path ? `${path}: ${detail}` : detail;
+  }
+}
+
+module.exports = Validate;

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "mm_validate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "这是一个通用的 Node.js 参数验证模块，按 JSON Schema 常用子集校验参数，返回首个错误信息。",
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_common",
+    "超级美眉",
+    "参数验证",
+    "数据校验",
+    "json schema",
+    "validate",
+    "validator",
+    "schema",
+    "nodejs",
+    "commonjs"
+  ],
+  "layer": "infra",
+  "group": "common",
+  "author": "邱文武",
+  "license": "ISC",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=16"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "example"
+  ],
+  "directories": {
+    "example": "example",
+    "lib": "lib"
+  },
+  "homepage": "https://gitee.com/qiuwenwu91/mm_validate#readme",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_validate/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_validate.git"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "demo": "node example/index.js",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}