# @api-ts/typed-express-router 中文文档

规范地址：https://npmcn.com/package/%40api-ts/typed-express-router/

版本：2\.0\.7
npm 元数据更新时间：2026-08-04T17:13:22.377Z
中文译文更新时间：2026-11-06T09:50:13.116Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40api-ts/typed-express-router
原文对照：https://npmcn.com/package/%40api-ts/typed-express-router/?lang=original
项目主页：https://github.com/BitGo/api-ts#readme
源码仓库：https://github.com/BitGo/api-ts

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

- 包体积（解压后）：53.9 kB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：@opentelemetry/api ^1\.0\.0
- 首次发布：2022-08-11T15:55:25.375Z
- 最新版本发布：2026-08-04T17:13:22.050Z
- 近 30 天下载量：72424（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 7 个）

## 中文简介

执行带有快递的 HTTP 规格

## 安装

```sh
npm install @api-ts/typed-express-router
```

也可以使用：`pnpm add @api-ts/typed-express-router`、`yarn add @api-ts/typed-express-router`、`bun add @api-ts/typed-express-router`

## README

# @ api-ts/ typed- sext- 路由器

绕着快递的一圈 `Router`

## 目标

-   定义与 api- ts 中的路线相关的快递路线 `apiSpec`
-   以已解码的请求对象和 api- ts 路由增强现有的 Express 请求 元数据
-   通过打字检查增强已有的快递响应 `encode` 函数
-   允许定制解码/编码出错的操作, 如果需要, 则按程序进行
-   允许在发送编码后的响应后( 如果需要) 按程序执行动作
-   允许路由定义路径不同于指定路径的别名 输入 `httpRoute`
-   尽可能跟紧快速路由器 api 否则

## 非目标

-   强制执行其中列出的所有路线 `apiSpec` 拥有相关的路由处理器
-   上面的图层 `express.RequestHandler[]` 额外的链条 描述的属性 `Goals` (项目和其他图书馆可以做到这一点)

## 使用量

### 创建路由器

这个库提供了两个非常相近的功能,它们分别创建或包装 快速路由器 :

```ts
import { createRouter, wrapRouter } from '@api-ts/typed-express-router';
import express from 'express';

import { MyApi } from 'my-api-package';

const app = express();

const typedRouter = createRouter(MyApi);
app.use(typedRouter);
```

### 添加路径

一旦你拥有 `typedRouter`,您可以通过 api-ts api 名称开始添加路由 :

```ts
typedRouter.get('hello.world', [HelloWorldHandler]);
```

这里, `HelloWorldHandler` 几乎像一个快递请求处理器,但 `req` 财务报告和审定财务报表 `res` 拥有额外的财产. `req.decoded` 包含已验证和已解码的请求. 在反应方面,有一个额外的 `res.sendEncoded(status, payload)` 函数 将在有效载荷上适当执行类型和编码类型(例如:. `BigIntFromString` 将转换为字符串。 导出 `TypedRequestHandler` 类型可以用来推断这些函数的参数类型.

### 路由别名

如果在路径路径中需要更大的灵活性,a `routeAliases` 函数可能是 以匹配多个路径。 这些路径可能使用匹配语法的完整快报, 但要注意保存任何路径参数 否则你可能会被解码出错.

```ts
typedRouter.get('hello.world', [HelloWorldHandler], {
  routeAliases: ['/oldDeprecatedHelloWorld'],
});
```

### 钩子和错误处理器

这个 `createRouter`, (中文(简体) ), `wrapRouter`,而单个路由方法都采用可选的最后一个 参数,其中可以提供响应后和错误处理功能。 一个 为特定路由指定,优先于顶级。 这些可能是 用于自定义错误响应并进行其他动作,如度量衡集合或 伐木业.

```ts
const typedRouter = createRouter(MyApi, {
  decodeErrorFormatter: (errs, req) => {
    // Format `errs` however you want
    return { message: 'Bad request' };
  },
  getDecodeErrorStatusCode: (errs, req) => {
    return 400;
  },
  encodeErrorFormatter: (err, req) => {
    return { message: 'Internal server error' };
  },
  getEncodeErrorStatusCode: (err, req) => {
    // Ideally won't happen unless type safety is violated, so it's a 500
    return 500;
  },
  afterEncodedResponseSent: (status, payload, req, res) => {
    // Perform side effects or other things, `res` should be ended by this point
    endRequestMetricsCollection(req);
  },
});

// Override the decode error handler on one route
typedRouter.get('hello.world', [HelloWorldHandler], {
  decodeErrorFormatter: customHelloDecodeErrorFormatter,
});
```

### 未检查路线

如果您需要解码错误的自定义行为, 则不只是发送一个 出错响应,然后可以使用路由器函数的不受控制的变体. 没错 不失败, 并使用 http 响应发送 `decodeErrorFormatter` 财务报告和审定财务报表 `getDecodeErrorStatusCode` 当请求无效时。 相反,他们仍然会大量使用 `req.decoded`除了这次,它会包含 `Either<Errors, DecodedRequest>` 类型 供路由处理人员检查.

```ts
// Just a normal express route
typedRouter.getUnchecked('hello.world', (req, res) => {
  if (E.isLeft(req.decoded)) {
    console.warn('Route failed to decode! Continuing anyway');
  })

  res.send(200).end();
});
```

### 路由器中间软件

中间软件添加到 `typedRouter.use()` 在请求解码后运行 在验证之前,甚至在检查过的路线上。 它可以进入 `req.decoded` 内 和无节制的路线一样.

### 其他用途

除了上面记载的以外 包裹的路由器应该像普通的 一号快递,所以.. `typedRouter.use()` 应该有同样的行为.

## 常见问题

### @api-ts/typed-express-router 是什么？

执行带有快递的 HTTP 规格

### 如何安装 @api-ts/typed-express-router？

在项目目录运行 npm install @api-ts/typed-express-router，或使用 pnpm add / yarn add / bun add。

### @api-ts/typed-express-router 支持 TypeScript 吗？

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

### @api-ts/typed-express-router 支持 ESM 还是 CommonJS？

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

### @api-ts/typed-express-router 可以商用吗？

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

### @api-ts/typed-express-router 的下载量有多少？

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

### @api-ts/typed-express-router 还在维护吗？

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