scaffold-interceptor
Add or wire cross-cutting FastAPI/gRPC interceptors or middleware, preferring ArchiPy's. Use for "add middleware", "request ID/logging/auth interceptor", or "gRPC interceptor".
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- scaffold-interceptor
- description
- Add or wire cross-cutting FastAPI/gRPC interceptors or middleware, preferring ArchiPy's. Use for "add middleware", "request ID/logging/auth interceptor", or "gRPC interceptor".
03 SKILL.md 正文
Scaffold ArchiPy Interceptor
Scope
Only helpers/interceptors/. Do not create utils or decorators here.
Read first
Read these plugin rules in full before generating files (paths relative to this skill directory; Claude Code: ${CLAUDE_SKILL_DIR}/../../rules/):
../../rules/using-archipy-interceptors.mdc
Before writing files
- Inspect app bootstrap, existing interceptors/middleware, DI wiring, and the installed ArchiPy version.
- Infer framework and sync/async style from the repository.
- Ask only for an unresolved cross-cutting concern or framework choice. Prefer an ArchiPy interceptor whenever it fits.
- Preserve existing registration order and modules; do not overwrite.
Prefer ArchiPy
Check archipy.helpers.interceptors (FastAPI / gRPC). Prefer AppUtils auto-registration for stock interceptors. Show
registration via DI or framework APIs from docs / ../archipy-docs/reference/helpers.md (Interceptors), resolved relative to
this SKILL.md's directory in the plugin installation — not the app workspace.
Custom interceptor
Create under helpers/interceptors/ — FastAPI middleware sketch:
from __future__ import annotations
import logging
import time
import uuid
from collections.abc import Awaitable, Callable
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import Response
logger = logging.getLogger(__name__)
class RequestIdMiddleware(BaseHTTPMiddleware):
"""Attach/propagate an X-Request-ID header — cross-cutting only."""
async def dispatch(
self,
request: Request,
call_next: Callable[[Request], Awaitable[Response]],
) -> Response:
request_id = request.headers.get("x-request-id") or str(uuid.uuid4())
started = time.perf_counter()
response = await call_next(request)
response.headers["X-Request-ID"] = request_id
logger.debug(
"request_id=%s method=%s path=%s status=%s duration_ms=%.2f",
request_id,
request.method,
request.url.path,
response.status_code,
(time.perf_counter() - started) * 1000,
)
return response
- No domain business writes
- No adapter construction inside the interceptor module
- Wire through
configs/containers.py,AppUtils, or framework middleware registration - Map errors at the boundary; do not leak raw exceptions
Do not
- Keep cross-cutting only — no domain use-case logic, no domain business writes.
- Do not create utils or decorators in this step.
Verify
Run formatter/linter and Behave scenarios through the AppUtils-built app (/scaffold-bdd harness) for ordering,
success, and mapped failure behavior. Confirm registration
occurs once. Report the reused ArchiPy API or files created, plus commands run.
Docs
- https://syntaxarc.github.io/ArchiPy/tutorials/helpers/
- https://syntaxarc.github.io/ArchiPy/tutorials/observability/
- Bundled skill reference:
../archipy-docs/reference/helpers.md(Interceptors section)
04 同仓库更多 Skills
scaffold-utils
Add or wire pure helpers/utils, preferring ArchiPy utils (datetime, JWT, password, file, string). Use for "add a helper/util function", "format dates", "hash passwords", or "generate tokens".
scaffold-service
Scaffold a thin FastAPI router or gRPC servicer under services/{domain}/v{n}/ with AppUtils bootstrap. Use for "add an endpoint/route/API", "expose via REST/gRPC", or "new API version".
scaffold-observability
Configure ArchiPy 5.x OpenTelemetry traces, metrics, logs, and instrumentation. Use for "add tracing/metrics/OTel", "Prometheus/Pushgateway", or migrating off Sentry, Elastic APM, or old Prometheus.
scaffold-models
Scaffold ArchiPy models under models/: domain/repository DTOs, errors, optional entities and types. Use for "add DTO/schema/request/response model", "new error type", or "SQLAlchemy entity".
scaffold-logic
Scaffold an ArchiPy logic (use case) under logics/{domain}/ with a unit-of-work decorator and DTO I/O. Use for "add business logic", "new use case", "transactional operation", or "service layer method".
scaffold-health-checks
Scaffold FastAPI/gRPC liveness, readiness, and startup health checks, graceful shutdown, and optional Kubernetes probes. Use for "health endpoint", "readiness/liveness probe", or "k8s probes".