# @adaptivestone/framework 中文文档

规范地址：https://npmcn.com/package/%40adaptivestone/framework/

版本：5\.6\.0
npm 元数据更新时间：2026-10-27T21:21:48.775Z
中文译文更新时间：2026-11-06T17:34:12.204Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adaptivestone/framework
原文对照：https://npmcn.com/package/%40adaptivestone/framework/?lang=original
项目主页：https://framework.adaptivestone.com/
源码仓库：https://github.com/adaptivestone/framework

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

- 包体积（解压后）：1.3 MB，409 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.0\.0
- 运行依赖：7 个
- peer 依赖：yup ^1\.7\.0，zod ^3\.24\.0 \|\| ^4\.0\.0，vitest ^4\.0\.0 \|\| ^5\.0\.0，i18next ^26\.0\.1，oxc-parser ^0\.156\.0，@sentry/core ^10\.34\.0 \|\| ^11\.0\.0，@sentry/node ^10\.34\.0 \|\| ^11\.0\.0，@redis/client ^6\.0\.0，i18next-fs-backend ^2\.0\.0，mongodb-memory-server ^11\.0\.0，@adaptivestone/framework-module-email ^2\.1\.0
- 首次发布：2020-01-08T08:20:11.589Z
- 最新版本发布：2026-10-27T21:21:48.562Z
- 近 30 天下载量：2573（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：246（近 12 个月 44 个）

## 中文简介

适应性石头节点js框架

## 安装

```sh
npm install @adaptivestone/framework
```

也可以使用：`pnpm add @adaptivestone/framework`、`yarn add @adaptivestone/framework`、`bun add @adaptivestone/framework`

## README

# @ 适应石/ 框架

基于公约的控制器和 Mongoose 模型,基于树的路由器,每个控制器生成路由/处理器 i18n)和缓存.

📖 **完整文件 ∗∗ [https://framework.adaptivestone.com/\* (中文(简体) )](https://framework.adaptivestone.com/*)\* 联合国**

🤖 **LLM 已准备好的文件( 完整站点为一个文件) — [https://framework.adaptivestone.com/llm-context.md\* (中文(简体) )](https://framework.adaptivestone.com/llm-context.md*)\* 联合国**

## 所需资源

-   **节点 24** (仅ESM,运行) `.ts` ——或 **1.4.0号机**,参见 [运行时间](https://npmcn.com/package/%40adaptivestone/framework/#readme-runtimes)
-   **蒙戈DB** - 需要;没有启动便快速失效 `MONGO_DSN`
-   **`AUTH_SALT`** 需要; 生成一个 `node src/cli.ts generateRandomBytes`

## 运行时间

节点是主运行时间. **1.4.0号机** 作为一项补充支持: 同样的应用代码,同样的快递适配器,运行在 Bun 节点上 兼容层 — 没有 Bun 特定构建, 没有 `Bun.serve` 路径,以及 不需要依赖性指针或覆盖。 1.4.0是地板,因为它是第一个 输入框架解析的Mongoose/BSON图的平面布局.

每一次发布都经过认证, 无论是在地板上还是最新的稳定舱: 框架测试套件;和 安装已公布的柏油球的消费者 `bun install`,进口公共入境点,靴子a `Server`,服务于 请求,运行 Mongoose 创建/读取/更新/删除对 MongoDB 并关闭.

仅节点,截至1.4号机:

-   **`cluster.js` 编号 : `runCluster`** ——多工艺生产入站. 这个 在 Bun 下导入精细, 但仅测试节点路径; 运行单进程 由 Bun (或将进程管理器置于应用程序之外).
-   **节点测试跑者CLI.** Bun 执行 `node:test` _API 密码_ 但没有 `node --test`,所以一个Bun项目运行它的套房与 `bun test` 编辑 框架预装,而不是节点文件显示的旗帜。 四个框架 测试文件需要 `mock.module()` (节点) `--experimental-test-module-mocks`, (中文(简体) ), bun 不执行的[烤箱-sh/bun#5090](https://github.com/oven-sh/bun/issues/5090)),并且是唯一一个 bun 运行中排除的东西 : `cluster.test.ts`, (中文(简体) ), `models/UserOld.test.ts`, (中文(简体) ), `helpers/redis/redisConnection.failure.test.ts`, (中文(简体) ), `services/i18n/I18n.missing.test.ts`所有其它东西都会在两跑时间上流传.
-   **`assert.deepStrictEqual` 对抗蒙哥斯阵列.** Bun 1.4报告任何 `Proxy` Mongoose阵列就是这样的 不平等 先散开 (单位:千美元)`[...doc.tags]`) (中文(简体) ). 这是一个测试的诡异; 价值本身是 没错.

## 快速启动

最快的启动方式是复制示例项目并将其用作 模板 - 它运送一个工作 `Server`、控制器、配置、测试和一个多克 dev 堆栈( 包括MongoDB + Redis) :

```sh
git clone https://github.com/adaptivestone/framework-example-project.git my-app
cd my-app
docker compose up
```

您的应用开始于 `http://localhost:3300`。提供 `AUTH_SALT` 开始之前 启动(见要求和 `.env.example`) (中文(简体) ). 编辑控制器 `src/controllers/` 而 Dev 服务器会自动重新装入。 完全进入 页:1 [获得开始的引导](https://framework.adaptivestone.com/)。 。 。 .

将框架添加到现有项目中:

```sh
npm install @adaptivestone/framework
```

## 升级说明(5.6.0)

见 [5.6.0发布说明](https://npmcn.com/package/%40adaptivestone/framework/CHANGELOG.md)。升级时检查这些 :

-   注册自定义验证器驱动程序( D)`ValidateService.register`在模块中 范围,在 `startServer()`路线现在选择他们的司机 一次在靴子,所以 注册在 `bootHttp` 钩子已经没了,而且.. 没有驱动匹配失败 `startServer()` 而不是回答500个.
-   静态路由只回答它定义的方法. 与 `GET /events/new` 财务报告和审定财务报表 `DELETE /events/:slug`, (中文(简体) ), `DELETE /events/new` 现在到达 页:1 `:slug` 而不是回答405.
-   每架车 `RateLimiter` `consumeKeyComponents.request` 列表替换 配置列表而不是添加到列表中 。 依靠两个清单的挂载 必须指定每个字段.
-   运行的项目 `npm run gen` 必须更新可选对等点 : `npm i -D oxc-parser@^0.156.0`。 。 。 .

## 升级说明(5.5.1)

见 [5.5.1 释放说明](https://npmcn.com/package/%40adaptivestone/framework/CHANGELOG.md)。大多数不需要采取行动:

-   运行的项目 `npm run gen` 必须更新可选对等点 : `npm i -D oxc-parser@^0.153.0`。 。 。 .
-   当用户读完密码后, `user.generateToken()` 拒绝400 `BadRequestError` (答案与错误密码相同) 而不是一只绵羊 `VersionError` 或者说 `DocumentNotFoundError`一个抓住你 为周围的人添加 `generateToken` 可以离开.
-   子类 `Auth` 财务报告和审定财务报表 `Role` 可能从 `middleware()` 再来一次.

## 升级说明(5.5.0)

见 [5.5.0发布说明](https://npmcn.com/package/%40adaptivestone/framework/CHANGELOG.md) 对一切新的。 检查这些何时 您升级 :

-   日志默认被编辑: 字段命名 `authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `password`, (中文(简体) ), `secret` 或者说 `token` 以 `[REDACTED]`。自定义 `redact` 列表中 `config/log.ts` 替换默认值,所以将这些名称保留在 (a) 与《公约》有关的规定; `redact: []` 关闭编辑.
-   几处错误反应有变. 野外误差400多发 `message` 财务报告和审定财务报表 每场阵列(安全网) `errors.<field>` 以前是弦,每500个 有一个文本,默认的404文本是 `Not found`,则 `Role` 财务报告和审定财务报表 `RateLimiter` 答复携带 `error` 密码 比较整个身体的测试 可能需要更新.
-   中间软件所抛出的错误会通过处理错误的登记册: a `HttpError` 从一个中间的软件 回答自己的地位 而不是500. 内置 `Auth`, (中文(简体) ), `Role` 财务报告和审定财务报表 `RateLimiter` 现在扔而不是写 反应,所以直接调用他们的测试 一定预料到一个抛出的错误.
-   内置健康终点在 `/health/live` 财务报告和审定财务报表 `/health/ready`。您的 拥有 `controllers/Health.ts` 替换它们; `GET /health` 自己保持自由.
-   请求按键费率限额的计数器(`consumeKeyComponents.request`重设 部署时:其密钥现已正常化并散列.
-   新建 : `npm run cli createEnv` 创建 `.env` 有新鲜的 `AUTH_SALT` 编号 新鲜克隆.
-   已折旧,在v6中被删除: `usedAuthParameters` (现在) `authSchemes`页:1 职位 `body` 论点 `HttpError`, (中文(简体) ), `RateLimiter.gerenateConsumeKey`, (中文(简体) ), 财务报告和审定财务报表 `notVerified` 在未经验证的日志中.

## 升级说明(5.4.2)

见 [5.4.2 释放说明](https://npmcn.com/package/%40adaptivestone/framework/CHANGELOG.md) 用于所有修复。 大多数人不需要行动:

-   运行的项目 `npm run gen` 必须更新可选对等点 : `npm i -D oxc-parser@^0.152.0`。 。 。 .
-   `user.generateToken()` 现在用一只绵羊拒绝 `VersionError` 当 文档装入后存储的密码已更改; 内置登录 回答这个是密码错误 。 自定义登录流量应该同样进行.
-   HTTP 服务器仅在路由后打开端口, `bootHttp` 错误 操作器安装; `startServer()` 它一听就决定了.
-   `createuser --token` 打印可用的会话符号;没有标记,则 命令不再创建会话.

## 认证和缓存升级说明(5.4.1)

见 [5.4.1 释放说明](https://npmcn.com/package/%40adaptivestone/framework/CHANGELOG.md) 包括模型/验证 输入更正和可选的 i18 次声明更改.

内置登记和密码重置路线接受15-128的密码 Unicode代码点,包括空格. 登录时仍可使用现有密码. 要自定义长度限制,请在应用程序中扩展默认值 `src/config/auth.ts`数字 :

```ts
import auth from '@adaptivestone/framework/config/auth.js';

export default {
  ...auth,
  passwordPolicy: { minLength: 15, maxLength: 128 },
};
```

该政策适用于内置的 HTTP 路由; 直接模式写作和自定义 密码更改终点必须执行自己的政策。 翻译 `auth.passwordTooShort` 财务报告和审定财务报表 `auth.passwordTooLong` 以自定义验证 电文 (`min` 财务报告和审定财务报表 `max` 可用作插值参数.

与 `consumeKeyComponents.route` 启用, 速率限制使用已注册的路由 还有方法 案例的变体、编码拼写、跟踪鞭打和不同 参数值共享相同的预算;隐含的HEAD股份获取预算. 路由前安装的限速器将每个方法共享一桶,而不拆分 根据请求的 URL 。 升级一次现有费率限制计数器; 滚动 所以年长的工人不能单独保留别名.

缓存密钥现在包含 a `cache-v2` 标记此字符串并签名 BigInts 来回 没有碰撞。 升级始于冷缓存; 旧密钥过期于 他们的原始TTL。 在混合版本部署期间,每个版本无效 只有它自己的钥匙空间,所以在依赖交叉工作前完成推出 缓存无效 。 快取被击中/ 丢失日志中不再包含密钥或值 .

## 生成类型

框架生成 `genTypes.d.ts` (类型) `getConfig`编号 :`getModel`和 每个控制器 `*.routes.gen.ts` 文件(类型处理器签名)。 重新生成 它们包括:

```sh
node src/cli.ts generatetypes
```

代码生成需要 **可选同伴依赖 `oxc-parser`** - 安装它 作为您项目的依赖性:

```sh
npm i -D oxc-parser
```

它解析了您的控制器源, 并且从未在运行时被装入, 所以它会停留 生产外安装(`npm ci --omit=dev`) (中文(简体) ).

它们被取出后再生(新鲜的取出是红色的) 编辑器直到第一次运行). 在CI中,防范被打成哑巴的类型 `node src/cli.ts generatetypes --check`,它不写,退出非零 如果什么是过时的。 模板将它接入 `check:types` 剧本.

从v5.2.0开始,一个完全由括号组成的控制器文件夹段是一个 组织路线组: `src/controllers/(group)/Reports.ts` 留着 默认 `/reports` URL, 而其生成的文件仍然位于控制器旁边 . 普通文件夹仍然贡献其小写 URL 部分 .

## 打开API

从相同的控制器路径生成 OpenAPI 3.1 文档并请求 运行时使用的策略 :

```sh
node src/cli.ts openapi --output openapi.json
```

Zod request schemas描述它们的输入形状. 不支持的个人 schema 生成一个背景警告和安全回落而不清除健康 来自文档的路径。 见全 [OpenAPI 指南](https://framework.adaptivestone.com/docs/openapi)。 。 。 .

## 公共 API 稳定性

只有下面列出的子路径 `exports` 内 `package.json` 可导入为 `@adaptivestone/framework/<path>`;内部模块故意不 导出。 导出路径依次分两个层次:

-   **第一级——稳定:** `server.js`, (中文(简体) ), `Cli.js`, (中文(简体) ), `cluster.js`, (中文(简体) ), `types.js`, (中文(简体) ), `folderConfig.js`, (中文(简体) ), `modules/*`, (中文(简体) ), `models/*`, (中文(简体) ), `controllers/*`, (中文(简体) ), `tests/*`, (中文(简体) ), `migrations/*`。 。 。 .
-   **第二级——扩展表面:** `config/*`, (中文(简体) ), `helpers/*`,以及 `services/*` 可能 未成年人的改变(有堕落周期); 进口时给未成年人钉上钉子 直接说. `config/*` 是您导入用于扩展框架默认值的内容 配置( 如 . `import http from '@adaptivestone/framework/config/http.js'`,则 再导出您自己编辑的副本 `src/config/http.ts`) (中文(简体) ).

## 许可证

麻省理工学院

## 常见问题

### @adaptivestone/framework 是什么？

适应性石头节点js框架

### 如何安装 @adaptivestone/framework？

在项目目录运行 npm install @adaptivestone/framework，或使用 pnpm add / yarn add / bun add。

### @adaptivestone/framework 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adaptivestone\_\_framework 是否存在。

### @adaptivestone/framework 支持 ESM 还是 CommonJS？

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

### @adaptivestone/framework 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adaptivestone/framework 可以商用吗？

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

### @adaptivestone/framework 的下载量有多少？

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

### @adaptivestone/framework 还在维护吗？

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