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

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

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

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

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

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

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

## 中文简介

FastAPI服务器-路由探测器:Python AST扫描仪在GPP/3(pack-sqlalchemy模式)上服务,排放http. Contract 证据事实,带有犬类有效路径外加曝光/生命周期信号(ADR0004 D1,计划阶段2).

## 安装

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

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

## README

# @ gate-forge/ pack-fastapi – FastAPI 服务器路由检测器

Python- AST 探测器( 仅限 Stdlib, 不导入应用程序, 不执行, 不网络) 在GPP/3上服务,使用包-sqlalchemy双层结构(ADR 0002): 进程内 TypeScript 包件将生成 SME 硬化的蟒蛇插件 子进程传输运行,所以一个检测器执行既服务于两个.

## 发现什么

-   `FastAPI()` 应用程序实例和 `APIRouter(prefix="…")` 路由器为 **字义** 前缀; 计算出一个已键入的前缀 `FASTAPI_PREFIX_UNRESOLVED` 输入(阻塞)——从不猜测.
-   路由装饰器`@app.get`, (中文(简体) ), `@router.post`, (中文(简体) ), `@router.api_route( methods=[...])`,同步和 `async` 处理器) **字义** 路径; 计算路径流出 `HTTP_PATH_DYNAMIC`。 。 。 .
-   交叉文件挂载树 : `include_router(...)` 有文字上的前缀, 通过扫描文件导入(绝对和相对)解决,包括 导入异名路由器名称( i)`from .routers import router as r`谁 路由合并到定义路由器和模块导入属性 链 (`from api.v1 import endpoints` + 键 `endpoints.health.router`) (中文(简体) ). 重复挂载每个挂载一个事实。 无法解决或含糊不清 目标/别称,包括周期 `FASTAPI_PREFIX_UNRESOLVED`。 。 。 .
-   包属性导入 : `from pkg import attr` 地点 `pkg/attr.py` 不存在决定 `attr` 通过包 `__init__.py` 模块级绑定——任务(`router = APIRouter()`或一个 进口再出口(`from .endpoints import router`),后续行动至8起 跳起来。 模糊度保持输入 `FASTAPI_PREFIX_UNRESOLVED` 输入.
-   **书记官处职能** (中央-登记模式):一个函数 他们的身体呼唤 `include_router` 它本身的参数之一—— `def register_all_routers(app): app.include_router(r, prefix=...)` —— 说 包括重新连接到任何呼叫站点参数名 (详情见下文).
-   被支持的集外的动词(例如). `@router.trace`发射 `HTTP_METHOD_DYNAMIC` - 没有什么会悄悄地消失的.
-   事实上,处理器符号, `isAsync`, (中文(简体) ), `response_model`,请求计划 符号(非原始、非路径参数说明), `tags`, (中文(简体) ), `operationId`,以及 `mountProvenance` (单位:千美元)`include-chain` | `standalone`) (中文(简体) ).
-   **登记令** (0.14):探测器可以放置的每一个端点 静静地在应用程序的平整注册序列中 `registration: {scope, order}` —— 说 `scope` 命名应用程序 (单位:千美元)`module:var`, (中文(简体) ), `order` 是其基于 0 的立场: 包括呼叫命令 跨路由器, 在一个路由器内的装饰源顺序( Starlette) 匹配注册顺序中的路由,所以最小顺序是 服务路线。 由顶层调用的一次性登记功能 应用所有者模块在PLACE的扩展: 函数体顶级包含完全像所写命令的顺序 (呼叫现场位置,功能内声明顺序). 失败 关闭: 路由器后附加的路由器 `include_router` 调用 在同一文件中,在函数体内声明,可从 不止一个应用程序,或通过登记功能安装的应用程序包括: 这不能确定订单(第二个呼叫站点,一个呼叫嵌入 语句、外国模块呼叫、链式帮助跳或包含 窝入 `if`编号 :`for`编号 :`while`编号 :`try`编号 :`with`编号 :`match`载 否 `registration` 命令- 不确定的块被跳过, 而相对 可证明路线的顺序保持不变。 输入路径 原始路径字符串中的转换器(`{n:int}`, (中文(简体) ), `{p:path}`(组数) `typedPathParams: true` - 路线比它窄 犬槽形状.

## 配置 : `.gateforge/fastapi.json`

可选, JSON 仅从 repo 根读取(与 数据包 `.gateforge/http-clients.json`: **没有是正常的, 错误的文档抛出 .**

```json
{ "importRoots": ["backend"] }
```

`importRoots` 列表 repo-root- relat- relative 目录 aBSOLUTE进口的进口根-中央路由-登记模式 在一个模块中记录一切 (单位:千美元)`from api.v1.endpoints import activities` 编号 : `app.include_router(activities.router, prefix="/api/v1")`) (中文(简体) ). 有根头 已配置 :

-   `from api.v1.endpoints import activities` 绑定扫描文件 `<importRoot>/api/v1/endpoints/activities.py` (或其一揽子) `__init__.py`因此,登记包括决心和有效路径 它们的正前缀( 以`/api/v1/activities/{id}`) (中文(简体) ).
-   `from api.v1 import activities` + 键 `activities.router` (进口) 名称是模块)和更深的链条 (单位:千美元)`from api.v1 import endpoints` + 键 `endpoints.health.router`决心 通过相同的根.
-   **独一无二是强制性的**: 一个比一个更匹配的点化模块 扫描到根部的文件是输入的阻塞 `FASTAPI_PREFIX_UNRESOLVED` 指定冲突文件的条目 - 从不猜测。 输入解析到无任何扫描的状态 未解决如常( 关闭世界: 没有隐藏扫描孔) 。 有根头 配置的绝对导入后缀 heuristic 已禁用( 说明 根法则);相对进口和其他一切没有变化.
-   没有配置文件, 检测器的行为与以前完全相同 .

过程内包装器将根传递到蟒蛇扫描仪上作为 明确 `--import-roots <json-array>` argv 旗; 子进程 运输可以直接通过同一种旗帜.

## 书记官处的职能: `include_router` 通过函数参数

真正的后端经常在一个函数内注册每个路由器 (单位:千美元)`backend/router_registry.py`:

```python
def register_all_routers(app):        # app is a PARAMETER
    app.include_router(activities_router, prefix="/api/v1/activities")
    ...                                # × 79 includes

# server.py
fastapi_app = FastAPI(...)
register_all_routers(fastapi_app)     # module-level call site
```

没有程序间支持, 参数会打破挂载图 行走: 路由器被证明包含在内( 因此从独立处被压制) 然而,ZERO的终点却有所贡献。 探测器关闭了缺口, 有限度和决定性的:

-   **收藏**: 身体呼唤的顶级功能 `include_router` 在它自己的一个参数中收集这些参数包括: 由参数键入的边值( 已计为 附加顶级函数;仅位置参数——呼叫站点 固定位置).
-   **物质化**: 这种函数的每个调用站点,其论据 誓以决心 `FastAPI()`编号 :`APIRouter()` 实例变量—— a 同文件任务(模块级别) **或者说** 工厂-当地: `def create_app(): app = FastAPI(); register(app)` 工作是因为 本地实例被行走) 或导入绑定到另一个扫描器 file 实例 —— 作为普通的边 包括在该边 举个例子 证据不变: `include-chain` 包含 调用自己的源地址; 重复调用站点 , 就像写作一样.
-   **链条**: 登记函数可能将其参数传递给另一个 帮助( e)`def create_app(app): register_all_routers(app)`最多为 **8个帮助跳** (单位:千美元)`MAX_RESOLUTION_DEPTH`) (中文(简体) ). 超限链 生成一个键入的未解决条目,命名需要的函数 hop 9——没有静音滴出,没有猜测.
-   **有序扩展** (登记令):当一个呼叫站点 完全可以证明——该功能是一个简单的模块级别 `def`, (中文(简体) ), 用顶级表达式在扫描组中精确调用一次 模块的语句 `FastAPI()` 参数—— 扩展加入该模块在呼叫站点的语句顺序 每个函数体 TOP 级别 `include_router` 语句命令像 写入包含(函数内部的报表顺序断开链接). 其它的都关不上了 哪里都有第二个呼叫站点 呼叫嵌入到语句或其他表达式中, 来自 a 应用程序所有者以外的模块,链式帮助跳,以及任何 包括嵌入 `if`编号 :`for`编号 :`while`编号 :`try`编号 :`with`编号 :`match` 挂载 无 `registration` (事实不变). 顺序- 不确定的块是 跳过,所以可证明路线的相对顺序仍然正确.
-   **无法解析的参数** (无已知实例的名称,或 计算表达式: 诚实的结果是输入的 `FASTAPI_PREFIX_UNRESOLVED` 输入确切的呼叫地点和 **没有 排放量** ——路由器被证明包含在某个地方,他们的 源带前缀,所以前缀无独立路径会 伪造路线 永远的注册函数不会挂起任何 保持缄默( 封闭世界 : 没有隐藏扫描孔, 没有挂载 ) 发明). 一个参数名称阴影同一文件实例变量 仅保留模块级读取(不重复排放).

## 可证明的前缀和路由器

-   **附加说明的定义是定义.** `router: APIRouter = APIRouter(prefix="/api/v1")` 索引完全一样 `router = APIRouter(prefix="/api/v1")`,包括前缀。 (它曾经被忽略, 在路由器自己的前缀上发布 无输入结果。 )
-   **恒定前缀折叠.** 模块级字符串的前缀 常数 - `API = "/api/v1"` 与 `APIRouter(prefix=API)` **或者说** `app.include_router(router, prefix=API)` 来源可以证明, 因此,路线保持了它的真实路径。 一个f-string,一个属性,或者一个呼叫 真实计算: 路由器生成一个键入 `FASTAPI_PREFIX_UNRESOLVED` 输入时没有发布路径.
-   **由未建模的表达式所构建的路由器对象** (单位:千美元)`router = build_router()`,下标,属性)有一个未知的前缀,所以 其路线报告为: `FASTAPI_PREFIX_UNRESOLVED` 名称 变量 —— 绝不是任何应用程序服务的无前缀路径 .
-   **`FASTAPI_ROUTER_UNMOUNTED`。 。 。 .** 没有扫描的路由器 `include_router` 没有扫描应用程序为目标服务。 它的路线保持 他们的单独排放(所申报的前缀是扫描所知道的), 和一个输入的条目名称 路由器、其文件和每个已声明 路径,所以" `/api/v1` 前缀没有被应用 ” 从来不是答案 当真正的一个是"没有挂载这个路由器"时. 仅在 扫描组显示的是应用程序,没有无法解决的包括; 带部分扫描,或包含扫描无法跟踪,包 什么也不能证明.

## 输出模型(ADR 0004 D1)

一个 `http.contract` 每个资源(有效挂载路径、混凝土) 页:1 这些是 **仅限证据**: 引擎自有图排除 (无路线/表格相撞)和 端点编译器结合前端调用的事实 (单位:千美元)`@gate-forge/http-contract`) (中文(简体) ). TypeScript 包装器填充了词条 `normalizedPath` - (单一概念化实施) 和薄荷 **无分类信号** (狗粮补救) 阶段4:较早 `exposure: route` 编号 : `lifecycle.*` 信号是 以路径生成的商业名称为对象的猜测,即: 未发现资源( e)`/admin-bypasses` vs 真实的表格),生成 `STALE_SIGNAL_TARGET` 屏蔽器, 无添加, 因为未知 曝光默认值 `user-facing` 和未知生命周期操作默认值 启用( ADR 0003 D5) 。 路线-资源连接属于CLI 端点编译器,用于对照 计划符号( s)`requestSchemaSymbols`编号 :`responseSchemaSymbols`和 处理者的名字 这些事实携带, 和阻断模糊 与类型 `ENDPOINT_RESOURCE_LINK_UNRESOLVED`核心项目 `STALE_SIGNAL_TARGET` 检测仍为真正陈旧的权威信号(声明) 标记、适配器绑定、只读声明).

## 反应式电线名称

每个服务器程序的事实都包含 `attributes.responseModelFields`: 有线 命名其响应模式的答案, 按声明顺序排列—— 每个 pydantic 字段名称加每个 `Field(alias=...)` 它宣布,包括田地 它继承了扫描组也证明的基类。 这个模型是 装饰者 `response_model=` 当它宣布一个和处理者 返回非注解( FastAPI 本身的默认), 并带有容器 FastAPI 解开已解开 : `list[InvoiceOut]`, (中文(简体) ), `Optional[MoneyOut]` 财务报告和审定财务报表 `MoneyOut | None` 全部报告元素模型.

`detail` 总是名称之一: FastAPI 以 `{"detail": ...}` (单位:千美元) `HTTPException`或一个 `detail` 列表(请求) 前端读取 `detail` 无法报告错误 (原始内容存档于2018-06-21). exactly of a dropped support-model field.

属性是 **缺席** 只要电线名称不是静态的 可计算,绝不是部分:

-   模型配置化名生成( e)`model_config = ConfigDict(...)` 或 pydantic v1 键 `class Config`——每个名字都不同;
-   a. 扫描组外的基类——继承的字段未知;
-   一个不是一种模型的形状 : `dict`两个模型的结合,a 计算注释,完全没有注释.

现有 `responseModel` 属性保持其先前的确切含义 (只有装饰者声明)和它的上一个字节;返回 注释是一个新的事实, 从来没有改变旧的.

`gateforge check` 对照前端的字段检查这些名称 实际读取( `@gate-forge/pack-http` 作为 `responseReads`(中文(简体) ) 并发出一个 **无阻断** `RESPONSE_FIELD_MISSING_FROM_MODEL` 每个字段的咨询 端点、字段、前端文件和行以及模型名称 已经宣布了。 一个字段以它自己的名字计算,另一个以它的名字计算 案件样式( e)`due_date` ≡ `dueDate`)或用宣布的别名。 A 类 其路径未声明可证明的响应模式未产生 咨询及同字节报告.

## 设置

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

要求节点 ++ 20和 `python3` 有关PATH的QQ 3.11;没有任何网络 点.

子进程传输(等同):

```yaml
plugins:
  - id: gateforge.pack-fastapi
    version: 0.1.0
    transport: subprocess
    command: ['python3', '-m', 'gateforge_fastapi_detector']
# with PYTHONPATH=<pack>/python:<plugin-protocol>/python
```

## 常见问题

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

FastAPI服务器-路由探测器:Python AST扫描仪在GPP/3\(pack-sqlalchemy模式\)上服务,排放http\. Contract 证据事实,带有犬类有效路径外加曝光/生命周期信号\(ADR0004 D1,计划阶段2\)\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

