# @debugr/http-common 中文文档

规范地址：https://npmcn.com/package/%40debugr/http-common/

版本：4\.0\.2
npm 元数据更新时间：2026-08-31T16:40:20.502Z
中文译文更新时间：2026-11-11T18:57:35.432Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：23.3 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2022-08-02T09:46:37.626Z
- 最新版本发布：2026-08-31T16:40:20.208Z
- 近 30 天下载量：9101（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 3 个）

## 中文简介

HTTP 插件的共同接口和工具功能

## 安装

```sh
npm install @debugr/http-common
```

也可以使用：`pnpm add @debugr/http-common`、`yarn add @debugr/http-common`、`bun add @debugr/http-common`

## README

# 通用HTTP接口和公用设施

此软件包定义了 `data` 包含在条目中 代表 HTTP 请求或回复。 生成或消耗此类条目的插件 应该符合这个形状。 除非你正在开发调试器插件 或日志处理器,你通常不需要担心 这个包,因为它会 在需要时自动安装和使用.

## 用于插件开发者

该套件输出以下类型定义:

```typescript
export interface HttpHeaders {
  [header: string]: number | string | string[] | undefined;
}

export interface HttpRequestData {
  method: string; // The uppercase HTTP request method, e.g. 'GET', 'POST' etc.
  uri: string; // The request URI including query string, if any
  headers?: HttpHeaders; // A map of HTTP headers to values or lists of values. Header names should be lower-case.
  ip?: string; // The client IP, if it can be determined.
  body?: string; // The request body as a string, if the request body was captured.
  bodyLength?: number; // Request body length in bytes derived from the actual request data, NOT from the Content-Length header.
  lengthMismatch?: boolean; // This should be `true` if the actual request body length didn't match the Content-Length header.
}

export interface HttpResponseData {
  status: number; // HTTP response status code.
  message?: string; // HTTP response status message.
  headers?: HttpHeaders; // A map of HTTP headers; same format as for request headers.
  body?: string; // The response body as a string, if the response body was captured.
  bodyLength?: number; // Response body length in bytes derived from the actual response data, NOT from the Content-Length header.
  lengthMismatch?: boolean; // This should be `true` if the actual response body length didn't match the Content-Length header.
}

export interface HttpRequestLogEntry<
  TTaskContext extends TContextBase = TContextBase,
  TGlobalContext extends TContextShape = TContextShape,
> extends LogEntry<TTaskContext, TGlobalContext> {
  type: 'http.request';
  data: HttpRequestData;
}

export interface HttpResponseLogEntry<
  TTaskContext extends TContextBase = TContextBase,
  TGlobalContext extends TContextShape = TContextShape,
> extends LogEntry<TTaskContext, TGlobalContext> {
  type: 'http.response';
  data: HttpResponseData;
}
```

此外,还输出了若干公用事业功能:

-   `getHttpStatusMessage(status: number): string` - 此函数将返回给定的标准 HTTP 状态消息 状态代码,或 `(unknown)` 如果状态代码没有定义信件.
-   `formatHttpHeaders(headers: HttpHeaders): string` - 此函数将类似方式格式化 HTTP 头图 标题将采用实际请求或答复标题的格式。 用于格式化快捷键 对于试图显示请求或响应信息的日志处理器,无法保证信头 这样的格式将符合规格或可用于实际请求或答复.
-   `createHttpHeadersFilter(exclude?: string[]): HeaderFilter` - 此函数将创建过滤回调功能,您可以 用于替换 `exclude` 带有字符串的列表 `**redacted**`通常你会用这个 包含敏感信息的信头,例如 `Cookie` 或者说 `Authorization`。 。 。 .
-   `createHttpCaptureChecker(option: CaptureBodyOption = false): CaptureBodyChecker` - 此函数将创建回调 您可以用来检查是否根据定义的规则捕获特定的请求或响应机构 (按规定) `CaptureBodyOption`A级 `boolean` 意思是,你期望它意味着: `true` 意味着永远抓住, `false` 意味着永远不捕捉。 如果你通过一个 `number`,它解释为以字节表示的最大体积。 如果你通过一个 `string` 或一个 `string[]`,它将被转换成一种模式,将对照 `Content-Type` 头曰. 模式 能够包含星号( q)`*`)代表一个或多个字符;字符串也可以包含多个图案分离 以逗号(`,`)或一个或多个白空字符。 以下都是有效模式的例子: `text/html`, (中文(简体) ), `text/*`, (中文(简体) ), `text/*, application/json`, (中文(简体) ), `['image/svg', 'text/*, application/json']`上一个窗体 `CaptureBodyOption` 能取为一 `Record<string, boolean | number>`,键的相匹配模式 `Content-Type` 标题 和数值为布尔或数字,其语义与上述相同;当不存在匹配条目时 对于特定内容类型, `false` 假设.
-   `normalizeContentType(type?: number | string | string[]): string | undefined` - 此函数使内容类型正常化 从请求或响应页头映射到字符串中,可选地将第一个后的任何后缀去除 `;` 字符键.
-   `normalizeContentLength(length?: number | string | string[]): number | undefined` - 此功能使内容正常化 从请求或响应头图到数字的长度.

## 常见问题

### @debugr/http-common 是什么？

HTTP 插件的共同接口和工具功能

### 如何安装 @debugr/http-common？

在项目目录运行 npm install @debugr/http-common，或使用 pnpm add / yarn add / bun add。

### @debugr/http-common 支持 TypeScript 吗？

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

### @debugr/http-common 支持 ESM 还是 CommonJS？

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

### @debugr/http-common 需要什么版本的 Node\.js？

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

### @debugr/http-common 可以商用吗？

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

### @debugr/http-common 的下载量有多少？

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

### @debugr/http-common 还在维护吗？

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