跳转至

FastAPI 模板创建指南

为 FastAPI-fastkit 添加新 FastAPI 项目模板的完整指南。

🎯 总览

添加新模板分为 5 个步骤:

  1. 📋 规划与设计 —— 明确模板用途与结构
  2. 🏗️ 模板实现 —— 创建必需的结构与文件
  3. 🔍 本地校验 —— 用 inspector 校验模板
  4. 📚 文档 —— 编写 README 与使用指南
  5. 🚀 提交与评审 —— 创建 PR 并由社区评审

📋 第 1 步:规划与设计

明确模板用途

在创建新模板之前,请回答以下问题:

  • 该模板的独特价值是什么?
  • 它与现有模板的差异在哪里?
  • 目标用户群体是谁?
  • 会包含怎样的技术栈?

模板命名规范

fastapi-{purpose}-{stack}

示例:

  • fastapi-microservice(微服务模板)
  • fastapi-graphql(GraphQL 集成模板)
  • fastapi-auth-jwt(JWT 认证模板)

技术栈规划

事先定义好要包含的主要技术:

# Example: fastapi-microservice template
core_dependencies:
  - fastapi
  - uvicorn
  - pydantic
  - pydantic-settings

additional_features:
  - sqlalchemy (ORM)
  - alembic (migrations)
  - redis (caching)
  - celery (background tasks)
  - pytest (testing)

development_tools:
  - black (code formatting)
  - isort (import sorting)
  - mypy (type checking)
  - pre-commit (Git hooks)

🏗️ 第 2 步:模板实现

必需的目录结构

fastapi-{template-name}/
├── src/                          # Application source code
│   ├── main.py-tpl              # ✅ FastAPI app entry point (required)
│   ├── __init__.py-tpl
│   ├── api/                     # API routers
│   │   ├── __init__.py-tpl
│   │   ├── api.py-tpl           # Main API router
│   │   └── routes/              # Individual routes
│   │       ├── __init__.py-tpl
│   │       └── items.py-tpl     # Example route
│   ├── core/                    # Core configuration
│   │   ├── __init__.py-tpl
│   │   └── config.py-tpl        # Settings management
│   ├── crud/                    # CRUD logic
│   │   ├── __init__.py-tpl
│   │   └── items.py-tpl
│   ├── schemas/                 # Pydantic models
│   │   ├── __init__.py-tpl
│   │   └── items.py-tpl
│   └── utils/                   # Utility functions
│       ├── __init__.py-tpl
│       └── helpers.py-tpl
├── tests/                       # ✅ Tests (required)
│   ├── __init__.py-tpl
│   ├── conftest.py-tpl         # pytest configuration
│   └── test_items.py-tpl       # Example tests
├── scripts/                     # Scripts
│   ├── format.sh-tpl           # Code formatting
│   ├── lint.sh-tpl             # Linting
│   ├── run-server.sh-tpl       # Server execution
│   └── test.sh-tpl             # Test execution
├── pyproject.toml-tpl           # ✅ Primary metadata (PEP 621, required)
├── requirements.txt-tpl         # 🟡 Optional when pyproject declares deps
├── setup.cfg-tpl               # Development tools configuration
├── README.md-tpl               # ✅ Project documentation (required)
├── .env-tpl                    # Environment variables template
└── .gitignore-tpl              # Git ignore file

最少必备文件。 一个模板至少要提供:

  • tests/ 目录
  • README.md-tpl
  • pyproject.toml-tpl(PEP 621)
  • 在 pyproject.toml-tpl 的 [project].dependencies 或 requirements.txt-tpl 中声明 fastapi 依赖

当 pyproject.toml-tpl 已声明 [project].dependencies 时,requirements.txt-tpl 不是必需的 —— 但如果模板同时附带两者,它们必须保持一致:两者之间存在依赖漂移时检查会失败。

新模板以 pyproject 为先,不得附带 setup.py-tpl。截至 v1.4.0,没有任何内置模板包含该文件。检查仍然接受该文件,以便仓库外的模板继续可用,但这是一条遗留路径。

统一以 Python 3.12 为目标:requires-python = ">=3.12"、black 的 target-version = ["py312"]、mypy 的 python_version = "3.12",以及任何 Docker 基础镜像都使用 python:3.12-slim。检查会确认这三处固定版本保持一致。

切勿将 FastAPI-fastkit 声明为生成项目的运行时依赖。该 CLI 是开发工具;模板的依赖列表只应包含生成的应用本身会导入的内容。

文件编写指南

1. 编写 main.py-tpl

"""
FastAPI application entry point

This file is the main application for the <project_name> project created with FastAPI-fastkit.
"""
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from api.api import api_router
from core.config import settings

# Create FastAPI app (required for inspector validation)
app = FastAPI(
    title="<project_name>",
    description="Project created with FastAPI-fastkit",
    version="1.0.0",
)

# CORS middleware configuration
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Register API router
app.include_router(api_router, prefix="/api/v1")

@app.get("/")
async def root():
    """Root endpoint"""
    return {"message": "Hello from <project_name>!"}

@app.get("/health")
async def health_check():
    """Health check endpoint"""
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

2. 编写 pyproject.toml-tpl(推荐)

新模板应使用 PEP 621 的 pyproject.toml-tpl 来声明元数据与依赖。该文件至少要有一个 [project] 段,内含 name、version、description,以及包含 fastapi 的 dependencies 列表。模板还必须携带两个 FastAPI-fastkit 身份标识,这样 is_fastkit_project() 才能在用户工作区中把生成的项目与无关的 FastAPI 项目区分开:

  • 在 description 中带 [FastAPI-fastkit templated] 前缀
  • 专门提供 [tool.fastapi-fastkit] 表,并设置 managed = true

识别时只需任一标识匹配即可(不区分大小写)。若模板遗漏了它们,元数据注入会在项目生成时自动补上,但作者应当显式包含它们。

[project]
name = "<project_name>"
version = "0.1.0"
description = "[FastAPI-fastkit templated] <description>"
authors = [
    {name = "<author>", email = "<author_email>"},
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.34.0",
    "pydantic>=2.10.0",
    "pydantic-settings>=2.7.0",
    "python-dotenv>=1.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "httpx>=0.28.0",
]

[tool.fastapi-fastkit]
managed = true

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

3. 编写 requirements.txt-tpl(可选)

当 pyproject.toml-tpl 已经声明 [project].dependencies 时为可选。对于偏好纯 pip 工作流的模板,仍然有用。

# FastAPI core dependencies (required)
fastapi==0.104.1
uvicorn[standard]==0.24.0

# Data validation
pydantic==2.5.0
pydantic-settings==2.1.0

# Environment variable management
python-dotenv==1.0.0

# Database (if needed)
sqlalchemy==2.0.23
alembic==1.13.0

# Development tools
pytest==7.4.3
pytest-asyncio==0.21.1
httpx==0.25.2

# Code quality
black==23.11.0
isort==5.12.0
mypy==1.7.1

4. 路由锚点

附带 main.py-tpl 或 API 聚合模块的模板,应当标记出 fastkit addroute 插入代码的位置:

from src.app.api import health

# fastkit:imports

api_router = APIRouter()
api_router.include_router(health.router)

# fastkit:routes

如果没有这些锚点,addroute 会退回到基于 AST 的插入方式,自行定位 import 块和路由注册位置 —— 因此缺少锚点的模板仍然可以工作,但结果的可预测性较差。编辑这些文件时请保留这些注释。

5. 编写测试文件

# tests/test_items.py-tpl
"""
Items API test module
"""
import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_root():
    """Test root endpoint"""
    response = client.get("/")
    assert response.status_code == 200
    assert "message" in response.json()

def test_health_check():
    """Test health check"""
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "healthy"}

def test_create_item():
    """Test item creation"""
    item_data = {
        "name": "Test Item",
        "description": "Test Description"
    }
    response = client.post("/api/v1/items/", json=item_data)
    assert response.status_code == 200
    data = response.json()
    assert data["name"] == item_data["name"]
    assert data["description"] == item_data["description"]

def test_read_items():
    """Test reading items list"""
    response = client.get("/api/v1/items/")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

🔍 第 3 步:本地校验

运行自动校验脚本

新模板准备好后,用以下命令进行校验:

# Validate all templates
make inspect-templates

# Validate specific template only
make inspect-template TEMPLATES="fastapi-your-template"

# Validate with verbose output
python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose

# Fast local loop: no network, no server boot
python scripts/inspect-templates.py --templates "fastapi-your-template" \
    --offline --no-smoke

# Full check before opening a PR (adds mypy over the generated project)
python scripts/inspect-templates.py --templates "fastapi-your-template" --mypy

--offline 会跳过 PyPI 依赖新鲜度查询,--no-smoke 会跳过启动生成项目(最慢的步骤),--mypy 会对生成项目进行类型检查。每项检查具体做什么,请参阅 模板质量保障。

Note

您提交 PR 后,Template PR Inspection 工作流会自动运行并校验您的模板改动,反馈会直接出现在 PR 上。

校验清单

inspector 会自动校验以下项目:

✅ 文件结构校验

  • [ ] 存在 tests/ 目录
  • [ ] 存在 README.md-tpl 文件
  • [ ] 存在 pyproject.toml-tpl(新模板中不包含 setup.py-tpl)

✅ 文件扩展名校验

  • [ ] 所有 Python 文件使用 .py-tpl 扩展名
  • [ ] 不存在 .py 扩展名的文件

✅ 依赖校验

  • [ ] fastapi 至少声明于以下其一:
    • [ ] pyproject.toml-tpl 的 [project].dependencies(推荐)
    • [ ] requirements.txt-tpl
  • [ ] requirements.txt-tpl 与 [project].dependencies 不存在冲突
  • [ ] FastAPI-fastkit 不是运行时依赖

✅ FastAPI 实现校验

  • [ ] main.py-tpl 中存在 FastAPI 的 import
  • [ ] main.py-tpl 中存在形如 app = FastAPI() 的应用创建

✅ 测试执行校验

  • [ ] 成功创建虚拟环境
  • [ ] 成功安装依赖
  • [ ] 所有 pytest 测试通过

✅ 冒烟测试

  • [ ] 生成的项目可以在 uvicorn 下启动
  • [ ] /docs 有响应
  • [ ] /health 有响应

uvicorn 的目标依次从生成的 pyproject.toml 中的 [tool.fastapi-fastkit].app_module、template-config.yml 中的 app_module,以及约定俗成的 main.py 位置解析得到。

✅ 配置一致性

  • [ ] requires-python、black 的 target-version 与 mypy 的 python_version 都指向 Python 3.12
  • [ ] requirements.txt-tpl 与 [project].dependencies 之间不存在依赖漂移
  • [ ] 不存在对 FastAPI-fastkit 的自我依赖

✅ 占位符残留

  • [ ] 项目生成后不残留任何 <placeholder>

✅ 自动化模板测试

FastAPI-fastkit 自带自动化模板测试,会对所有模板执行完整测试:

测试覆盖范围:

  • ✅ 模板创建过程
  • ✅ 项目元数据注入
  • ✅ 虚拟环境搭建
  • ✅ 依赖安装(覆盖所有包管理器)
  • ✅ 基本项目结构校验
  • ✅ FastAPI 项目识别

测试执行:

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

# Test specific template
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v

模板测试自动发现: 新模板会被自动发现并测试,无需手动配置:

  1. ✅ 零配置:加入模板即可自动测试
  2. ✅ 一致的测试:对所有模板使用相同的质量标准
  3. ✅ 多种包管理器:覆盖 UV、PDM、Poetry 与 PIP
  4. ✅ 全面校验:结构、元数据与功能性都会检查

这对您意味着什么:

  • 🚀 FastAPI-fastkit 主源码中无需新增测试:您的模板会被自动测试
  • ⚡ 开发更快:专注模板内容,而不是测试配置
  • 🛡️ 质量保证:所有模板拥有一致的测试体验
  • 🔄 CI/CD 集成:Pull Request 中自动测试

仍需手动测试的内容:

  • 🧪 模板特有的功能:业务逻辑与定制特性
  • 🔧 集成测试:外部服务与复杂工作流
  • 📱 端到端场景:完整的用户流程

测试最佳实践:

# 1. Test your template locally
$ fastkit startdemo your-template-name

# 2. Run automated tests
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v

# 3. Test with different package managers
$ fastkit startdemo your-template-name --package-manager poetry
$ fastkit startdemo your-template-name --package-manager pdm
$ fastkit startdemo your-template-name --package-manager uv

手动校验清单

在自动校验之外,还要手动检查以下项:

🔧 代码质量

  • [ ] 代码遵循 PEP 8 风格指南
  • [ ] 合理使用类型注解
  • [ ] 变量与函数命名有意义
  • [ ] 注释与 docstring 得当

🏗️ 架构

  • [ ] 关注点分离(API、业务逻辑、数据访问相互独立)
  • [ ] 组件设计可复用
  • [ ] 结构便于扩展
  • [ ] 落实安全最佳实践

📚 文档

  • [ ] README.md-tpl 遵循 PROJECT_README_TEMPLATE.md 的格式
  • [ ] 明确说明安装与运行方式
  • [ ] 提供 API 文档(OpenAPI / Swagger)
  • [ ] 解释环境变量

📚 第 4 步:文档

编写 README.md-tpl

参照 PROJECT_README_TEMPLATE.md 指南编写。

编写模板说明文档

在 src/fastapi_fastkit/fastapi_project_template/README.md 中加入对新模板的说明:

## fastapi-your-template

Write a brief description and use cases for your new template here.

### Features:
- Feature 1
- Feature 2
- Feature 3

### Use Cases:
- Use case 1
- Use case 2

🚀 第 5 步:提交与评审

创建 PR 前的清单

  • [ ] 全部自动校验通过(make inspect-templates)
  • [ ] 完成代码格式化(make format)
  • [ ] 静态检查通过(make lint)
  • [ ] 所有测试通过(make test)
  • [ ] 文档已完成
  • [ ] 遵循 CONTRIBUTING.md 的规范

PR 标题与描述

[TEMPLATE] Add fastapi-{template-name} template

## Overview
Adds a new {purpose} template.

## Key Features
- Feature 1
- Feature 2
- Feature 3

## Validation Results
- [ ] Inspector validation passed
- [ ] All tests passed
- [ ] Documentation completed

## Usage Example
\```bash
fastkit startdemo
# Select template: fastapi-{template-name}
\```

## Related Issues
Closes #issue-number

评审流程

  1. 自动校验:GitHub Actions 自动校验模板
    • Template PR Inspection:对修改模板的 PR 运行 inspect-changed-templates.py
    • Weekly Inspection:每周三对所有模板进行完整校验
  2. 代码评审:维护者与社区评审代码
  3. 测试:在不同环境中测试模板
  4. 文档评审:核对文档的准确性与完整性
  5. 批准与合并:所有要求满足后合并到 main 分支

Note

您会自动收到带有校验结果的 PR 评论。在请求评审前先确认这些结果!

🎯 最佳实践

安全考量

  • 用环境变量管理敏感信息
  • 合理配置 CORS
  • 校验输入数据
  • 预防 SQL 注入

性能优化

  • 善用异步处理
  • 优化数据库查询
  • 合理的缓存策略
  • 配置响应压缩

可维护性

  • 代码结构清晰
  • 测试覆盖全面
  • 文档详尽
  • 配置日志与监控

🆘 需要帮助?

为 FastAPI-fastkit 社区添加新模板是非常宝贵的贡献。 您的创意与付出会对其他开发者大有帮助!🚀