# @aws-mdaa/naming 中文文档

规范地址：https://npmcn.com/package/%40aws-mdaa/naming/

版本：1\.10\.0
npm 元数据更新时间：2026-11-07T13:48:41.099Z
中文译文更新时间：2026-11-07T14:45:28.702Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-mdaa/naming
原文对照：https://npmcn.com/package/%40aws-mdaa/naming/?lang=original
项目主页：https://github.com/aws/modern-data-architecture-accelerator#readme
源码仓库：https://github.com/aws/modern-data-architecture-accelerator

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：398 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：constructs 10\.6\.0
- 首次发布：2025-05-14T09:51:29.691Z
- 最新版本发布：2026-11-07T13:48:40.927Z
- 近 30 天下载量：15670（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 9 个）

## 中文简介

MDAA 命名

## 安装

```sh
npm install @aws-mdaa/naming
```

也可以使用：`pnpm add @aws-mdaa/naming`、`yarn add @aws-mdaa/naming`、`bun add @aws-mdaa/naming`

## README

# MDAA 命名

此软件包定义了MDA兼容的命名执行的接口,以及默认执行. 命名执行将被通过 MDAA CDK App Context ,以便根据 MDAA 执行环境中指定的任何上下文初始化自己.

## 资源类型支持

这个 `MdaaResourceType` 页:1 `withResourceType()` 方法允许自定义命名执行生成资源型识别名称. 默认执行是无操作的——它忽略了资源类型,返回名称不变,保留了后向相容性.

以下示例产出只能通过自定义执行实现,该执行将超过 `withResourceType()` (见 [计算机化.md](https://npmcn.com/CUSTOMIZATION.md)) (中文(简体) ). 框外,默认执行将生成同名名称,无论哪个 `MdaaResourceType` 提供了数值.

```typescript
// With a custom impl that overrides withResourceType (see CUSTOMIZATION.md):
const naming = customNaming.withResourceType(MdaaResourceType.S3_BUCKET);
const bucketName = naming.resourceName('my-data');
// → "aw-dev-s3-dpl-retail-datalake-my-data"
```

见 [计算机化.md](https://npmcn.com/CUSTOMIZATION.md) 仅供参考.

## 包括 `env` 在 SSM 路径和导出名称中

默认情况下, 默认命名执行生成的 SSM 参数路径和 CloudFormation 导出名称 **没有** 包括环境`env`:

| 方法 | 默认格式 |
| --- | --- |
| `ssmPath()` | `/<org>/<domain>/<module_name>/<path>` |
| `exportName()` | `<org>:<domain>:<module_name>:<path>` |

这导致碰撞,当 **同单元** 用于多种环境(例如:. `dev` 财务报告和审定财务报表 `prod`(a) 内 **单一 AWS 账户**:两种部署都产生相同的SSM参数名称(沉默覆盖/跨环境泄漏)和相同的CloudFormation导出名称(第二次部署彻底失败,因为每个账户/区域的出口名称必须独一无二).

### 启用嵌入意识路径

设定 `@mdaaIncludeEnvInSsmPath` CDK 上下文旗为 `true` (通过a) `context` 块在您的 MDAA 配置中,或 `additional_context` 在模块中)。 值必须准确 `true` 或者说 `false` ——其他任何值都会被错误地拒绝来防止打字(例如. `yes`, (中文(简体) ), `1`)从被无声地曲解. 当启用时, `env` 紧接 `domain`数字 :

| 方法 | 格式为 `@mdaaIncludeEnvInSsmPath: true` |
| --- | --- |
| `ssmPath()` | `/<org>/<domain>/<env>/<module_name>/<path>` |
| `exportName()` | `<org>:<domain>:<env>:<module_name>:<path>` |

旗帜默认为 `false`因此,除非明确选择,否则现有部署不会受到影响。 启用时, 发布 SSM 参数和导出的所有内部代码路径( 通过 `naming.ssmPath(...)` 编号 : `naming.exportName(...)`)自动采用新格式——不需要每个单元的代码修改.

### 引用嵌入意识参数

国旗只影响 **发布** 边 当在配置中引用另一个模块的 env-aware 参数时, 框架不能推断您指的是哪个环境, 所以您必须提供 `env` 明确 — 正如您已经提供了模块名称:

```yaml
# Preferred for same-domain references — ssm-env: already prepends /<org>/<domain>/<env>/,
# so no manual env segment is needed:
someKmsKeyArn: ssm-env:/my-kms-module/cmk/arn

# With ssm-domain: (prepends only /<org>/<domain>/), include the env segment yourself:
someKmsKeyArn: ssm-domain:/dev/my-kms-module/cmk/arn

# With ssm-org: or a literal resolve:ssm: reference, write the full env-aware path:
someKmsKeyArn: ssm-org:/my-domain/dev/my-kms-module/cmk/arn
```

### 调动现有部署

启用此旗会更改 SSM 参数名称和 CloudFormation 导出名称, 所以对于任何用户参考了旧路径的部署来说, 这是一种突破性更改 。 因为参数/导出 **名称** 更改时, 而基本的 CloudFormation 逻辑ID 不 :

-   每个 SSM 参数是 **已替换** 已就位 —— Cloud Formation 创建了新的env-aware参数并删除同一部署中的旧参数. 没有遗留的旧参数需要清理,也没有旧名和新名都解决的重叠窗口.
-   当另一个堆栈仍然导入时, 导出名称不能被更改( E)`Fn::ImportValue`) (中文(简体) ). 您必须阻止消费者在重新部署生产者之前(或者在与重新部署生产者相同的协调变化中)进口旧出口,否则生产者部署将失败.

安全迁移:

1.  更新所有关于受影响参数的配置引用/导出到内存意识路径(见上文) **在此之前** 重新部署生产商,所以没有堆栈导入旧的导出名.
2.  启用 `@mdaaIncludeEnvInSsmPath: true` 并重新部署。 制作者在env-aware路径上发布(旧参数被替换,而不是被孤),消费者解决了新路径.

## 常见问题

### @aws-mdaa/naming 是什么？

MDAA 命名

### 如何安装 @aws-mdaa/naming？

在项目目录运行 npm install @aws-mdaa/naming，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（10\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-mdaa/naming 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-mdaa/naming 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-mdaa/naming 可以商用吗？

@aws-mdaa/naming 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-mdaa/naming 的下载量有多少？

根据 npm 官方下载统计，@aws-mdaa/naming 在 2026/10/08 – 2026/11/06 这 30 天内被下载 15,670 次，日均约 522 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-mdaa/naming 还在维护吗？

最新版本 1\.10\.0 发布于 2026/11/07（今天）；至今共发布 12 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/05/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。