跳转至

模板质量保障

FastAPI-fastkit 提供了完善的自动化模板校验,确保所有模板在不同环境与包管理器下都保持高质量且可正常工作。

多层质量保障

FastAPI-fastkit 同时使用两套互补的质量保障系统:

1. 静态模板检查

对模板结构与语法的每周自动校验

2. 动态模板测试

包含真实项目创建的完整端到端测试

自动化的每周检查

每周三午夜(UTC),我们的 GitHub Actions 工作流会自动检查所有 FastAPI 模板,确保它们达到质量标准:

  • ✅ 文件结构校验 —— 确保所有必备文件与目录都存在
  • ✅ 文件扩展名核对 —— 确认模板文件使用正确的 .py-tpl 扩展名
  • ✅ 依赖检查 —— 确认 FastAPI 及必要依赖被正确声明
  • ✅ FastAPI 实现 —— 确认模板包含合规的 FastAPI 应用初始化
  • ✅ 测试执行 —— 运行模板的测试以确认功能正常
  • ✅ 冒烟测试 —— 用 uvicorn 启动生成的项目,并探测其 HTTP 接口
  • ✅ 配置一致性 —— Python 版本固定、依赖漂移、自我依赖
  • ✅ 占位符残留 —— 项目生成后不残留任何 <placeholder>
  • ✅ 依赖新鲜度 —— 对落后于 PyPI 最新发布版本的固定版本发出警告

各项检查的作用

检查会从模板生成一个真实的项目 —— 复制、转换 -tpl、注入元数据 —— 然后针对这个生成的项目而不是模板源码运行每一项检查。只读取模板的检查无法发现生成过程中未能替换的占位符。

冒烟测试

生成的项目会在一个空闲端口上用 uvicorn 启动,检查器会持续轮询,直到服务器响应或超时。服务器启动后,会请求 /docs 与 /health 并检查其状态码。随后终止服务器进程,如果它没有停止,则升级为 SIGKILL。

uvicorn 的目标按以下顺序解析:生成的 pyproject.toml 中的 [tool.fastapi-fastkit].app_module,然后是模板 template-config.yml 中的 app_module,最后是约定俗成的 main.py 位置。这与 fastkit runserver 使用的契约相同,因此冒烟测试能够启动的模板,其生成的项目也能够运行。

这项检查能发现静态分析发现不了的问题:只在运行时才解析的 import、会抛出异常的 lifespan、没有默认值的配置字段。

配置一致性

会针对模板的 pyproject.toml-tpl 验证三件事:

  • Python 版本固定保持一致并以 3.12 为目标 —— requires-python、black 的 target-version 与 mypy 的 python_version。一个声明 >=3.12 却按 py311 格式化的模板,就是一个迟早会坑到贡献者的 bug。
  • 没有依赖漂移 —— requirements.txt-tpl 与 [project].dependencies 中声明的包不得相互冲突。模板为了兼容各种包管理器会同时附带这两个文件,而两份列表如果没有检查,总会逐渐偏离。
  • 没有自我依赖 —— 生成的项目不得将 FastAPI-fastkit 声明为运行时依赖。该 CLI 是开发工具;把它打包进每个生成的应用,会把整个 fastkit 依赖树带入无关的项目。

占位符残留

每个 <project_name>、<description> 及同类占位符都必须在生成过程中被替换。生成的项目中仍然存在任何 <placeholder> 都会被视为错误 —— 这意味着元数据注入不知道那个文件,用户会原样收到它。

依赖新鲜度

固定的版本会与 PyPI 上的最新发布版本进行比较,并以警告而非错误的形式报告 —— 一个落后一个小版本的模板只是一条信息,而不是一次失败。这是唯一一项会访问网络的检查,--offline 会跳过它。

自动化模板测试系统

FastAPI-fastkit 自带一套革新性的自动化测试系统,对每个模板进行完整校验:

动态模板发现

测试系统会自动发现所有模板,无需手动配置:

# Test all templates automatically
$ pytest tests/test_templates/test_all_templates.py -v

# Results show all discovered templates
PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-default]
PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-async-crud]
PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-dockerized]
PASSED tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-psql-orm]

全面的测试覆盖

每个模板都会经历完整的端到端测试:

✅ 项目创建过程

  • 模板复制与文件转换
  • 项目元数据注入(名称、作者、描述)
  • 文件结构校验

✅ 包管理器兼容性

  • UV(默认):基于 Rust 的高速包管理器
  • PDM:现代 Python 依赖管理工具
  • Poetry:成熟的依赖管理工具
  • PIP:传统的 Python 包管理器

✅ 虚拟环境管理

  • 为每种包管理器创建对应环境
  • 校验依赖安装
  • 处理包管理器特有的工作流

✅ 依赖解析

  • 生成 pyproject.toml(UV、PDM、Poetry)
  • 生成 requirements.txt(PIP)
  • 元数据合规(PEP 621)
  • 构建系统配置

✅ 项目结构校验

  • FastAPI 项目识别
  • 必备文件存在性
  • 目录结构核对

测试执行示例

运行全部模板测试:

$ pytest tests/test_templates/test_all_templates.py -v

测试指定模板:

$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[fastapi-default] -v

在 PDM 环境中运行测试:

$ pdm run pytest tests/test_templates/test_all_templates.py -v

持续集成

自动化测试系统在 CI/CD 流水线中运行:

  • ✅ Pull Request 校验:每个 PR 都会测试受影响的模板
  • ✅ 每日夜间测试:对完整模板套件进行校验
  • ✅ 包管理器测试:覆盖所有包管理器的交叉校验
  • ✅ 环境测试:覆盖多个 Python 版本与平台

对贡献者的好处

零配置测试:

  • 🚀 添加新模板 → 自动测试
  • ⚡ 无需手动创建测试文件
  • 🛡️ 一致的质量标准

全面覆盖:

  • 🔍 端到端项目创建测试
  • 📦 多包管理器校验
  • 🏗️ 完整的依赖解析测试
  • ✅ 模拟真实使用场景

开发体验:

  • 🎯 专注模板内容:测试由系统自动完成
  • 🔄 即时反馈:测试执行迅速
  • 📊 结果清晰:报告信息详尽
  • 🚫 零样板代码:无需任何测试配置

手动模板检查

为开发与调试之便,您可以通过本地检查脚本或 Makefile 命令手动检查模板:

直接使用检查脚本

# Inspect all templates
$ python scripts/inspect-templates.py

# Inspect specific templates
$ python scripts/inspect-templates.py --templates fastapi-default,fastapi-async-crud

# Verbose output with detailed information
$ python scripts/inspect-templates.py --verbose

# Save results to custom file
$ python scripts/inspect-templates.py --output my_results.json

检查选项

选项 作用 适用场景
--offline 跳过所有网络查询(依赖新鲜度报告) 没有网络,或者想要快速、封闭的运行
--no-smoke 跳过用 uvicorn 启动生成的项目 只在迭代结构;冒烟测试是最慢的步骤
--mypy 用 mypy 对生成的项目进行类型检查 提交模板之前 —— 由于速度较慢,需要显式开启
--templates 要检查的模板列表,以逗号分隔 只处理一个模板时
--verbose 详细输出 调试失败时
--output JSON 结果文件的路径 需要并排保留多次运行结果时

针对单个模板的快速本地循环:

$ python scripts/inspect-templates.py \
    --templates fastapi-sqlmodel --offline --no-smoke --verbose

……以及提交 PR 之前的完整检查:

$ python scripts/inspect-templates.py --templates fastapi-sqlmodel --mypy

使用 Makefile 命令

# Inspect all templates
$ make inspect-templates

# Inspect with verbose output
$ make inspect-templates-verbose

# Inspect specific templates
$ make inspect-template TEMPLATES="fastapi-default,fastapi-async-crud"

检查结果

  • 成功的检查会被记录在工作流输出与产物中
  • 失败的检查会自动创建 GitHub issue,附带详细的错误报告
  • 检查历史在 GitHub Actions 产物中保留 30 天

理解检查输出

运行模板检查时,您会看到类似输出:

📋 Found 6 templates to inspect: fastapi-async-crud, fastapi-custom-response, fastapi-default, fastapi-dockerized, fastapi-empty, fastapi-psql-orm
============================================================
🔍 Inspecting template: fastapi-async-crud
   Path: /path/to/src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud
✅ fastapi-async-crud: PASSED
----------------------------------------
🔍 Inspecting template: fastapi-custom-response
   Path: /path/to/src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response
✅ fastapi-custom-response: PASSED
----------------------------------------
...
============================================================
📊 INSPECTION SUMMARY
   Total templates: 6
   ✅ Passed: 6
   ❌ Failed: 0
🎉 All templates passed inspection!
📄 Results saved to: template_inspection_results.json

模板要求

要让模板通过检查,必须满足以下要求:

文件结构

  • 必须包含一个带 Python 源文件的 src/ 目录
  • Python 文件必须使用 .py-tpl 扩展名
  • 必须包含 tests/ 目录与 README.md-tpl 文件
  • 必须包含 pyproject.toml-tpl(PEP 621)。内置模板以 pyproject 为先,不再附带 setup.py-tpl;检查仍然接受该文件,以便第三方模板继续可用,但新模板不得添加它。
  • 当 pyproject.toml-tpl 已声明 [project].dependencies 时,requirements.txt-tpl 为可选 —— 但如果两者同时存在,它们必须保持一致(参见配置一致性)
  • 必须统一以 Python 3.12 为目标:requires-python = ">=3.12"、black 的 target-version = ["py312"]、mypy 的 python_version = "3.12",以及任何 Docker 基础镜像都使用 python:3.12-slim
  • 不得将 FastAPI-fastkit 声明为运行时依赖
  • 生成后不得留下任何未替换的 <placeholder>

FastAPI 要求

  • 必须包含 FastAPI 应用初始化
  • 必须在以下至少一个位置把 fastapi 声明为依赖:pyproject.toml-tpl 的 [project].dependencies、requirements.txt-tpl,或 setup.py-tpl 的 install_requires
  • 所有模板文件必须具有有效的 Python 语法

身份标识

模板应携带 FastAPI-fastkit 的身份标识,这样生成的项目在用户工作区中可以与无关的 FastAPI 项目区分开:

  • pyproject.toml-tpl —— 在 description 中带 [FastAPI-fastkit templated] 前缀,并提供带 managed = true 的 [tool.fastapi-fastkit] 表。
  • setup.py-tpl —— 在 setup() 的 description 参数中带 [FastAPI-fastkit templated] 前缀。

is_fastkit_project() 接受其中任一标识(pyproject 优先,setup.py 是遗留回退;匹配不区分大小写)。即使模板遗漏了它们,元数据注入也能确保生成的项目带上这些标识。

质量标准

  • 所有模板文件必须语法正确
  • 依赖必须正确声明
  • 模板结构必须遵循 FastAPI-fastkit 的约定

这套自动化的质量保障可以让所有模板保持可靠,并随时可用于生产。