# @cdk\_utils/iam 中文文档

规范地址：https://npmcn.com/package/%40cdk_utils/iam/

版本：1\.56\.0
npm 元数据更新时间：2026-10-30T12:50:42.655Z
中文译文更新时间：2026-11-09T15:42:10.299Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cdk_utils/iam
原文对照：https://npmcn.com/package/%40cdk_utils/iam/?lang=original
项目主页：https://github.com/cdk-utils/iam#readme
源码仓库：https://github.com/cdk-utils/iam

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

- 包体积（解压后）：101 MB，929 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：projen \>=0\.99\.0，constructs ^10\.0\.5，aws-cdk-lib ^2\.150\.0
- 首次发布：2026-08-12T10:34:42.105Z
- 最新版本发布：2026-10-30T12:50:42.263Z
- 近 30 天下载量：2340（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

CDK 构建和帮助功能,以简化IAM资源的创建

## 安装

```sh
npm install @cdk_utils/iam
```

也可以使用：`pnpm add @cdk_utils/iam`、`yarn add @cdk_utils/iam`、`bun add @cdk_utils/iam`

## README

# @cdk utils/ iam

CDK 构建和帮助功能,以简化IAM资源的创建.

本套件提供:

-   **类型安全 AWS 服务常数** ——自动生成自官方 AWS 服务授权引用,给您编译时间检查的行动名称,资源 ARN 模式,以及每455+的条件密钥 AWS服务.
-   **ARN 构建器、验证器和解析器** – 类型安全功能,用于构建,验证,并分解每种资源类型的ARN.
-   **业务-IAM行动绘图** ——准确了解每个API呼叫需要哪个IAM行动(包括跨服务依赖).
-   **条件密钥构建器** ——与正确的运算符一起键入帮助生成IAM条件块.

> **马上就来了:** IAM 辅助器功能和即用CDK构造.

## 文档

API的完整参考文件载于 [`docs/`](https://npmcn.com/package/%40cdk_utils/iam/docs/) 目录,每个 AWS 服务有一个文件 。 开始于 **[`docs/API.md`](https://npmcn.com/package/%40cdk_utils/iam/docs/API.md)** 用于完整目录.

## 安装

```bash
npm install @cdk_utils/iam
```

## 使用量

```typescript
import { dynamodb, s3 } from "@cdk_utils/iam";

// Action constants (type-safe, no typos)
const action = dynamodb.DynamoDBActions.CreateTable; // "dynamodb:CreateTable"
const getAction = dynamodb.DynamoDBActions.actionGetItem; // "dynamodb:GetItem"

// Access-level groupings
const readActions = dynamodb.DynamoDBActions.AllReadActions; // string[]
const writeActions = dynamodb.DynamoDBActions.AllWriteActions; // string[]

// ARN builders (with defaults: partition="aws", region="*", account="*")
const tableArn = dynamodb.DynamoDBResources.table({ tableName: "Orders" });
// → "arn:aws:dynamodb:*:*:table/Orders"

const indexArn = dynamodb.DynamoDBResources.index({
  tableName: "Orders",
  indexName: "GSI1",
  region: "us-east-1",
  account: "123456789012",
});
// → "arn:aws:dynamodb:us-east-1:123456789012:table/Orders/index/GSI1"

// ARN validation
dynamodb.DynamoDBResources.isValidTableArn("arn:aws:dynamodb:us-east-1:123:table/T"); // true

// ARN parsing (throws on invalid)
const parts = dynamodb.DynamoDBResources.parseTableArn(
  "arn:aws:dynamodb:us-east-1:123:table/Orders"
);
// → { partition: "aws", region: "us-east-1", account: "123", tableName: "Orders" }

// Operation → required IAM actions (what you actually need to call CreateTable)
const required = dynamodb.DynamoDBOperations.CreateTable;
// → ["dynamodb:AssociateTableReplica", "dynamodb:BatchWriteItem", "dynamodb:CreateTable", ...]

// Condition key builders (type-safe operators)
const condition = dynamodb.DynamoDBConditions.attributes(["col1", "col2"]);
// → { "ForAllValues:StringEquals": { "dynamodb:Attributes": ["col1", "col2"] } }

// S3 example
const bucketArn = s3.S3Resources.bucket({ bucketName: "my-bucket" });
// → "arn:aws:s3:::my-bucket"
```

## 每个服务生成的类数

每个 AWS 服务导出为 **jsii 子模块** (名称空间). 从软件包根导入服务命名空间 :

```typescript
import { s3, lambda, ec2 } from "@cdk_utils/iam";
```

每个分单元最多包含4个班级:

| 类 | 目的 | 示例 |
| --- | --- | --- |
| `{Service}Actions` | 动作字符串常数+访问级别分组 | `s3.S3Actions.PutObject` |
| `{Service}Resources` | ARN 构建者、验证者(`isValid*Arn`),解析器(`parse*Arn`(中文(简体) ) | `s3.S3Resources.bucket(...)` |
| `{Service}Operations` | API 操作 ~ 需要 IAM 动作阵列 | `s3.S3Operations.PutObject` |
| `{Service}Conditions` | 条件键常数+打入的构建器方法 | `s3.S3Conditions.prefix("docs/")` |

没有资源/操作/条件的服务跳过相应的类别.

> **说明:** 子模块名称对连字符服务使用下划线(例如:, `access_analyzer`, (中文(简体) ), `route53_recovery_cluster`) (中文(简体) ).

## 项目结构

```
iam/
├── src/
│   ├── index.ts                      # Re-exports submodules from generated/
│   ├── generated/                    # Auto-generated (DO NOT EDIT)
│   │   ├── index.ts                  # jsii submodule declarations (export * as ...)
│   │   └── services/                 # One file per AWS service (455+)
│   │       ├── dynamodb.ts
│   │       ├── s3.ts
│   │       ├── lambda.ts
│   │       └── ...
│   ├── helpers/                      # (Planned) IAM helper functions
│   └── constructs/                   # (Planned) CDK constructs
│
├── docs/                             # API documentation (NOT published to npm)
│   ├── API.md                        # Table of contents (links to all services)
│   ├── s3.md                         # Per-service documentation
│   ├── dynamodb.md
│   └── ...                           # 456 files total
│
├── scripts/                          # Tooling (NOT published to npm)
│   ├── types.ts                      # TypeScript types for the AWS API
│   ├── fetch-service-reference.ts    # Fetch + validate API responses
│   ├── sync-service-reference.ts     # Timestamp-based incremental sync
│   ├── generate-service.ts           # Generate TS for a single service
│   ├── generate-index.ts             # Regenerate barrel exports
│   ├── generate-all.ts              # Generate all services
│   ├── run-update.ts                 # Unified: sync + generate + index
│   ├── run-sync.ts                   # CLI for sync-only
│   ├── naming.ts                     # PascalCase/camelCase/UPPER_SNAKE utilities
│   ├── arn-codegen.ts                # ARN template → code generation
│   └── condition-codegen.ts          # Condition type → operator mapping
│
├── data/                             # Raw data (NOT published to npm)
│   └── service-reference/            # 455+ AWS service JSON files
│       ├── .last-sync-timestamp
│       ├── dynamodb.json
│       └── ...
│
├── test/scripts/                     # Unit tests (154 tests)
│
├── .github/workflows/
│   ├── build.yml                     # CI (projen-managed)
│   ├── release.yml                   # Release to npm (projen-managed)
│   ├── upgrade-main.yml              # Dependency upgrades (projen-managed)
│   └── update-service-reference.yml  # Cron: sync → generate → PR
│
├── .projenrc.ts                      # Project configuration
└── package.json
```

## 自动更新

一个 GitHub 动作`update-service-reference.yml`)使生成的代码与AWS同步:

-   **时间表 :** 协调世界时6:00工作日
-   **手动触发 :** `gh workflow run update-service-reference`
-   **流量 :** 获取更新的服务数据 – 仅重生已更改的服务 – 运行全构件 – 如果有任何变化打开 PR

更新是 **递增** ——只提供 `modified` 时间戳超过存储 `.last-sync-timestamp` 重排和重生成.

## 发展

### 先决条件

-   节点.js 24.x
-   无

### Projen 任务

```bash
npx projen build                    # Full build (jsii + tests + packaging)
npx projen test                     # Run unit tests
npx projen update-service-reference # Sync data + regenerate constants
npx projen sync-service-reference   # Fetch data only (no code generation)
npx projen generate-constants       # Regenerate all 455+ service files
npx projen generate-service         # Generate for a single service JSON
npx projen generate-index           # Regenerate the barrel index
```

### 代码生成如何工作

1.  **数据来源:** [AWS 服务授权 API](https://servicereference.us-east-1.amazonaws.com/)
2.  **同步 :** `fetch-service-reference.ts` 基于时间戳的下载服务 JSONs
3.  **生成 :** `generate-service.ts` 转换一个 JSON – 一个 TypeScript 文件, 并带有命名的接口和静态类
4.  **命名公约:**
    -   行动:PascalCase作为`CreateTable`, (中文(简体) ), `PutItem`(三); `Get*`编号 :`Set*` 前缀为 `action`编号 :`op` 用于 jsii 兼容性
    -   资源:骆驼案例方法(`table(...)`, (中文(简体) ), `index(...)`(中文(简体) )
    -   接口 : `{ServicePrefix}{Resource}ArnProps` 编号 : `{ServicePrefix}{Resource}ArnComponents`
5.  **格式化 :** 所有生成的文件都与 Biome 自动格式化

## 普罗让

这个项目由 [projen 语录](https://github.com/projen/projen) 通过 `@cdk_utils/projen_template` 模板。 执行 **没有** 手动编辑生成的文件——修改 `.projenrc.ts` 运行 `npx projen` 换句话说.

从 npm 包中排除的文件( 但承诺 git ) :

-   `scripts/` ——构建/同步工具
-   `data/` ——原始AWS服务参考JSONs
-   `docs/` ——人均服务API文档(由jsii-docgen生成)
-   `test/` 单位测试

## 许可证

阿帕奇 - 2.0

## 常见问题

### @cdk\_utils/iam 是什么？

CDK 构建和帮助功能,以简化IAM资源的创建

### 如何安装 @cdk\_utils/iam？

在项目目录运行 npm install @cdk\_utils/iam，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：projen（\>=0\.99\.0）、constructs（^10\.0\.5）、aws-cdk-lib（^2\.150\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdk\_utils/iam 支持 TypeScript 吗？

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

### @cdk\_utils/iam 支持 ESM 还是 CommonJS？

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

### @cdk\_utils/iam 可以商用吗？

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

### @cdk\_utils/iam 的下载量有多少？

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

### @cdk\_utils/iam 还在维护吗？

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