# @astram/engine 中文文档

规范地址：https://npmcn.com/package/%40astram/engine/

版本：0\.20\.0
npm 元数据更新时间：2026-11-06T15:41:52.115Z
中文译文更新时间：2026-11-07T00:59:42.789Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40astram/engine
原文对照：https://npmcn.com/package/%40astram/engine/?lang=original
项目主页：https://github.com/ASTRAM-2-0/astram-framework#readme
源码仓库：https://github.com/ASTRAM-2-0/astram-framework

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

- 包体积（解压后）：428 kB，87 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：rxjs ^7，@nestjs/core ^11，@nestjs/common ^11，reflect-metadata ^0\.2
- 首次发布：2026-07-17T18:32:51.657Z
- 最新版本发布：2026-11-06T15:41:51.818Z
- 近 30 天下载量：5017（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

Astram框架——铺平了的道路。 一个不可通通的写字管(resolve-schema → perference gate → exterm-write-context → 校验 → 校验 → 交叉-同步 – 审计 → 发售 – 事件),每个功能的 CRUD 流经真实的物理表.

## 安装

```sh
npm install @astram/engine
```

也可以使用：`pnpm add @astram/engine`、`yarn add @astram/engine`、`bun add @astram/engine`

## README

# @ astram/ 引擎

Astram铺面道路:一个固定的、交易式的写字管(型号为前门-取回-记录-) 校正 校正 校正 校正 校正 校正 校正 校正 特性 代码只接收 `RecordEngine` 外观( e)`RECORD_ENGINE` 编号 : `RecordsService`从不游泳池. 许可门和审计阶段是强制性的。 消费者指南是: `@astram/guide` (单位:千美元)`CAPABILITIES.md`) (中文(简体) ).

## 复制密钥 : `UniqueConflictError`

记录 `create`, (中文(简体) ), `update`, (中文(简体) ), `createMany` 点击 UNIQUE 索引的行或操作写入创建 (司机错误1062) `UniqueConflictError` (GAPS#58, `docs/features/unique-conflict-error/SPEC.md`) (中文(简体) ). Guard 的全局过滤器以 `409 { statusCode: 409, code: 'unique_conflict', message: 'This record conflicts with an existing one.' }`。 。 。 .

-   字段 : `typeKey`, (中文(简体) ), `constraint` (索引名称,例如:. `uq_site_code`,或 `null` 当驾驶员 信件无法安全读取 , `rowIndex` (创建 Many: 以 0 为主的行; 整个批次滚动) )和只读 `errno: 1062` 编号 : `code: 'ER_DUP_ENTRY'` 旧的捕捉码.
-   和它比对 `isUniqueConflict(err, '<constraint>')`驱动程序 `sqlMessage` 信息为 未曝光: 它们命名值并携带 SQL 参数 。 错误从不包含值 没有 `cause`。 。 。 .
-   **内部 `transaction(fn)`** 失败的写入使交易只回滚: 抓取 错误和再次写入 `EngineUnavailableError` (503),而且没有任何承诺。 给 偶能接答,接取后再以一新交易再读.
-   **被围住的类型.** 非根创建于类型 `readScope` (无) `create: 'unscoped'`谁 输入位于角色的写范围解答之外 `create_outside_write_scope` (403) 即使当 值是重复的,与新值完全一样(没有关于行为者无法触及的值的预告). 对复制件的瞄准镜检查精确地比较了输入字节,所以一个案例或后继的空间变体 在对大小写不敏感字符串列上显示范围值,也可回答403(未关闭); uuid 范围 柱子总是有条理的 提供的主要密钥与一行相撞 演员不能 到达时还回答403,从未有确认身份的409。 如果范围检查无法运行,则 创建失败 `EngineUnavailableError` (503) (英语).
-   **租户类型:与租户列一起领导每个UNIQUE指数** (例如:. `UNIQUE (s_tenant, s_code)`) (中文(简体) ). 一个指数没有它横跨租户,所以一个409告诉打电话者,另一个租户持有这个价值.

## `lockForUpdate` 并锁定取自: 被墙锁

`lockForUpdate(typeKey, id)` (内部) `transaction(fn)`页:1 `tx.authorize(typeKey, id, action)` 只有在角色可以时, 交易会锁定一行 写它: 与一个 `update` (单位:千美元)`whereById`:主键+演员的房客+ `readScope` 写入壁; root: 仅主键). 在此之前 `FOR UPDATE`引擎检查 中,该行存在于该演员的正键读取并仅指壁柱 交易和必要时的专用 **锁定探测池** (每个工人2个连接,相同) 作为引擎池的账户和设置,每个探测器的READ COMMITED,获得超时2000毫秒)。 A 类 缺少,外国租户 或范围外的id 不取行锁.

### 行为变化(0.19)

在这个版本之前, `lockForUpdate` 失踪的、外国的或超出范围的身份 却无声无息 锁上(一个外国身份证被它的主键锁上)。 从这个版本,它发出同样的否认 a 一个 `update` 其中的id获得: `AuthorizationDeniedError` 有理无据 `no_record_permit` (一个答复) 三者,无存在信号. 代码,首先锁定,然后检查丢失的一行 或先检查存在( n)`get` 那么在交易中 `lockForUpdate`)或抓住那个 否认。 拒绝在任何锁定声明之前, 所以一个呼叫者抓住它可能会继续下去 进行交易.

-   `EngineUnavailableError` 从 `lockForUpdate` 或者锁定的接取意味着锁定的检测池没有 回答(需要超时、连接或查询出错)。 没有取出锁;让它传播(503). 失败被计算在内(`MariaDbUnitOfWork.lockProbeStats()`, (中文(简体) ), `@astram/engine/internal`)和登录 作为每分钟一个警告 与计数,从来没有id.
-   找不到其他交易插入但尚未执行的行( 旧的主键) 锁等.
-   如果在存在检查和锁之间删除一行,则 `FOR UPDATE` 打开一个缺口锁 在主键范围 周围的ID,直到交易结束。 它锁住没有现有的行 什么都没有.
-   应用程序的ADR -0018 连接预算 计算每个工人增加2个连接 (单位:千美元)`@astram/guard` `ENGINE_LOCK_PROBE_POOL_CONNECTIONS`),在两个数据库布局中.

谱: `docs/features/agent-proposals/SPEC.md` 第5 J条(GAPS #51).

## 常见问题

### @astram/engine 是什么？

Astram框架——铺平了的道路。 一个不可通通的写字管\(resolve-schema → perference gate → exterm-write-context → 校验 → 校验 → 交叉-同步 – 审计 → 发售 – 事件\),每个功能的 CRUD 流经真实的物理表\.

### 如何安装 @astram/engine？

在项目目录运行 npm install @astram/engine，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7）、@nestjs/core（^11）、@nestjs/common（^11）、reflect-metadata（^0\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @astram/engine 支持 TypeScript 吗？

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

### @astram/engine 支持 ESM 还是 CommonJS？

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

### @astram/engine 可以商用吗？

@astram/engine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @astram/engine 的下载量有多少？

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

### @astram/engine 还在维护吗？

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