MongoDB 导出器文档

模块: src/exporters/MongoDBExporter.ts

用途: 将 JSON Schema 转换为 MongoDB 验证 Schema

📑 目录

概述
快速开始
API 参考
配置选项
完整示例
类型映射

概述

MongoDBExporter 将 schema-dsl 生成的 JSON Schema 转换为 MongoDB 的 $jsonSchema 验证格式，可直接用于创建集合时的文档验证。

核心功能

✅ 转换为 MongoDB $jsonSchema 格式
✅ 自动映射类型为 BSON 类型
✅ 保留所有约束条件
✅ 生成 createCollection 命令
✅ 支持严格/宽松验证模式

快速开始

const { dsl, exporters } = require('schema-dsl');

// 1. 定义 Schema
const userSchema = dsl({
  username: 'string:3-32!',
  email: 'email!',
  age: 'number:18-120'
});

// 2. 创建导出器
const exporter = new exporters.MongoDBExporter();

// 3. 导出为 MongoDB Schema
const mongoSchema = exporter.export(userSchema);
console.log(JSON.stringify(mongoSchema, null, 2));

输出：

{
  "$jsonSchema": {
    "bsonType": "object",
    "required": ["username", "email"],
    "properties": {
      "username": {
        "bsonType": "string",
        "minLength": 3,
        "maxLength": 32
      },
      "email": {
        "bsonType": "string"
      },
      "age": {
        "bsonType": "double",
        "minimum": 18,
        "maximum": 120
      }
    }
  }
}

API 参考

构造函数

new MongoDBExporter(options)

参数：

参数	类型	默认值	说明
`options.strict`	boolean	`false`	是否使用严格验证模式

方法

`export(jsonSchema)`

将 JSON Schema 转换为 MongoDB 验证 Schema。

const mongoSchema = exporter.export(jsonSchema);

参数：

jsonSchema (Object): schema-dsl 生成的 JSON Schema 对象

返回值：

Object: 包含 $jsonSchema 的 MongoDB 验证对象

`generateCreateCommand(collectionName, jsonSchema)`

生成 createCollection 命令对象。

const command = exporter.generateCreateCommand('users', userSchema);

参数：

collectionName (string): 集合名称
jsonSchema (Object): JSON Schema 对象

返回值：

{
  collectionName: 'users',
  options: {
    validator: { $jsonSchema: {...} },
    validationLevel: 'moderate',  // 或 'strict'
    validationAction: 'error'
  }
}

`generateCommand(collectionName, jsonSchema)`

生成可执行的 MongoDB 命令字符串。

const commandStr = exporter.generateCommand('users', userSchema);
console.log(commandStr);

输出：

db.createCollection("users", {
  "validator": {
    "$jsonSchema": {
      "bsonType": "object",
      ...
    }
  },
  "validationLevel": "moderate",
  "validationAction": "error"
})

`MongoDBExporter.export(jsonSchema)` (静态方法)

快速导出，无需实例化。

const mongoSchema = exporters.MongoDBExporter.export(userSchema);

配置选项

验证模式

模式	说明
`strict: false` (默认)	`validationLevel: 'moderate'` - 只验证插入和更新操作中涉及的字段
`strict: true`	`validationLevel: 'strict'` - 验证所有插入和更新操作

// 严格模式
const strictExporter = new exporters.MongoDBExporter({ strict: true });

完整示例

用户集合验证

const { dsl, exporters } = require('schema-dsl');

// 定义复杂用户 Schema
const userSchema = dsl({
  _id: 'string!',
  username: 'string:3-32!'
    .pattern(/^[a-zA-Z0-9_]+$/)
    .label('用户名'),
  email: 'email!'.label('邮箱'),
  profile: {
    bio: 'string:500',
    avatar: 'url'
  },
  status: 'active|inactive|banned',
  createdAt: 'datetime!'
});

// 导出并生成命令
const exporter = new exporters.MongoDBExporter({ strict: true });
const command = exporter.generateCommand('users', userSchema);

console.log(command);

在 MongoDB 中使用

const { MongoClient } = require('mongodb');

async function createValidatedCollection() {
  const client = new MongoClient('mongodb://localhost:27017');
  await client.connect();

  const db = client.db('myapp');
  
  // 获取验证 Schema
  const exporter = new exporters.MongoDBExporter({ strict: true });
  const { options } = exporter.generateCreateCommand('users', userSchema);

  // 创建带验证的集合
  await db.createCollection('users', options);

  console.log('集合创建成功，已启用文档验证');
}

类型映射

JSON Schema 类型	MongoDB BSON 类型
`string`	`string`
`number`	`double`
`integer`	`int`
`boolean`	`bool`
`object`	`object`
`array`	`array`
`null`	`null`

约束映射

JSON Schema 约束	MongoDB 约束
`minLength`	`minLength`
`maxLength`	`maxLength`
`minimum`	`minimum`
`maximum`	`maximum`
`pattern`	`pattern`
`enum`	`enum`
`minItems`	`minItems`
`maxItems`	`maxItems`

导出限制

⚠️ 重要提示: 并非所有 schema-dsl 特性都能导出到数据库 Schema。

不支持导出的特性:

❌ 条件验证逻辑（dsl.match(), dsl.if()）
❌ 自定义验证器（.custom()）
❌ 复杂 JSON Schema 关键字（allOf, anyOf, oneOf）
❌ 自定义错误消息（.messages()）

详细说明: 请阅读导出限制说明文档

对应示例文件

示例入口: mongodb-exporter.ts
说明: 覆盖 $jsonSchema 导出、generateCreateCommand() 和 generateCommand()，对应文档中的验证集合创建场景。

#MongoDB 导出器文档

#📑 目录

#概述

#核心功能

#快速开始

#API 参考

#构造函数

#方法

#export(jsonSchema)

#generateCreateCommand(collectionName, jsonSchema)

#generateCommand(collectionName, jsonSchema)

#MongoDBExporter.export(jsonSchema) (静态方法)

#配置选项

#验证模式

#完整示例

#用户集合验证

#在 MongoDB 中使用

#类型映射

#约束映射

#导出限制

#相关文档

#对应示例文件