文档首页

MongoDB Shell

代码片段

创建并分享代码片段

在此页面上

创建代码片段包
发布代码段
安装新的代码片段包
向 MongoDB Community 贡献代码段包

警告

实验功能

此功能是实验性的。MongoDB 不支持代码片段。此功能可随时更改或删除，恕不另行通知。

预计不会出现错误，但如果您遇到错误，请在 Github 存储库中提出问题对于此项目。

您可以编写脚本来操作数据，或在 mongosh 中执行管理任务。将脚本打包为代码片段提供了一种在组织内或跨 MongoDB 用户社区轻松共享脚本的方法。

本页讨论：

准备代码片段包。
将代码段包发布到注册表。

有关代码片段包中的脚本和元数据文件的示例，请参阅社区代码片段注册表中的代码片段在Github 上。

提示

如果您计划将代码片段提交到社区注册表，请务必查看向MongoDB Community 贡献代码片段包中的信息。

创建代码片段包

本节中的步骤重点介绍如何打包脚本。有关编写脚本的更多详细信息，请参阅编写脚本。

准备文件

为社区存储库创建分支。

如果您计划为社区存储库做出贡献，请派生代码片段项目存储库。

如果要创建私有存储库，则不必分叉社区存储库，但应在执行以下步骤时手动重新创建类似的目录结构。

创建包目录。

在分叉存储库的 snippets 目录下为代码段包创建一个目录。此目录将包含脚本代码和一些元数据文件。

此示例显示了两个代码段包 decrypt-cards 和 update-auth 的目录。社区片段的内容为清楚起见，省略了目录。

mongo-snippets
|
├── scripts
│   ├── make-index.js
│   └── show-index.js
└── snippets
    ├── analyze-schema
    ├── decrypt-cards
    │   ├── LICENSE-Community.txt
    │   ├── README.md
    │   ├── error-matchers.js
    │   ├── index.js
    │   └── package.json
    ├── mock-collection
    ├── mongocompat
    ├── resumetoken
    ├── spawn-mongod
    └── update-auth
        ├── LICENSE
        ├── README.md
        ├── index.js
        └── package.json

创建 `README.md` 。

创建 README.md 。 README.md 说明了如何使用您的代码。当用户为代码片段输入 snippet help 时，将显示此文件。

创建 `LICENSE` 。

创建 LICENSE 文件。稍后您需要输入许可证标识符字符串，因此请尝试从 SPDX 许可证列表中选择许可证。

创建 `index.js` 。

创建 index.js 文件。

该文件中的入口点指向 mongosh 控制台中公开的代码。
该脚本用 JavaScript 编写，用于定义新函数。
该脚本可以位于单个文件或多个文件中。
该脚本可以调用其他文件和本地或远程 npm 模块。要使用 require() 远程 npm 模块，请使用以下构造：
```
const localRequire = require('module').createRequire(__filename);)
```
有关示例请参阅 resumetoken 代码片段中的 index.js 。
index.js 在 package.json 中引用。
MongoDB 存储库提供了示例代码。

提示

如果您有现有脚本，请将其重命名为 index.js 或创建 index.js 文件来加载该脚本。 index.js 有关加载其他脚本的文件的示例，请参阅此文件在社区存储库中。

准备 `package.json` 文件

package.json 包含包注册表用于管理代码段的元数据。

最小的 package.json 文件如下所示：

{
    "name": "@mongosh/snippet-resumetoken",
    "snippetName": "resumetoken",
    "version": "1.0.2",
    "description": "Resume token decoder script",
    "main": "index.js",
    "license": "Apache-2.0",
    "publishConfig": {
       "access": "public"
    }
}

参数包括：

字段	说明
"name"	包含该代码片段的 npm 软件包。
"snippetName"	代码片段名称。这是与 `install` 等命令一起使用的名称。
"version"	软件包版本。更新代码片段时，此值应递增。
"description"	简要说明代码片段的用途。注意，如果描述的长度超过 50 或 60 个字符，则可能会导致某些代码片段命令出现显示问题。
"main"	这是代码的起点， `index.js` 。请注意，其他文件中的函数可以限定范围，以便它们也可以在 `mongosh` shell 中使用。
"license"	代码用户的许可证。如果您想为共享注册表做出贡献，则许可证应来自 SPDX 许可证列表。另请参阅 MongoDB 贡献者协议。
"publishConfig"	此值用于控制对代码片段包的访问。 `public` 是典型选项，但 npm 还提供其他选项以及。

使用此代码创建框架 package.json 文件。编辑该文件并替换每个 UPDATE ，以插入代码片段包的值。

{
    "name": "@UPDATE/UPDATE",
    "snippetName": "UPDATE",
    "version": "UPDATE",
    "description": "UPDATE",
    "main": "UPDATE",
    "license": "UPDATE",
    "publishConfig": {
       "access": "UPDATE"
    }
}

存储库中有多个 package.json MongoDBGithub 文件的示例。

提示

MongoDB 使用 npm 作为包注册表。

npm 依赖 package.json 文件来管理软件包。请参阅 npm 包文档以了解有关 package.json 的更多信息。

发布代码段

要分享您的代码片段，必须将代码片段包发布到注册表。该包将包含：

您的代码
README.md
LICENSE 文件
package.json

文件完成后，请按照以下步骤创建并发布代码片段包。

创建注册表索引文件。

注册表索引文件与包含代码段代码的 index.js 文件不同。注册表索引文件 index.bson.br 包含注册表中代码段包的元数据。

注册表索引文件在上传使用之前必须进行压缩。 make-index.js 实用程序会遍历代码片段源目录，收集创建注册表索引文件所需的信息。在创建注册表索引文件后， make-index.js 脚本还会对其进行压缩。

运行 make-index.js 从 mongo-snippets 目录创建索引。

node ./scripts/make-index.js

此脚本的输出是一个经过 Brotli 压缩的注册表索引文件 index.bson.br 。

您可以使用 show-index.js 查看压缩的注册表索引文件。

使用 make-index.js 是创建注册表索引的首选方法，但也可手动创建注册表索引。

提交代码片段

将代码片段和注册表索引文件提交到 GitHub 存储库。

发布更改

将您的更改发布到您的 npm 注册表。

npm publish --access public

安装新的代码片段包

请按照以下步骤安装新的代码段包：

刷新元数据。

刷新本地 mongosh 中的代码片段元数据。

snippet refresh

安装 Snippet。

安装代码片段。

snippet install YOUR_NEW_SNIPPET

向 MongoDB Community 贡献代码段包

如果您编写的代码片段可能对其他MongoDB 用户有用，我们邀请您将其贡献到社区存储库托管在Github 上。

要将代码片段提交到共享 MongoDB 存储库，请执行以下操作：

完成贡献者协议。

阅读并完成 MongoDB 贡献者协议。

克隆存储库。

分叉并克隆代码片段项目存储库来自Github 。

创建您的包目录。

在 snippets/ 下为代码添加一个新目录。为其指定一个描述性名称。

创建包。

创建代码段包。请确保它包含以下文件：

package.json
index.js
README.md
LICENSE

您不必创建注册表索引文件。如果您的代码片段包被接受，MongoDB 将更新注册表索引文件。

提交更改。

将更改提交到 GitHub 存储库。

提交代码段。

针对代码片段项目存储库打开拉取请求。

MongoDB 将审核您的拉取请求。如果被接受，我们将：

将您的代码合并到 GitHub 存储库中。
将其发布到 npm 注册表。
将其添加到代码段索引。

后退

在控制台中使用代码片段

来年

注册表和注册表配置