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

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

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

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

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

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

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

## 中文简介

框架中立的Canonic HTTP合同: HttpContFact schema,打出块码,路径/方法正常化,定型前端调用 <->服务器-路由连接引擎(ADR0004 D1-D4).

## 安装

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

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

## README

# @gate-forge/http-contract (中文(简体) )

Gateforge(ADR 0004)框架中立罐装HTTP合同: 严格 `HttpContractFact` 计划、 类型结果代码、 犬科 路径/方法正常化,以及决定性的前端呼号 服务器路由加入引擎.

此软件包拥有 **无框架解析** (检测包拥有它)和 **无分类** (单位:千美元)`@gate-forge/core` 拥有它。 每次输出都是纯的 函数; 相同的输入在任何输入下产生字节相同的产出 相会相会.

## 合同事实

一个发现的HTTP表面 被探测器包串联成 GPP/3类资源 `http.contract` (仅凭证据;从未分类) 直接,从不是一种商业资源:

```ts
interface HttpContractFact {
  schemaVersion: 1;
  role: 'server-route' | 'frontend-call';
  method: 'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS'|'ANY';
  normalizedPath: string;   // canonical positional form
  rawPath: string;          // exactly as written in source
  framework: string;        // 'fastapi' | 'fetch' | 'axios' | ...
  handlerSymbol?: string;   // server routes
  requestSchemaSymbols?: string[];
  responseSchemaSymbols?: string[];
  callsites?: string[];     // frontend calls
  source: { file: string; line: number; col: number };
}
```

## 服装规范化(ADR 0004 D2)

`normalizeHttpPath` 条形查询/断裂、倒塌和转换 `${expr}` 和快速API `{name}` 编号 : `{name:type}` 改为 `{}`, (中文(简体) ), `{name:path}` 转换器和 `*` 包罗万象 `{*}`绝对 URL 仅用于配置的同源主机。 参数名称是 **永远** 编 一个身份。 无法解析的形状返回 `HTTP_PATH_DYNAMIC` 从来没有 猜对了.

`normalizeHttpMethod` 大写混凝土动词和返回 `null` 页:1 动态方法(呼叫器必须发出) `HTTP_METHOD_DYNAMIC`; 默认为 `GET` ”).

## 联合引擎( ADR 0004 D3, 第3相升优先级)

`joinFrontendCalls(routes, calls)` 执行完全一个要点: 等效方法, 等分数, 前端的位置匹配 `{}` 匹配任何单一路线段和路线 `{*}` 匹配一个或 更多后端部分.

候选人在一号之前按质量进行分配 检查( c)**绝对优先**: 匹配为 _字义_ 当它耗尽的时候,没有 位档通俗性——每个位置都是精确的分段等同,计有: 路径 `{}` 被电话所映射 `{}` - 和 _参数_ 否则 (路线) `{}` 吸收一个呼叫字面,一个呼叫 `{}` 放松到一个路径 字面,或任何 `{*}` 吸收;通配符永远不是字面意思). 若为 任何字面匹配都存在,它们都是 " 候选人 " ; 仅限参数匹配 只有在零字形匹配存在时才考虑.

为什么: 路由器在参数化的路由段之前先解析字面路径段 运行时间(包括快速API),所以 `/messages/search` 永远无法到达 `/messages/{}` 与 `id="search"`。静态组合镜像运行时间 truth: 模板调用 `/messages/${id}` 加入 `/messages/{}` 尽管 字形的兄弟姐妹,一个字形的叫法会加入字形的路线.

零比对 – `FRONTEND_ROUTE_UNWIRED`; 不止一个不同的存活 候选人(任一级别) `FRONTEND_ROUTE_AMBIGUOUS`没有 得分和无先入为胜 超出记录分区。 复制 相同的路线倒入一个端口 携带每一个源.

## 常见问题

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

框架中立的Canonic HTTP合同: HttpContFact schema,打出块码,路径/方法正常化,定型前端调用 \<-\>服务器-路由连接引擎\(ADR0004 D1-D4\)\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

