创建并分享代码片段

在此页面上

创建代码片段包

发布代码段
安装新的代码片段包
向 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文件。稍后您需要输入许可证标识符string ，因此请尝试从 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 注册表。
将其添加到代码段索引。

后退

在控制台中使用

来年

注册表

警告