创建和共享片段

警告:

实验特征

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

预计不会出现错误，但是如果您遇到错误，请在 GitHub 仓库 对于这个项目。

您可以编写脚本来操作数据或在mongosh. 将脚本打包为片段提供了一种在组织内或跨 MongoDB 用户社区轻松共享脚本的方法。

本页讨论：

• 准备中一个片段包。
• 出版片段包到注册表。

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

提示:

如果您打算将您的代码片段提交给社区登记处, 请务必查看中的信息向 MongoDB 社区贡献一个片段包。

创建代码段包

本节中的步骤侧重于打包脚本。有关编写脚本的更多详细信息，请参阅编写脚本。

准备文件

1. 分叉社区存储库

   如果您打算为社区存储库做出贡献，请分叉代码片段项目库。

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

2. 创建包目录

   在分叉存储库的目录下为您的代码段包创建一个目录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
   

3. 创建README.md

   创建一个README.md. 描述README.md了如何使用您的代码。当用户输入snippet help您的代码段时会显示此文件。

4. 创建LICENSE

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

5. 创建index.js。

   创建一个index.js文件。

   • 此文件包含在控制台中公开的代码的入口点mongosh。

   • 该脚本是用 JavaScript 编写的，用于定义您的新功能。

   • 脚本可以在单个文件或多个文件中。

   • 该脚本可以调用其他文件和本地或远程 npm 模块。对于require()远程 npm 模块，请使用以下结构：

     const localRequire = require('module').createRequire(__filename);)
     

     有关示例，请参见 索引.js 在片段中resumetoken。

   • index.js被引用在包.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"
    }
}

参数是:

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

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

package.jsonMongoDB GitHub 中有几个文件示例存储库。

提示:

MongoDB 使用 npm 作为包注册表。

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

发布片段

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

• 你的代码
• README.md
• LICENSE文件
• 包.json

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

1. 创建注册表索引文件.

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

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

   跑步制作索引.js 从mongo-snippets目录创建索引。

   node ./scripts/make-index.js
   

   该脚本的输出是 brotli 压缩注册表索引文件，index.bson.br.

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

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

2. 提交你的代码片段

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

3. 发布更改

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

   npm publish --access public
   

安装新的片段包

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

1. 刷新元数据

   刷新本地mongosh.

   snippet refresh
   

2. 安装代码段

   安装片段.

   snippet install YOUR_NEW_SNIPPET
   

向 MongoDB 社区贡献一个代码片段包

如果您编写了可能对其他 MongoDB 用户有用的 代码片段，我们邀请您将其贡献给社区资料库托管在 GitHub 上。

要将片段提交到共享的 MongoDB 存储库：

1. 完成贡献者协议

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

2. 克隆存储库

   分叉并克隆 片段项目存储库 来自 GitHub。

3. 创建您的包目录

   在下面为您的代码添加一个新目录 片段/. 给它一个描述性的名字。

4. 创建您的包裹

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

   • package.json
   • index.js
   • README.md
   • LICENSE

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

5. 提交您的更改.

   将更改提交到 GitHub 存储库。

6. 提交您的代码片段。

   针对片段项目存储库。

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

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

翻译：韩鹏帅

原文：Create and Share Snippets