@gate-forge/pack-fastapi

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

FastAPI server-route detector: Python AST scanner served over GPP/3 (pack-sqlalchemy pattern), emitting http.contract evidence facts with canonical effective paths plus exposure/lifecycle signals (ADR 0004 D1, plan phase 2).

原始使用文档
文档目录7 节
  1. What it finds
  2. Configuration: .gateforge/fastapi.json
  3. Registry functions: include_router through a function param…
  4. Prefixes that are provable, and routers nothing mounts
  5. Output model (ADR 0004 D1)
  6. Response-model wire names
  7. Setup

@gate-forge/pack-fastapi — FastAPI server-route detector

Python-AST detector (stdlib only, no app import, no execution, no network) served over GPP/3 using the pack-sqlalchemy two-tier structure (ADR 0002): the in-process TypeScript wrapper spawns the SAME hardened python plugin the subprocess transport runs, so one detector implementation serves both.

What it finds

  • FastAPI() app instances and APIRouter(prefix="…") routers with literal prefixes; computed prefixes emit a typed FASTAPI_PREFIX_UNRESOLVED entry (blocking) — never a guess.
  • Route decorators (@app.get, @router.post, @router.api_route( methods=[...]), sync and async handlers) with literal paths; computed paths emit HTTP_PATH_DYNAMIC.
  • Cross-file mount trees: include_router(...) with literal prefixes, resolved through scanned-file imports (absolute and relative), including import-aliased router names (from .routers import router as r) whose routes merge into the defining router, and module-import attribute chains (from api.v1 import endpoints + endpoints.health.router). Repeated mounts yield one fact per mount. Unresolvable or ambiguous targets/aliases and include cycles emit FASTAPI_PREFIX_UNRESOLVED.
  • Package-attribute imports: from pkg import attr where pkg/attr.py does not exist resolves attr through the package's __init__.py module-level bindings — an assignment (router = APIRouter()) or an import re-export (from .endpoints import router), followed up to 8 hops. Ambiguity stays a typed FASTAPI_PREFIX_UNRESOLVED entry.
  • Registry functions (the central-registrar pattern): a function whose body calls include_router on one of its own parameters — def register_all_routers(app): app.include_router(r, prefix=...) — has those includes rewired onto whatever the call-site argument names (details below).
  • Verbs outside the supported set (e.g. @router.trace) emit HTTP_METHOD_DYNAMIC — nothing disappears silently.
  • Per fact: handler symbol, isAsync, response_model, request schema symbols (non-primitive, non-path parameter annotations), tags, operationId, and mountProvenance (include-chain | standalone).
  • Registration order (0.14): every endpoint the detector can place statically in an app's flattened registration sequence carries registration: {scope, order} — scope names the app (module:var), order is its 0-based position: include call order across routers, decorator source order within one router (Starlette matches routes in registration order, so the smallest order IS the serving route). A once-called registry function called by a top-level statement of the app-owner module expands IN PLACE: its function-body top-level includes order exactly like written includes (call-site position, statement order inside the function). Fail closed: a route appended to its router after an include_router call in the same file, declared inside a function body, reachable from more than one app, or mounted through a registry-function include that is not order-certain (a second call site, a call nested in a statement, a foreign-module call, a chained helper hop, or an include nested in if/for/while/try/with/match) carries NO registration — order-uncertain blocks are skipped, and the relative order of the provable routes stays correct. A typed path convertor in the raw path string ({n:int}, {p:path}) sets typedPathParams: true — the route matches narrower than its canonical slot shape.

Configuration: .gateforge/fastapi.json

Optional, JSON-only, read from the repo root (same precedent as pack-http's .gateforge/http-clients.json): absence is normal, malformed documents throw.

{ "importRoots": ["backend"] }

importRoots lists repo-root-relative directories that act as Python import roots for ABSOLUTE imports — the central-router-registry pattern where one module registers everything (from api.v1.endpoints import activities / app.include_router(activities.router, prefix="/api/v1")). With roots configured:

  • from api.v1.endpoints import activities binds the scanned file <importRoot>/api/v1/endpoints/activities.py (or its package __init__.py), so registry includes resolve and effective paths carry their real prefixes (/api/v1/activities/{id}).
  • from api.v1 import activities + activities.router (the imported name is the module) and deeper chains (from api.v1 import endpoints + endpoints.health.router) resolve through the same roots.
  • Uniqueness is mandatory: a dotted module matching MORE THAN ONE scanned file across the roots is a typed blocking FASTAPI_PREFIX_UNRESOLVED entry that names the conflicting files — never a guess. Imports resolving to nothing scanned stay typed- unresolved as usual (closed world: no scan hole is hidden). With roots configured the absolute-import suffix heuristic is disabled (explicit roots govern); relative imports and everything else are unchanged.
  • Without the config file the detector behaves exactly as before.

The in-process wrapper passes the roots to the python scanner as an explicit --import-roots <json-array> argv flag; the subprocess transport can pass the same flag directly.

Registry functions: include_router through a function parameter

Real backends often register every router inside one function (backend/router_registry.py):

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

Without interprocedural support the parameter breaks the mount-graph walk: the routers are provably included (so suppressed from standalone emission) yet contribute ZERO endpoints. The detector closes that gap, bounded and deterministic:

  • Collection: a top-level function whose body calls include_router on one of its own parameters collects those include edges keyed by the parameter (nested functions count for the enclosing top-level function; positional parameters only — call sites bind positionally).
  • Materialization: every call site of such a function whose argument resolves to a known FastAPI()/APIRouter() instance variable — a same-file assignment (module-level or factory-local: def create_app(): app = FastAPI(); register(app) works because the local instance is walked) or an import binding to another scanned file's instance — receives the edges as ordinary includes on that instance. Provenance is unchanged: include-chain at the include call's own source location; repeated call sites duplicate mounts, exactly like written includes.
  • Chaining: a registry function may pass its parameter to another helper (def create_app(app): register_all_routers(app)) up to 8 helper hops (MAX_RESOLUTION_DEPTH). Chains beyond the bound yield one typed unresolved entry naming the function that would need hop 9 — no silent drop, no guess.
  • Order-certain expansion (registration order): when ONE call site is provable in full — the function is a plain module-level def, called exactly once across the scanned set, by a top-level expression statement of the module that owns the FastAPI() argument — the expansion joins that module's statement order at the call site, and each function-body TOP-LEVEL include_router statement orders like a written include (statement order inside the function breaks ties). Everything else stays fail closed: a second call site anywhere, a call nested in a statement or another expression, a call from a module other than the app owner's, a chained helper hop, and any include nested in if/for/while/try/with/match mount without registration (facts unchanged). Order-uncertain blocks are skipped, so the relative order of the provable routes stays correct.
  • Unresolvable arguments (a name bound to no known instance, or a computed expression): the honest outcome is a typed FASTAPI_PREFIX_UNRESOLVED entry at the exact call site and no emission — the routers are provably included somewhere and their source carries prefixes, so prefix-less standalone paths would fabricate routes. A never-called registry function mounts nothing and stays silent (closed world: no scan hole is hidden, and no mount is invented). A parameter name shadowing a same-file instance variable keeps the module-level reading only (no double emission).

Prefixes that are provable, and routers nothing mounts

  • Annotated definitions are definitions. router: APIRouter = APIRouter(prefix="/api/v1") is indexed exactly like router = APIRouter(prefix="/api/v1"), prefix included. (It used to be ignored, and every route behind it was published at the router's own prefix with no typed outcome.)
  • Constant prefixes fold. A prefix that is a module-level string constant — API = "/api/v1" with APIRouter(prefix=API) or app.include_router(router, prefix=API) — is provable from the source, so the route keeps its real path. An f-string, an attribute, or a call is genuinely computed: the router yields a typed FASTAPI_PREFIX_UNRESOLVED entry and no route is emitted.
  • A router object built by an unmodeled expression (router = build_router(), a subscript, an attribute) has an unknown prefix, so its routes are reported as FASTAPI_PREFIX_UNRESOLVED naming the variable — never as prefix-less paths that no app serves.
  • FASTAPI_ROUTER_UNMOUNTED. A router that no scanned include_router targets is served by no scanned app. Its routes keep their standalone emission (the declared prefix is all the scan knows), and one typed entry names the router, its file and every declared route, so "the /api/v1 prefix was not applied" is never the answer when the real one is "nothing mounts this router". Reported only when the scanned set shows an application and has no unresolvable include; with a partial scan, or an include the scan cannot follow, the pack says nothing it cannot prove.

Output model (ADR 0004 D1)

One http.contract resource per (effective mounted path, concrete method). These are evidence-only: the engine-owned graph excludes them from business classification (no route/table collision) and the endpoint compiler joins them against frontend-call facts (@gate-forge/http-contract). The TypeScript wrapper fills the canonical normalizedPath (single canonicalization implementation across languages) and mints no classification signals (dogfood remediation phase 4): the earlier exposure: route / lifecycle.* signals were targeted at the path-derived business name — a guess that mostly names no discovered resource (/admin-bypasses vs the real table), producing STALE_SIGNAL_TARGET blockers while adding nothing, since unknown exposure defaults user-facing and unknown lifecycle operations default enabled (ADR 0003 D5). Route→resource linkage belongs to the CLI endpoint compiler, which corroborates the candidate name against the schema symbols (requestSchemaSymbols/responseSchemaSymbols) and handler names these very facts carry, and blocks ambiguity with typed ENDPOINT_RESOURCE_LINK_UNRESOLVED. Core's STALE_SIGNAL_TARGET detection remains for genuinely stale authority signals (declaration markers, adapter bindings, read-only declarations).

Response-model wire names

Each server-route fact carries attributes.responseModelFields: the wire names its response model answers to, in declaration order — every pydantic field name plus every Field(alias=...) it declares, including the fields it inherits from a base class the scanned set also proves. The model is the decorator's response_model= when it declares one and the handler's return annotation otherwise (FastAPI's own default), with the containers FastAPI unwraps peeled off: list[InvoiceOut], Optional[MoneyOut] and MoneyOut | None all report the element model.

detail is always among the names: FastAPI answers a failed request with {"detail": ...} (an HTTPException) or a detail list (request validation), so a frontend reading detail to report an error is never evidence of a dropped success-model field.

The attribute is absent whenever the wire names are not statically computable, never partial:

  • a model configuring alias generation (model_config = ConfigDict(...) or a pydantic v1 class Config) — every name differs;
  • a base class outside the scanned set — inherited fields unknown;
  • a shape that is not one model: dict, a union of two models, a computed annotation, no annotation at all.

The existing responseModel attribute keeps its exact previous meaning (the decorator declaration only) and its exact previous bytes; a return annotation is a new fact, never a change of the old one.

gateforge check cross-checks these names against the fields a frontend actually reads (reported by @gate-forge/pack-http as responseReads) and emits one non-blocking RESPONSE_FIELD_MISSING_FROM_MODEL advisory per field a joined endpoint's model does not declare — naming the endpoint, the field, the frontend file and line, and the names the model does declare. A field counts as present under its own name, under the other case style (due_date ≡ dueDate) or under a declared alias. A repository whose routes declare no provable response model produces no advisory and a byte-identical report.

Setup

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

Requires Node >= 20 and python3 >= 3.11 on PATH; no network at any point.

Subprocess transport (equivalent):

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 共发布 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/pack-fastapi 的常见问题

@gate-forge/pack-fastapi 是什么?

FastAPI server-route detector: Python AST scanner served over GPP/3 (pack-sqlalchemy pattern), emitting http.contract evidence facts with canonical effective paths plus exposure/lifecycle signals (ADR 0004 D1, plan phase 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 和提交记录判断。