# @aws-blocks/bb-app-setting 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-app-setting/

版本：0\.4\.0
npm 元数据更新时间：2026-11-02T10:27:03.785Z
中文译文更新时间：2026-11-07T12:55:59.881Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-app-setting
原文对照：https://npmcn.com/package/%40aws-blocks/bb-app-setting/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-app-setting#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

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

- 包体积（解压后）：219 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：constructs ^10\.6\.0，aws-cdk-lib ^2\.257\.0
- 首次发布：2026-06-15T23:39:23.543Z
- 最新版本发布：2026-11-02T10:27:03.423Z
- 近 30 天下载量：67149（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

由SSM参数存储器支持的单一应用程序配置值.

## 安装

```sh
npm install @aws-blocks/bb-app-setting
```

也可以使用：`pnpm add @aws-blocks/bb-app-setting`、`yarn add @aws-blocks/bb-app-setting`、`bun add @aws-blocks/bb-app-setting`

## README

# 部署

由SSM参数存储器支持的单一应用程序配置值.

**何时使用 :** 您需要一个不敏感的配置值( 地标, API URL, 阈值) 作为单个 SSM 参数存储 。 每个 `AppSetting` 实例映射到一个参数.

**不使用时 :** 对于生产密钥( API 密钥、 OAuth 客户端密钥、 数据库连接字符串、 令牌) , 使用 [`Secret`](https://npmcn.com/package/%40aws-blocks/bb-secret/README.md) 是推荐的家 证书保护生产应用, [符合AWS指南的](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。 。 。 . `AppSetting` 与 `secret: true` 在休息时加密该值, 并且是免费的, 所以它是一个精细的倒置 _低值_ 在一个原型中的秘密——但这不是生产秘密的推荐地点. 如果您需要结构化的密钥值数据并附带条件的写和查询,请使用 `KVStore` 或者说 `DistributedTable`。 。 。 .

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-app-setting/DESIGN.md)

## API 密码

```typescript
const setting = new AppSetting(scope, id, options)
```

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `get()` | `Promise<T>` | 读取当前值 . |
| `put(value)` | `Promise<void>` | 运行时更新值 . |

### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 没有 | SSM 参数路径. 省去时,取自瞄准树 `/${fullId}`,保证堆内的独特性. |
| `value` | `T` | 没有 | 初标相. 非秘密参数需要。 不得在 `secret` 已经设定. |
| `schema` | `StandardSchemaV1<T>` | 没有 | 运行时验证计划 (Zod, Valibot, ArkType). 推断 `T` 从计划。 无法使用 `secret`。 。 。 . |
| `secret` | `boolean` | 没有 | 何时 `true`,以默认设置创建 SSM 安全串 `aws/ssm` KMS 密钥( 或 `kmsKeyArn` (设定时). 无法使用 `schema` 或者说 `value`对于生产秘密,更喜欢 [`Secret`](https://npmcn.com/package/%40aws-blocks/bb-secret/README.md) (AWS 秘密管理器)——参见 **不使用时** 见上文. |
| `kmsKeyArn` | `string` | 没有 | 客户管理的 KMS 密钥的 ARN 加密安全链, 而不是默认 `aws/ssm` 键。 仅有效 `secret: true`. 见下文注释. |
| `logger` | `ChildLogger` | 没有 | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |

> **客户管理的 KMS 密钥`kmsKeyArn`:** 提供一个CMK ARN来控制 秘密的解密/授予范围(例如交叉账户访问或专用密钥) (政策)。 构造允许共享处理器 `kms:Decrypt` (单位:千美元) `kms:Encrypt` 关键是ARN 因为AWS Blocks没有你的钥匙, **关键的关键政策也必须 允许应用程序的 Lambda 执行角色** (或通过 账户根报表 CDK 添加到同账户密钥中。 添加或更改 `kmsKeyArn` 在已部署的秘密中重新加密当前值 下一次部署时的新密钥, 所以解密继续工作.

> **名称 :** 省略时 `name`,这个框架从 构造范围树( e)`/${fullId}`) (中文(简体) ). 这是建议的办法——它 自动防止相撞堆栈。 如果你提供明确 `name`, (中文(简体) ), **你们** 负责确保它在所有堆栈中独一无二 部署在同一AWS账户和区域.

### 处理错误

```typescript
import { isBlocksError } from '@aws-blocks/core';
import { AppSettingErrors } from '@aws-blocks/bb-app-setting';

try {
  await setting.put(value);
} catch (e: unknown) {
  if (isBlocksError(e, AppSettingErrors.ValidationFailed)) {
    // schema validation failed or value exceeds 4 KB
  }
  throw e;
}

try {
  const value = await setting.get();
} catch (e: unknown) {
  if (isBlocksError(e, AppSettingErrors.ParameterNotFound)) {
    // the parameter is missing (e.g., deleted out-of-band) or a secret has an empty value
  }
  throw e;
}
```

`get()` 可以抛出 `AppSettingErrors.ParameterNotFound` 当参数不存在或者一个秘密参数有空值时(在AWS和模拟运行时).

## 实例

### 普通字符串设置

```typescript
// Recommended: let the framework manage the SSM name (unique by default)
const apiUrl = new AppSetting(scope, 'apiUrl', {
  value: 'https://api.example.com',
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getApiUrl() {
    return { url: await apiUrl.get() };
  },
  async setApiUrl(url: string) {
    await apiUrl.put(url);
  },
}));
```

### 用 Schema 键入对象

```typescript
import { z } from 'zod';

const config = new AppSetting(scope, 'config', {
  value: { maxRetries: 3, timeout: 5000 },
  schema: z.object({ maxRetries: z.number(), timeout: z.number() }),
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getConfig() {
    return await config.get(); // { maxRetries: number; timeout: number }
  },
  async updateConfig(cfg: { maxRetries: number; timeout: number }) {
    await config.put(cfg); // validated against schema
  },
}));
```

### 秘诀

```typescript
const stripeKey = new AppSetting(scope, 'stripeKey', {
  secret: true,
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async charge(amount: number) {
    const key = await stripeKey.get(); // decrypted from SSM SecureString
    // use key...
  },
}));
```

### 明确名称( 交叉服务读取)

使用明确的 `name` 当SSM参数必须被其他服务所读取或遵循出名的路径公约时.

> 您必须保证这个名字在部署到 相同的AWS账户和区域以避免相撞.

```typescript
const apiUrl = new AppSetting(scope, 'apiUrl', {
  name: '/my-app/production/api-url',
  value: 'https://api.example.com',
});
```

## 审定规则

它们是在CDK合成时间和本地开发中执行的(模拟在建筑中拒绝相同的组合):

-   `secret` + 键 `schema` ~ 错误( 机密为平线)
-   `schema` 无 `value` − 出错(参数需要一个有效的初始值)
-   `secret` 与 `value` - 错误(不要在源代码中隐藏秘密)
-   无机密 `value` 出错(设置需要初始值)

## 缩放成本( AWS)

-   **字符串参数 :** 标准等级,免费,4 KB限额,每个账户/区域10,000
-   **安全结构参数 :** 标准等级, 免费, 加密 `aws/ssm` KMS 密钥
-   **通过量 :** GetParemeter 的40 TPS 默认值( 可增加)
-   **延迟 :** 读取和写出数位数

## 地方发展

模拟数据持续到磁盘 `.bb-data/settings/{fullId}/value.json` 跨 Dev 服务器重启 。 擦拭为 `rm -rf .bb-data`. 机密在当地生成随机值(没有模拟模式的 KMS 加密).

## 常见问题

### @aws-blocks/bb-app-setting 是什么？

由SSM参数存储器支持的单一应用程序配置值\.

### 如何安装 @aws-blocks/bb-app-setting？

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

### @aws-blocks/bb-app-setting 支持 TypeScript 吗？

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

### @aws-blocks/bb-app-setting 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aws-blocks/bb-app-setting 可以商用吗？

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

### @aws-blocks/bb-app-setting 的下载量有多少？

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

### @aws-blocks/bb-app-setting 还在维护吗？

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