# @bearei/contracts 中文文档

规范地址：https://npmcn.com/package/%40bearei/contracts/

版本：3\.4\.1
npm 元数据更新时间：2026-11-06T05:21:26.980Z
中文译文更新时间：2026-11-07T20:02:47.749Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：55.4 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-26T15:25:45.764Z
- 最新版本发布：2026-11-06T05:21:26.810Z
- 近 30 天下载量：2764（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Bearei服务、客户和应用共享的框架不可知线合同

## 安装

```sh
npm install @bearei/contracts
```

也可以使用：`pnpm add @bearei/contracts`、`yarn add @bearei/contracts`、`bun add @bearei/contracts`

## README

# @bearei/contracts

Bearei 服务、客户端与应用共享的传输契约，不依赖任何框架。包本身没有运行时依赖，同时提供 ESM 与 CommonJS 两种产物。

[English](https://npmcn.com/package/%40bearei/contracts/README.md) | 中文

| 导出 | 类型 | 用途 |
| --- | --- | --- |
| `HTTP_EXCEPTION_CODE`、`HttpExceptionCode` | 值 | 服务与客户端共享的数字错误码 |
| `ApiErrorBody`、`ApiValidationErrorBody`、`ApiErrorResponseBody` | 类型 | 业务错误体与校验错误体 |
| `DEFAULT_PAGE_SIZE`、`MAX_PAGE_SIZE` | 值 | 所有列表接口使用的分页上限 |
| `PaginationQuery`、`PaginatedResult<T>` | 类型 | 分页请求字段与分页响应信封 |
| `RESERVED_REQUEST_HEADER`、`ReservedRequestHeaderName` | 值 | 由网关或认证层写入的保留请求头 |
| `LANGUAGE`、`Language` | 值 | 语言值 |
| `EMAIL_TEMPLATE`、`EmailTemplate` | 值 | 服务与客户端共用的邮件模板值 |
| `ORDER`、`Order` | 值 | 排序值 |
| `PAYMENT_CHANNEL`、`PAYMENT_ENVIRONMENT`、`PAYMENT_EVENT_TYPE` | 值 | 支付服务与订阅服务共用的支付契约词表 |
| `PAYMENT_TRANSACTION_STATE`、`PaymentTransactionState` | 值 | 支付服务返回的交易状态值 |
| `PERMISSION`、`Permission`、`ALL_PERMISSION_KEY` | 值 | 服务与客户端共用的权限值与管理员哨兵值 |
| `SUBSCRIPTION_FEATURE`、`SubscriptionFeature` | 值 | 订阅特性值，与权限使用相同的区域写法 |

## 安装

```bash
yarn add @bearei/contracts
```

本包不声明任何运行时依赖或 peer 依赖，安装它不会向依赖树加入其他包。

## 使用

```ts
import {
    DEFAULT_PAGE_SIZE,
    HTTP_EXCEPTION_CODE,
    RESERVED_REQUEST_HEADER,
    type ApiErrorBody,
    type PaginatedResult
} from '@bearei/contracts'

const error: ApiErrorBody = {
    code: HTTP_EXCEPTION_CODE.NOT_FOUND,
    message: 'Not Found',
    statusCode: 404
}

const subject = request.headers[RESERVED_REQUEST_HEADER.SUBJECT]
const page: PaginatedResult<{id: string}> = {
    page: 1,
    pageSize: DEFAULT_PAGE_SIZE,
    results: [{id: 'a'}]
}
```

`ApiErrorBody` 对应守卫、服务与共享异常抛出的业务错误。请求参数校验错误使用 `ApiValidationErrorBody`，保留字段错误数组；`ApiErrorResponseBody` 是两者的联合类型。 `ALL_PERMISSION_KEY`（`all:all`）是 `bearei-permission` 对管理员返回的响应哨兵值，不是可授予的 权限键。

### 模块格式

`exports` 映射会让 `import` 使用 ESM 产物、`require` 使用 CommonJS 产物；TypeScript 会自动选择 对应的声明文件（`.d.mts` 或 `.d.ts`）。

## 收录范围

这里只放传输边界两端必须一致的值与类型：

-   数字错误码与错误响应体
-   API 客户端与服务共享的查询、响应结构
-   保留请求头名称
-   语言、排序、权限、订阅特性、支付契约值等跨项目枚举

框架相关代码不放进这里：NestJS 装饰器、守卫、拦截器，TypeORM 实体，HTTP 客户端，持久化， 以及仅服务端使用的 DTO 都留在各自的库中。

`HTTP_EXCEPTION_CODE` 的数值属于线上契约。只能追加新错误码，不得重新编号或复用已有数值； 重命名错误码同样会破坏按名称引用它的使用者。

## 开发

```bash
yarn install
yarn verify       # 格式 + lint + typecheck + 覆盖率 + 构建
yarn run pack   # 打包一次并检查 tarball
```

## 发布

发布由版本 tag 驱动。先修改 `package.json` 的 `version` 并更新 `CHANGELOG.md`，再推送同版本 tag （`3.0.0` 与 `v3.0.0` 均可）。tag 必须等于包版本；稳定版 tag 必须位于 `main`，预发布 tag 必须位于 `main` 或 `develop`。

`.github/workflows/release.yml` 随后会：

1.  执行 `yarn verify`；
2.  打包一次并校验 tarball 的文件清单与导出映射；
3.  通过 npm Trusted Publishing（OIDC）发布该 tarball，稳定版使用 `latest`，预发布（如 `2.3.0-rc.1`）使用 `next`；
4.  从 registry 下载已发布的 tarball 并再次校验；
5.  创建 GitHub Release，附件为 `bearei-contracts-<version>.tgz`（dist-tag 为 `next` 时标记为 pre-release）。

发布前需在 npmjs.com 上为 `@bearei/contracts` 登记本 GitHub 仓库、`release.yml` 工作流与 `npm` 环境作为 trusted publisher。`workflow_dispatch` 可用已有 tag 手动重跑。

## 常见问题

### @bearei/contracts 是什么？

Bearei服务、客户和应用共享的框架不可知线合同

### 如何安装 @bearei/contracts？

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

### @bearei/contracts 支持 TypeScript 吗？

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

### @bearei/contracts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bearei/contracts 需要什么版本的 Node\.js？

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

### @bearei/contracts 可以商用吗？

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

### @bearei/contracts 的下载量有多少？

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

### @bearei/contracts 还在维护吗？

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