@gate-forge/http-contract

中文文档
0.19.2发布于 2026/11/10Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 2977

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

中文使用文档
文档目录3 节
  1. 合同事实
  2. 服装规范化(ADR 0004 D2)
  3. 联合引擎( ADR 0004 D3, 第3相升优先级)

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

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

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

合同事实

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

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 共发布 46 个版本,首次发布于 2026/09/17;过去 12 个月发布了 46 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.2latest2026/11/105 天前
0.19.12026/11/106 天前
0.19.02026/10/2917 天前
0.18.32026/10/2522 天前
0.18.22026/10/2125 天前
0.18.12026/10/2125 天前

关于 @gate-forge/http-contract 的常见问题

@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 和提交记录判断。