模板质量保障
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::TestAllTemplates::test_template_creation[fastapi-default] -v
在 PDM 环境中运行测试:
持续集成
自动化测试系统在 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 结果文件的路径 | 需要并排保留多次运行结果时 |
针对单个模板的快速本地循环:
……以及提交 PR 之前的完整检查:
使用 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 的约定
这套自动化的质量保障可以让所有模板保持可靠,并随时可用于生产。