# @gate-forge/pack-http 中文文档

规范地址：https://npmcn.com/package/%40gate-forge/pack-http/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T03:56:06.986Z
中文译文更新时间：2026-11-15T23:57:57.469Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gate-forge/pack-http
原文对照：https://npmcn.com/package/%40gate-forge/pack-http/?lang=original
项目主页：https://github.com/umiddey/gateforge#readme
源码仓库：https://github.com/umiddey/gateforge

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

- 包体积（解压后）：397 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：5 个
- 首次发布：2026-09-16T21:52:36.283Z
- 最新版本发布：2026-11-10T03:56:06.553Z
- 近 30 天下载量：2552（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

通用HTTP曝光包:用于路由注册的TS检测器(Express, Fastify, Hono, NestJS),用于前端API-客户呼叫的受限静态数据流(fetch, Axios, 例, 包装器, 常数, URL 构建器), http.contract evidence facts pluser

## 安装

```sh
npm install @gate-forge/pack-http
```

也可以使用：`pnpm add @gate-forge/pack-http`、`yarn add @gate-forge/pack-http`、`bun add @gate-forge/pack-http`

## README

# @gate-forge/pack-http——通用HTTP曝光包

找到纯TypeScript的流程中检测器 **外部可达到的 HTTP 文物** 内 `.ts`编号 :`.tsx`编号 :`.js`编号 :`.jsx`编号 :`.mjs`编号 :`.cjs` 来源——不执行, 没有网络,没有外接道具——并发出 `http.contract` **证据事实** (ADR0004 D1),为引擎端点-编译器相接. 薄荷薄荷 **没有 分类信号** (狗粮补救阶段4):

-   **服务器路径**页:1 `app.get('/accounts', …)` 编号 : `router.post(…)`, (中文(简体) ), 快速登记和Hono登记(进口 -- -- 变相,包 -- -- 自动) 公约),以及雀巢JS `@Controller('accounts')` + 键 `@Get/@Post/@Put/ @Patch/@Delete/@All('…')` 作装饰. `app`编号 :`server`编号 :`router` 按惯例是服务器名称; a `api.<verb>()` 电话计数为注册 **仅限** 文件导入服务器的地方 框架(表达/简化/hono),因为这也是轴线的原理 例如, Playwright 请求上下文, 或 api- client 模块拼写 其呼声——将呼声读作路由 薄荷服务器路由出测试 和客户呼叫网站.
-   **前端 API 客户端呼叫** (固定数据流动,计划阶段3): 直线字 `fetch`/亚克星, `fetch(url, { method })`, Axios 配置 对象和实例,配置的客户端符号(`apiClient.get`, (中文(简体) ), 纯 URL 构建器( E)`buildApiPath` 模块 常数(局部和扫描组内导入),模板 带有位置的文字 `${}` 插槽和简单的单还原包装 函数。 计算方法,任意调和, 环境依赖主机、未申报的包装和包装流 在模型外发射 **键入未解决的条目** 他们从来没有 消失,从不默认得到。 模拟 Axios 实例创建 有经证明的文字 `baseURL` 将这个基数加入发送的呼叫中 路径(参见 _加入实例库URL_ 页:1.
-   **动词 `fetch(url, options)`** 来自于边框 请求- 选项模型, 从“ 选项不是内置的 ” 中从未显示 : a 内置对象( n)`method` 与最后的写作者一起阅读, 所以传播 模块镜常数 命名一个,或对一个扫描函数的调用,其正体是一个单一的 `return <expression>` 其第一个参数与该参数结合 (所以一个转发者通过它解决). 证明不带的选项 `method` 保留平台默认 —— 获取真正的是呼叫 发送。 无法读取模式生成键 `HTTP_METHOD_DYNAMIC` 条目和 **无唤作事实**:在电话之前 被记录为 GET 并加入了服务器从未服务的路由 .

## 客户端扫描配置

配置宣布可解析的 API, 绝不允许覆盖 (单位:千美元)`.gateforge/http-clients.json`,或通过 `clientScan` 工厂:

```json
{
  "clientScanRoots": ["frontend/**"],
  "serverScanRoots": ["src/**", "services/**"],
  "clientSymbols": [
    "apiClient",
    { "name": "api", "include": ["frontend/src/**"], "exclude": ["frontend/src/generated/**"] }
  ],
  "wrapperFunctions": [{ "name": "apiGet", "method": "GET", "include": ["frontend/**"] }],
  "urlBuilders": [{ "name": "buildApiPath", "base": "/api" }],
  "sameOriginHosts": ["app.example.com"]
}
```

模块镜功能,其机体会给客户端打电话IS 包装: 拨打它而不宣布它与屏蔽 `FRONTEND_CALL_TARGET_UNRESOLVED` ——删除包装支持永远不会 静静地消失(红色探测器).

URL模型也解决了这些有限度的形状,并且只能解决: 单项任务 `const` (靠近点) `let` 两者均未解决 条件分支,a `const` 对象升查取( 每个 字元键值; 计算出键、 差值和 `let` 摆放桌子 未解决),一个已分解的亲属 `import()` 配置的别名 符号或构建器,以及返回表达式的同文件函数 是一个有限的可解析的集合。 A 类 `const` 名称 `fetch` 其初始化器 获取 API 不是一个获取呼叫 。 包装项可能名称 `parameter` (终点参数; 缺席表示第一个参数) 设置 `methodFromBody: true` 当身体发行超过一个 混凝土动词. 申报可以是相对进口,包括: 默认导出,以及 JSX 属性 `parameter` 是一个呼叫站. 设置外的任何东西 都会是未解决的输入 .

### 实例 baseURL 加入( 来源证明, 失败关闭)

前端通常会创建一个有基础路径的 Axios 客户端, 然后 写每个调用基数关系 `axios.create({ baseURL: '/api' })` 加号 `apiClient.get('/v1/x')` 点击数 `/api/v1/x` 在运行时间。 无 后端路由比较为 `/v1/x` 走开 单为前缀取出无线. 当一个实例符号的创建是 模式化,其 **已证实的文字 `baseURL` 加入发送的呼叫 路径**数字 : `normalizedPath = normalize(baseURL + callPath)`这是 源被证明,没有配置——不存在新的配置密钥.

**提炼.** 模型化的创建形状是模块镜 `const x = axios.create({...})`。基础从配置中读取 参数在属性顺序中,最后一个写入器获胜(JavaScript对象) 语义学:直接 `baseURL` 属性,和分布a **已声明 常数配置对象** 创建来自或扩展 (单位:千美元)`axios.create(config)`, (中文(简体) ), `axios.create({ ...defaults })`),解决 通过与路径常数相同的受限值表——本地 模块-瞄准镜常数和相对导入,循环保护。 A 类 非文学基础(env可变、计算、未建模的工厂) 未证出相.

**所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出.**

1.  符号的模块-镜像创建在呼叫站点文件本身.
2.  在提供约束的相对导入模块中创建 (现有有限度的进口机械,没有更松的).
3.  否则a **在整个扫描过程中对符号作出独特的声明 产品集** —— 配置的同义信道已经处理 名称为全球,真实的 API 客户端是单通,所以 异名输入创建( :`from '@/lib/apiClient'`解决这里. 失败关闭: 每个同名的创建都必须是模型 `axios.create` 并且所有经证明的根据必须同意 或任何无法证明的同名创作否决权 加入我们。 搜索会留在里面 `clientScanRoots` (范围外) e2e模拟实例不能毒害产品通话),从未适用于 光线 `axios` 全球,除非 被跟踪在呼叫文件本身.

**加入语义论.** 就用一根斜缝来缝合 轴心 `combineURLs` 样式 : 尾随底部被击倒, 并导致呼叫路径被击倒 (单位:千美元)`/api/` + 键 `/v1/x` → `/api/v1/x`) (中文(简体) ). 空和 `/` 基地不加入; 绝对调用 URL (`https://…`协议关系 `//`)无视 基数并保持现有的绝对-URL / `sameOriginHosts` 规则; a 字面绝对基数 加入并加固其路径部分 配置同源主机 。 带有可解析孔的基模板 (单位:千美元)`/api/${version}`() 以位置加入; 无法解开的孔保持 基础未证实.

**什么变化和什么从来没有做.** 只有事实 `normalizedPath` 获得前缀—— `rawPath` 保持原样 正常化本身(干燥/分解, `${}`编号 :`{}` 时间档, 斜线倒塌)不变. 加入的路径会遇到 端点编译器像其它路径一样加入字面规则 (该引擎为 `@gate-forge/http-contract`) (中文(简体) ). 呼吁 不加入任何行为 字节和之前相同, 并且从未加入 把经过的呼叫点变成阻塞器 折叠函数不加入 其内部客户基础(有记录的边界——宣布 包件的路径完整,或者使用带有 `base`) (中文(简体) ). 这个 `urlBuilders[].base` 频道没有改变:它是配置宣布的, 所以建造者的基础是 解决价值本身的一部分.

### 反应字段为(绑定、文件本地)

每一个前传的事实 `attributes.responseReads`: 字段 呼叫网站读取了该呼叫本身的响应, 每一个都有位置 读本。 这是前端 一半的投放反应现场证据 (合并前端为 `invoice.dueDate` fastAPI 模型完成后 放弃了;每次测试都嘲笑了反应,屏幕显示 和它收集 相同的有限度的通行证 解决 调用目标——没有执行,没有类型检查器,没有交叉文件推断.

这个模型是故意小的:

-   呼叫本身的等待结果通过 `await` 财务报告和审定财务报表 括号; `<result>.data` 有效载荷(轴/公斤信封)和 `<result>` 信封只有一个人,所以.. `res.status`编号 :`res.headers` 没有 字段;
-   由其中之一约束的名称(`const r = await call`, (中文(简体) ), `const { data: d } = await call`, (中文(简体) ), `const d = (await call).data`)为 后接相邻函数内的名称 包含类似函数,所以 `useEffect` 还算回调;
-   `holder.<field>`, (中文(简体) ), `holder.data.<field>`, (中文(简体) ), `holder.data['<field>']` 财务报告和审定财务报表 `holder['<field>']` 读取对象的每个密钥 持有人或 `<holder>.data`· ;
-   (单位:千美元) `let` 持有者(在读前重新指定),一个计算出的密钥 (单位:千美元)`d[key]`),和一个JavaScript成员(`data.map`, (中文(简体) ), `data.length`, (中文(简体) ), `status`从未读过;
-   在电话的OWN信封上打开的分行(`ok`, (中文(简体) ), `status`改为: 并且只有故障臂被放下: 失败分支读取( e)`res.data?.detail`)是服务器的错误 信封,从不成功. `if (res.ok)`, (中文(简体) ), `if (res.ok === true)`, (中文(简体) ), `if (res.status >= 400)`, (中文(简体) ), `> 399`, (中文(简体) ), `!== 200`, (中文(简体) ), `!== 201`, (中文(简体) ), `< 400`, (中文(简体) ), `=== 200`, (中文(简体) ), `<= 299` 联合国 `!` 否定所有决定 哪个手臂运行, 故成功之臂能持诵- `if (res.ok) setItems(res.data. items)` 恰恰是空地隐藏的形状。 一个大院 条件(`!res.ok || res.status >= 500`),比较此通过 无法读取( n)`>= Math.min(400, limit)`)和a 数据 `statusText` 测试是 无法辨认,所以NEITHER臂被收集. 一个三胞胎是同一个守卫 a 一个 `if` —— 说 `res.ok ? res.data.items : res.data?.detail` 留着 成功之臂——在其它任何事物上的三分之一——根本不是警卫: 武器是普通的成功之路 - 读。 早归后看书 (单位:千美元)`if (!res.ok) { throw … }` ...然后代码)照常收集;
-   读取的字是 `||` 编号 : `??` 链带链的 索引,所以检查判断链 作为一个决定是: `res.data?.invoice_id || res.data?.invoice?.id` 默默无声 模式声明 `invoice_id`,因为 `invoice` 它的防御力 倒计时。 连锁店里不申报任何操作.

`gateforge check` 对比这些读取的反应模式 加入后端路由声明并发送一个 **无阻断** `RESPONSE_FIELD_MISSING_FROM_MODEL` 每个未申报的领域提供咨询。 一个电话 没有人消费任何属性,所以它保持字节相同 从前.

### 扫描范围(可选、严格、可逆)

所有范围界定密钥均为 OPTIONAL;没有这些密钥的配置将精确扫描为 (字节相同) 它们的存在是因为测试机密码是 不同的合同类: 共享已配置符号的 e2e 助手 名称已扫描为产品前端消耗(类型阻塞器加 和模拟测试机匹配 服务器路由正则ex, 生成虚假 `http.endpoint` 资源.

-   `clientScanRoots` ——再生-相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相相相相接相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 客户呼叫扫描 (单位:千美元)`fetch`/ Axios, 配置的符号, 包装器, 构建器) 仅适用于 以匹配文件; 外部生成文件 **没有客户调用的事实和没有 未解决的条目** (他们仍然参与导入分辨率,所以) 从根外导入常数 解决).
-   `serverScanRoots` ——再生-相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相相相相接相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 通用服务器路由 扫描(Express/Fastify/Hano注册和NestJS控制器) 仅适用于匹配文件; 外部文件不会生成服务器路由 事实。 已报告 `scannedPaths` 无论哪种方式,保险都保持不变—— 范围界定缩小了事实,而不是涵盖范围.

偶数范围界定`include`编号 :`exclude` 编号 `clientSymbols`, (中文(简体) ), `wrapperFunctions`,或 `urlBuilders` 条目; 保留纯字符串条目 unscoped)以-从来不放松-上层根作曲. 这个 优先是决定:

1.  **上层根门先**: 外部文件 `clientScanRoots` 完全不产生任何客户调用的事实,无论任何符号 范围界定 `serverScanRoots` 和服务器路径.
2.  **`include` 下一个**: 如果一个条目声明 `include`,文件必须 匹配至少一个平面( 缺席) `include` =每个入室文件.
3.  **`exclude` 胜过 `include`**: 两者命名的文件已退出 该条目的范围.

所造成的后果,一直审慎地记录下来:

-   调用配置声明的名称, 在外部的文件中 名称为声明范围( e2e) `api(...)` 帮助者),是 **忽略** —— 说 既未解决也未受阻。 未申报的包装证据规则 仍然屏蔽任何配置从未提及的名称 .
-   已配置的构建器或包装器从一个文件中直接显示 解决这里。 如果附上的呼叫仍然在范围之内(例如: `fetch` 目标使用了构建器,该调用失败 键入未解决的条目——它从未默默地消失.
-   服务器路由分解是范围意识:客户端符号所在 对文件不活动 , `api.get('/x', handler)`\- 形状代码是自由的 作为路由器注册被发现.

错误的文档仍然被关闭: 非对象根, 非动词 包装方法,无定义条目 `name`,则非阵列 `include`编号 :`exclude` 数值抛出。 未知的密钥和未知的组合键 与以前一样被忽略(未改变的剖面姿态).

## 资源

**无.** 路线是证据,不是商业资源:早期设计 发射一个 `http-route` 资源,但路径来源资源 名称与同位相交的 SQLAlchemy 表格相交 平面合格 id, 因此资源通道在红色检测后被移除 (单位:千美元)`resources: []` 总是; 后续设计见 ARD0004 D1 —— 端点身份存在于 `@gate-forge/http-contract` 加入,永远不要加入 路径生成的表格名称).

## 信号

**无.** 之前的设计设计定了一个代码阳性 `exposure` 每个信号 文物(包装) `route`编号 :`frontend-call`+) 加上 (中文(简体) ) `lifecycle.<op>` 信号 从HTTP方法(POSTX&Create,GET/HEAD⇒read,PUT/PATCH⇒update, 德莱特·德莱特; `app.all` 说 " 无 " ) **路径来源资源名称** ——最后一个非空非参数路径 区段,小写,扩展脱去(`/api/accounts/:id` → `accounts`) (中文(简体) ). 该目标是一个猜测:在真实的重置中,它大多是名字没有 已发现资源( 路由) `/absences` vs 表单 `employee_absences`),以及 每个薄荷信号都浮出水面 `STALE_SIGNAL_TARGET` 屏蔽时 没有添加信息——未知曝光已默认 `user-facing` 和已启用的未知寿命周期操作(ADR 0003 D5), 因此去除猜想会改变任何分类结果.

后果,不断深思熟虑:

-   **Route-资源链接是 CLI 端点编译器的专属工作** (ADR0004):它获得相同的候选名称,只有在准确的 一个发现的商业资源匹配和一个计划符号或 处理器名称的事实可以证实它(这包放在 `http.contract` ,并发出已输入的 `ENDPOINT_RESOURCE_LINK_UNRESOLVED` 用于模糊的块。 名称 仅靠巧合是无法联系的.
-   删除信号保存默认值: 保持曝光 `user-facing`, (中文(简体) ), 每次生命周期操作都允许(cred:/ 持久性:义务) 生成通过 `lifecycleAllowsContract` 删除 语义学在模型包证明之前一直被屏蔽.
-   科雷尔 `STALE_SIGNAL_TARGET` 检测到的残留 真正停滞 权威信号(声明标记、适配器绑定、只读) ——这包已经不再产生虚假的目标.
-   弹包 **任何地方都没有负面证据** (无只记录的负数) 证明,没有"没有找到就意味着内部"),从不写分类.

## 设置

```yaml
# .gateforge.yml
plugins:
  - id: gateforge.pack-http
    version: 0.1.0
    transport: in-process
    module: '@gate-forge/pack-http'
```

包还发出 `http.contract` 证据事实(每个服务器一个) 用于端点编译器加盟的文物和每个前端呼叫站点的1个 (ADR0004 D1)——唯物证,永无商业资源.

需要节点 QQ 20; 任何时间都没有网络 .

## 常见问题

### @gate-forge/pack-http 是什么？

通用HTTP曝光包:用于路由注册的TS检测器\(Express, Fastify, Hono, NestJS\),用于前端API-客户呼叫的受限静态数据流\(fetch, Axios, 例, 包装器, 常数, URL 构建器\), http\.contract evidence facts pluser

### 如何安装 @gate-forge/pack-http？

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

### @gate-forge/pack-http 支持 TypeScript 吗？

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

### @gate-forge/pack-http 支持 ESM 还是 CommonJS？

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

### @gate-forge/pack-http 需要什么版本的 Node\.js？

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

### @gate-forge/pack-http 可以商用吗？

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

### @gate-forge/pack-http 的下载量有多少？

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

### @gate-forge/pack-http 还在维护吗？

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

