工作区和 Monorepos

Deno 支持工作区，也称为“Monorepos”，它允许您同时管理多个相关和相互依赖的包。

“工作区”是包含 deno.json 或 package.json 配置文件的一系列文件夹。根 deno.json 文件定义了工作区

{
  "workspace": ["./add", "./subtract"]
}

此配置使用 add 和 subtract 成员配置工作区，这些成员是预期包含 deno.json(c) 和/或 package.json 文件的目录。

示例 跳转到标题#

让我们扩展 deno.json 工作区示例，看看它的功能。文件层次结构如下所示

/
├── deno.json
├── main.ts
├── add/
│     ├── deno.json
│     └── mod.ts
└── subtract/
      ├── deno.json
      └── mod.ts

有两个工作区成员（add 和 subtract），每个成员都有 mod.ts 文件。还有一个根 deno.json 和一个 main.ts。

顶层 deno.json 配置文件定义了工作区和一个应用于所有成员的顶层导入映射

{
  "workspace": ["./add", "./subtract"],
  "imports": {
    "chalk": "npm:chalk@5"
  }
}

根 main.ts 文件使用导入映射中的 chalk 裸标识符，并从工作区成员导入 add 和 subtract 函数。请注意，它使用 @scope/add 和 @scope/subtract 导入它们，即使这些不是正确的 URL 并且不在导入映射中。它们是如何解析的？

import chalk from "chalk";
import { add } from "@scope/add";
import { subtract } from "@scope/subtract";

console.log("1 + 2 =", chalk.green(add(1, 2)));
console.log("2 - 4 =", chalk.red(subtract(2, 4)));

在 add/ 子目录中，我们定义了一个带有 "name" 字段的 deno.json，这对于引用工作区成员非常重要。deno.json 文件还包含示例配置，例如在使用 deno fmt 时关闭分号。

{
  "name": "@scope/add",
  "version": "0.1.0",
  "exports": "./mod.ts",
  "fmt": {
    "semiColons": false
  }
}

export function add(a: number, b: number): number {
  return a + b;
}

subtract/ 子目录类似，但没有相同的 deno fmt 配置。

{
  "name": "@scope/subtract",
  "version": "0.3.0",
  "exports": "./mod.ts"
}

import { add } from "@scope/add";

export function subtract(a: number, b: number): number {
  return add(a, b * -1);
}

让我们运行它

> deno run main.ts
1 + 2 = 3
2 - 4 = -2

这里有很多内容需要解释，展示了一些 Deno 工作区功能

1. 这个 monorepo 由两个包组成，分别放置在 ./add 和 ./subtract 目录中。

2. 通过在成员的 deno.json 文件中使用 name 和 version 选项，可以在整个工作区中使用“裸标识符”来引用它们。在本例中，这些包被命名为 @scope/add 和 @scope/subtract，其中 scope 是您可以选择的“作用域”名称。有了这两个选项，就不需要在 import 语句中使用长而相对的文件路径。

3. npm:chalk@5 包是整个工作区中的共享依赖项。工作区成员“继承”工作区根目录的 imports，从而可以轻松管理整个代码库中依赖项的单个版本。

4. add 子目录在其 deno.json 中指定 deno fmt 在格式化代码时不应应用分号。这使得现有项目的迁移更加顺畅，而无需一次性更改数十或数百个文件。

Deno 工作区非常灵活，可以与 Node 包一起使用。为了简化现有 Node.js 项目的迁移，您可以在单个工作区中同时拥有 Deno-first 和 Node-first 包。

Deno 如何解析工作区依赖项 跳转到标题#

当在工作区中运行从另一个工作区成员导入的项目时，Deno 按照以下步骤解析依赖项

1. Deno 从正在执行的项目目录（例如，项目 A）开始
2. 它在父目录中查找根 deno.json 文件
3. 如果找到，它会检查该文件中的 workspace 属性
4. 对于项目 A 中的每个 import 语句，Deno 检查导入是否与任何工作区成员的 deno.json 中定义的包名称匹配
5. 如果找到匹配的包名称，Deno 会验证包含目录是否列在根工作区配置中
6. 然后，使用工作区成员的 deno.json 中的 exports 字段将导入解析为正确的文件

例如，给定以下结构

/
├── deno.json         # workspace: ["./project-a", "./project-b"]
├── project-a/
│   ├── deno.json     # name: "@scope/project-a"
│   └── mod.ts        # imports from "@scope/project-b"
└── project-b/
    ├── deno.json     # name: "@scope/project-b"
    └── mod.ts

当 project-a/mod.ts 从 "@scope/project-b" 导入时，Deno

1. 看到 import 语句
2. 检查父目录的 deno.json
3. 在工作区数组中找到 project-b
4. 验证 project-b/deno.json 存在并且具有匹配的包名称
5. 使用 project-b 的 exports 解析导入

容器化的重要提示 跳转到标题#

当容器化依赖于其他工作区成员的工作区成员时，您必须包含

1. 根 deno.json 文件
2. 所有依赖的工作区包
3. 与您的开发环境相同的目录结构

例如，如果 docker 化上面的 project-a，您的 Dockerfile 应该

COPY deno.json /app/deno.json
COPY project-a/ /app/project-a/
COPY project-b/ /app/project-b/

这保留了 Deno 用于查找和导入工作区依赖项的工作区解析机制。

多个包入口 跳转到标题#

到目前为止，我们的包只有一个入口。对于简单的包来说，这很好，但通常您会希望有多个入口来对包的相关方面进行分组。这可以通过将 object 而不是 string 传递给 exports 来完成

{
  "name": "@scope/my-package",
  "version": "0.3.0",
  "exports": {
    ".": "./mod.ts",
    "./foo": "./foo.ts",
    "./other": "./dir/other.ts"
  }
}

"." 条目是导入 @scope/my-package 时选择的默认条目。因此，上面的 deno.json 示例提供了以下条目

• @scope/my-package
• @scope/my-package/foo
• @scope/my-package/other

从 npm 工作区迁移 跳转到标题#

Deno 工作区支持从现有的 npm 包中使用 Deno-first 包。在此示例中，我们将 Deno 库 @deno/hi 与我们几年前开发的 Node.js 库 @deno/log 混合搭配使用。

我们需要在根目录中包含一个 deno.json 配置文件

{
  "workspace": {
    "members": ["hi"]
  }
}

以及我们现有的 package.json 工作区

{
  "workspaces": ["log"]
}

该工作区当前有一个 log npm 包

{
  "name": "@deno/log",
  "version": "0.5.0",
  "type": "module",
  "main": "index.js"
}

export function log(output) {
  console.log(output);
}

让我们创建一个导入 @deno/log 的 @deno/hi Deno-first 包

{
  "name": "@deno/hi",
  "version": "0.2.0",
  "exports": "./mod.ts",
  "imports": {
    "log": "npm:@deno/log@^0.5"
  }
}

import { log } from "log";

export function sayHiTo(name: string) {
  log(`Hi, ${name}!`);
}

现在，我们可以编写一个导入并调用 hi 的 main.ts 文件

import { sayHiTo } from "@deno/hi";

sayHiTo("friend");

$ deno run main.ts
Hi, friend!

您甚至可以在现有的 Node.js 包中同时拥有 deno.json 和 package.json。此外，您可以删除根目录中的 package.json，并在 deno.json 工作区成员中指定 npm 包。这允许您逐步迁移到 Deno，而无需进行大量前期工作。

例如，您可以添加类似 log/deno.json 的内容来配置 Deno 的代码检查器和格式化程序

{
  "fmt": {
    "semiColons": false
  },
  "lint": {
    "rules": {
      "exclude": ["no-unused-vars"]
    }
  }
}

在工作区中运行 deno fmt 将格式化 log 包，使其不包含任何分号，如果您在其中一个源文件中留下未使用的变量，deno lint 也不会报错。

配置内置 Deno 工具 跳转到标题#

某些配置选项仅在工作区根目录中才有意义，例如。在一个成员中指定 nodeModulesDir 选项不可用，如果某个选项需要在工作区根目录中应用，Deno 会发出警告。

以下是工作区根目录及其成员中可用的各种 deno.json 选项的完整矩阵