@bearei/contracts

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

English | 中文

安装

yarn add @bearei/contracts

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

使用

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

开发

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 手动重跑。