跳转至

架构预设 / 功能矩阵

交互式的 fastkit init --interactive 在收集功能选择之前,会先询问一个 架构预设(issue #44)。预设决定了生成项目的整体布局 —— 不同的预设会使用不同的基础模板,并把生成的配置文件落到不同位置,使其与已有结构相邻,而不是放进平行的 src/config/ 子树中。

本页是关于「每个预设的作用、文件落地位置、哪些功能组合需要手动接入」的权威说明。

预设 → 基础模板

预设 基础模板 描述
minimal fastapi-empty 最小可运行的 FastAPI 应用 —— 占位的 main.py 会根据您的功能选择重新生成。
single-module fastapi-single-module 单文件 FastAPI 应用 —— main.py 会被重新生成。
classic-layered fastapi-default 分层布局(api/routes、crud、schemas、core)。自带的 main.py 会被保留。
domain-starter fastapi-domain-starter 领域驱动布局(src/app/domains/<concept>/)。自带的 main.py 会被保留。推荐默认选项。

生成文件的落地位置

预设 main.py 覆盖策略 数据库配置落点 认证配置落点
minimal 在 src/main.py 处重新生成 src/config/database.py src/config/auth.py
single-module 在 src/main.py 处重新生成 src/config/database.py src/config/auth.py
classic-layered 保留(模板自带) src/core/database.py src/core/auth.py
domain-starter 保留(模板自带) src/app/core/database.py src/app/core/auth.py

各预设对数据库 / 认证功能的支持

下列功能在所有预设中都支持 —— 包安装都会成功;差别只在于动态的 main.py 覆盖是否会自动接入它们。

功能 minimal / single-module classic-layered / domain-starter
数据库(PostgreSQL、MySQL、SQLite、MongoDB) 生成配置模块,并且在重新生成的 main.py 中插入 await init_db() 调用。 在预设对应路径生成配置模块。自带的 main.py 会保留,因此需要手动把 get_db() 接入路由器。
认证(JWT、FastAPI-Users、OAuth2、基于会话) 生成认证配置模块;JWT 会导入 HTTPBearer,OAuth2 与基于会话的认证还会添加各自的 main.py 中间件配置。 在预设对应路径生成认证配置模块。不会向 main.py 添加 import —— 需要手动接入依赖。
后台任务(Celery、Dramatiq) 生成 worker.py 与 features/tasks.py,并在重新生成的 main.py 中挂载任务路由器。 生成 worker.py 与 features/tasks.py,但自带的 main.py 会保留 —— 需要手动挂载路由器。
缓存(Redis) 生成 features/cache.py,并在重新生成的 main.py 中挂载并初始化。 生成 features/cache.py;需要手动挂载。
工具类:分页 / WebSocket 生成 features/pagination.py / features/websocket.py,并在重新生成的 main.py 中挂载路由器。 生成相同的模块;需要手动挂载。
监控:OpenTelemetry 不生成独立文件 —— 追踪配置直接加入重新生成的 main.py。 不生成独立文件。自带的 main.py 会保留,因此追踪不会被接入 —— 需要手动添加配置。
迁移(Alembic) 只要选择了任意 SQL 数据库,就会生成 alembic.ini、alembic/env.py、一个基线修订版本和 scripts/migrate.sh —— 与 main.py 覆盖无关。 同上 —— Alembic 的生成不取决于 main.py 是否被保留。
工具链(ruff、pre-commit、github-actions、devcontainer、makefile) 生成对应的配置文件,与 main.py 覆盖无关。 同上。
日志(structured) 生成 logging_config.py,并把 request-id 中间件接入重新生成的 main.py。 生成 logging_config.py;自带的 main.py 会保留,因此需要手动接入该中间件。
CORS(工具类) 在重新生成的 main.py 中加入 CORSMiddleware,allow_origins=['*']。 自带的 main.py 中已接入(以 settings.all_cors_origins 作为条件)。只需在 .env 中设置 BACKEND_CORS_ORIGINS 即可启用 —— 无需修改代码。
测试(基础 / 覆盖率 / 进阶) 在项目根生成 pytest.ini;进阶级别还会添加 tests/factories.py 与 tests/test_factories.py。 同上。
部署(Docker、docker-compose) 在项目根写入 Dockerfile 和/或 docker-compose.yml。 同上。
/health / /ready 重新生成的 main.py 中始终包含。 保留下来的模板自带 main.py 中已经包含。

何时会出现「Preset compatibility」警告

对于保留自带 main.py 的预设(classic-layered、domain-starter),某些功能选择不会被自动接入到应用。CLI 会在生成结束时一次性给出警告,列出哪些选择需要手动接入:

选择的功能 在 classic-layered / domain-starter 下是否触发警告?
CORS(工具类) ❌ —— 自带的 main.py 已接入。只需在 .env 中填好 BACKEND_CORS_ORIGINS。
Rate-Limiting(工具类) ✅ —— 不会加入 slowapi 限流器的初始化
Pagination / WebSocket(工具类) ✅ —— 生成的路由器(features/pagination.py / features/websocket.py)不会被挂载
Celery / Dramatiq(async_tasks) ✅ —— 生成的 worker.py / features/tasks.py 路由器不会被挂载
Redis(缓存) ✅ —— 生成的 features/cache.py 不会被挂载或初始化
Prometheus / OpenTelemetry(监控) ✅ —— 不会向 main.py 添加监控埋点配置
structured(日志) ✅ —— 会生成 logging_config.py,但不会向 main.py 添加 request-id 中间件
Alembic(迁移)、tooling 选择 ❌ —— 这些文件无论预设如何都会生成且可直接使用;不依赖 main.py
任意数据库 / 认证选择 ⚠️ —— 配置文件已生成,但需要您手动在路由器中通过 Depends() 接入

对 minimal 与 single-module 预设,动态的 main.py 覆盖会自动处理上述所有方面,因此不会触发警告。

不支持的组合(安全起见)

策略设计者刻意不会尝试把生成的代码拼接进模板自带的 main.py。这样做有可能产生坏掉的 import 或重复的路由器。整体契约是:

  • 所选的包总是会被安装(这样 pip freeze 与用户意图匹配)。
  • 生成的配置模块总是落到对应预设的路径。
  • 对于保留 main 的预设,会告知用户哪些选择仍需手动接入,而不是产出悄无声息坏掉的代码。

如果您需要对所有功能都进行自动接入,请选择 minimal 或 single-module —— 它们会基于功能开关重新生成 main.py。