使用模板

FastAPI-fastkit 提供了一组预构建项目模板,帮助您按不同技术栈快速起步。

可用的模板

使用 list-templates 命令查看可用模板:

$ fastkit list-templates
                      Available Templates
┌─────────────────────────┬───────────────────────────────────┐
│ fastapi-custom-response │ Async Item Management API with    │
│                         │ Custom Response System            │
│ fastapi-dockerized      │ Dockerized FastAPI Item           │
│                         │ Management API                    │
│ fastapi-empty           │ No description                    │
│ fastapi-async-crud      │ Async Item Management API Server  │
│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
│                         │ Management API with PostgreSQL    │
│ fastapi-default         │ Simple FastAPI Project            │
└─────────────────────────┴───────────────────────────────────┘

模板说明

1. `fastapi-default`

简单的 FastAPI 项目

包含必要功能的基础 FastAPI 配置
基于 mock 数据的 item 管理
适合学习与简单 API
内置基本的 CRUD 操作

适合:

FastAPI 新手
简单的 Web API
学习与原型开发

2. `fastapi-async-crud`

异步 Item 管理 API 服务

完全异步的 FastAPI 应用
基于 async/await 的进阶 CRUD 操作
I/O 操作性能更好
基于 mock 数据的异步模式

适合:

高性能应用
I/O 密集型操作
现代异步 Python 开发

3. `fastapi-custom-response`

带自定义响应系统的异步 Item 管理 API

自定义响应模型与格式化
进阶的错误处理
支持分页
自定义 HTTP 状态码与响应

适合:

需要特定响应格式的 API
复杂的错误处理需求
在响应中加入自定义业务逻辑

4. `fastapi-dockerized`

已容器化的 FastAPI Item 管理 API

完整的 Docker 容器化
面向生产的部署配置
多阶段 Docker 构建
基于环境变量的配置

适合:

生产部署
容器化环境
DevOps 与 CI/CD 管道

5. `fastapi-psql-orm`

集成 PostgreSQL 的已容器化 FastAPI Item 管理 API

集成 PostgreSQL 数据库
使用 SQLAlchemy ORM 与 Alembic 迁移
通过 Docker Compose 支持本地开发
完整的基于数据库的 CRUD 操作

适合:

数据驱动的应用
生产级数据存储
复杂的数据关系

6. `fastapi-empty`

极简 FastAPI 项目

极简的 FastAPI 配置
不预置任何功能
适合从零开始定制开发

适合:

从零开始
依赖最少
自定义架构需求

基于模板创建项目

使用 startdemo 命令基于模板创建项目:

$ fastkit startdemo
Enter the project name: my-blog-api
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: Blog API with PostgreSQL

Available Templates:
           fastapi-default
┌─────────────┬──────────────────────┐
│ Description │ Simple FastAPI       │
│             │ Project              │
│ Stack       │ FastAPI, Uvicorn     │
│ Database    │ Mock Data            │
│ Features    │ Basic CRUD           │
└─────────────┴──────────────────────┘

           fastapi-psql-orm
┌─────────────┬──────────────────────┐
│ Description │ Dockerized FastAPI   │
│             │ Item Management API  │
│             │ with PostgreSQL      │
│ Stack       │ FastAPI, PostgreSQL, │
│             │ SQLAlchemy, Docker   │
│ Database    │ PostgreSQL           │
│ Features    │ Full ORM, Migrations │
└─────────────┴──────────────────────┘

Select template (fastapi-default, fastapi-async-crud, fastapi-custom-response, fastapi-dockerized, fastapi-psql-orm, fastapi-empty): fastapi-psql-orm

           Project Information
┌──────────────┬─────────────────────┐
│ Project Name │ my-blog-api         │
│ Author       │ John Doe            │
│ Author Email │ john@example.com    │
│ Description  │ Blog API with       │
│              │ PostgreSQL          │
└──────────────┴─────────────────────┘

       Template Dependencies
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ sqlalchemy        │
│ Dependency 4 │ alembic           │
│ Dependency 5 │ psycopg2-binary   │
│ Dependency 6 │ python-dotenv     │
│ Dependency 7 │ pytest            │
└──────────────┴───────────────────┘

Available Package Managers:
                   Package Managers
┌────────┬────────────────────────────────────────────┐
│ PIP    │ Standard Python package manager            │
│ UV     │ Fast Python package manager                │
│ PDM    │ Modern Python dependency management        │
│ POETRY │ Python dependency management and packaging │
└────────┴────────────────────────────────────────────┘

Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y

✨ FastAPI project 'my-blog-api' from 'fastapi-psql-orm' has been created successfully!

模板功能对比

功能	默认模板	异步 CRUD	自定义响应	Docker 化	PostgreSQL ORM	空模板
基础 FastAPI	✅	✅	✅	✅	✅	✅
Mock 数据	✅	✅	✅	✅	❌	❌
异步支持	基础	✅	✅	✅	✅	❌
自定义响应	❌	❌	✅	❌	❌	❌
Docker	❌	❌	❌	✅	✅	❌
数据库	Mock	Mock	Mock	Mock	PostgreSQL	无
ORM	❌	❌	❌	❌	SQLAlchemy	❌
数据迁移	❌	❌	❌	❌	Alembic	❌
测试	✅	✅	✅	✅	✅	❌
适合	学习	性能	自定义 API	生产	数据应用	自定义

各模板的专属设置

使用 `fastapi-psql-orm`

该模板包含完整的 PostgreSQL 配置。创建完成后：

使用 Docker 启动 PostgreSQL：

$ cd my-blog-api
$ docker-compose up -d postgres
Starting my-blog-api_postgres_1 ... done

运行数据库迁移：

$ source .venv/bin/activate
$ alembic upgrade head
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade -> bedcdc35b64a, first alembic

启动 API 服务器：

$ fastkit runserver
INFO:     Uvicorn running on http://127.0.0.1:8000

使用 `fastapi-dockerized`

该模板提供完整的 Docker 支持：

构建 Docker 镜像：

$ cd my-dockerized-api
$ docker build -t my-dockerized-api .
Successfully built abc123def456
Successfully tagged my-dockerized-api:latest

运行容器：

$ docker run -p 8000:8000 my-dockerized-api
INFO:     Uvicorn running on http://0.0.0.0:8000

使用 `fastapi-custom-response`

该模板包含进阶的响应处理:

自定义响应模型:

from src.helper.pagination import PaginatedResponse
from src.schemas.base import StandardResponse

@router.get("/", response_model=PaginatedResponse[Item])
def read_items(skip: int = 0, limit: int = 10):
    items = items_crud.get_multi(skip=skip, limit=limit)
    total = items_crud.count()

    return PaginatedResponse(
        data=items,
        total=total,
        page=skip // limit + 1,
        pages=(total + limit - 1) // limit
    )

@router.post("/", response_model=StandardResponse[Item])
def create_item(item: ItemCreate):
    new_item = items_crud.create(item)
    return StandardResponse(
        data=new_item,
        message="Item created successfully",
        status_code=201
    )

增强的错误处理：

from src.helper.exceptions import ItemNotFoundError, ValidationError

@router.get("/{item_id}", response_model=StandardResponse[Item])
def read_item(item_id: int):
    try:
        item = items_crud.get(item_id)
        return StandardResponse(data=item)
    except ItemNotFoundError:
        raise HTTPException(
            status_code=404,
            detail=f"Item with id {item_id} not found"
        )

各模板的项目结构

每个模板都遵循统一但又针对自身做了定制的结构:

`fastapi-default` 结构

my-project/
├── src/
│   ├── main.py
│   ├── core/config.py
│   ├── api/
│   │   ├── api.py
│   │   └── routes/items.py
│   ├── crud/items.py
│   ├── schemas/items.py
│   └── mocks/mock_items.json
├── tests/
├── scripts/
└── requirements.txt

`fastapi-psql-orm` 结构

my-project/
├── src/
│   ├── main.py
│   ├── core/
│   │   ├── config.py
│   │   └── db.py
│   ├── api/
│   │   ├── api.py
│   │   ├── deps.py
│   │   └── routes/items.py
│   ├── crud/items.py
│   ├── schemas/items.py
│   ├── alembic/
│   │   ├── env.py
│   │   └── versions/
│   └── utils/
├── tests/
├── scripts/
├── docker-compose.yml
├── Dockerfile
├── alembic.ini
└── requirements.txt

定制模板

基于模板创建项目后,您可以进行定制:

1. 添加新路由

$ fastkit addroute posts my-blog-api
$ fastkit addroute users my-blog-api
$ fastkit addroute comments my-blog-api

2. 修改配置

按需修改 src/core/config.py:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "My Blog API"
    VERSION: str = "1.0.0"
    API_V1_STR: str = "/api/v1"

    # 数据库设置（适用于 PostgreSQL 模板）
    DATABASE_URL: str = "postgresql://user:password@localhost/dbname"

    # 安全设置
    SECRET_KEY: str = "your-secret-key-here"
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30

    class Config:
        env_file = ".env"

settings = Settings()

3. 添加环境变量

在项目根目录创建 .env:

# .env
PROJECT_NAME=My Blog API
VERSION=1.0.0
DEBUG=True

# 数据库设置（适用于 PostgreSQL 模板）
DATABASE_URL=postgresql://user:password@localhost:5432/myblogdb
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=myblogdb

# 安全设置
SECRET_KEY=your-super-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

测试模板

每个模板都附带预配置的测试:

$ cd my-blog-api
$ source .venv/bin/activate
$ python -m pytest

======================== test session starts ========================
tests/test_items.py::test_create_item PASSED
tests/test_items.py::test_read_items PASSED
tests/test_items.py::test_read_item PASSED
tests/test_items.py::test_update_item PASSED
tests/test_items.py::test_delete_item PASSED
======================== 5 passed in 0.23s ========================

基于模板的开发流程

1. 选择合适的模板

学习 / 简单 API:fastapi-default
高性能:fastapi-async-crud
自定义响应格式:fastapi-custom-response
生产部署:fastapi-dockerized
数据库应用:fastapi-psql-orm
自定义架构:fastapi-empty

2. 创建并配置

$ fastkit startdemo
# 按提示完成选择
$ cd your-project
$ source .venv/bin/activate

3. 开发

# 启动开发服务器
$ fastkit runserver

# 运行测试
$ python -m pytest

# 添加新功能
$ fastkit addroute new-resource your-project

4. 部署

对于面向生产的模板(fastapi-dockerized、fastapi-psql-orm):

# 构建生产镜像
$ docker build -t your-app .

# 使用 Docker Compose 部署
$ docker-compose up -d

最佳实践

1. 谨慎选择模板

学习时从更简单的模板开始
数据驱动应用使用数据库模板
生产部署使用 Docker 模板

2. 环境管理

始终使用 .env 文件管理配置
切勿将敏感信息提交到版本控制
开发与生产使用不同的环境

3. 定制策略

使用 fastkit addroute 添加新路由
根据您的业务逻辑改造现有代码
保持项目结构清晰

4. 测试

开发过程中持续运行测试
为新实现的功能补充测试
把内置的测试结构当作参考模板

故障排查

数据库连接问题(PostgreSQL 模板)

若无法连接 PostgreSQL:

检查 Docker 是否在运行:

$ docker ps

检查 PostgreSQL 容器:

$ docker-compose logs postgres

检查环境变量:

DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Docker 构建失败

若 Docker 构建失败:

检查 Dockerfile 语法
确认所有文件都存在
确认 Docker 守护进程已启动

依赖缺失

若出现 import 错误:

激活虚拟环境:
```
$ source .venv/bin/activate
```
安装依赖:
```
$ pip install -r requirements.txt
```

下一步

现在您已了解模板:

您的第一个项目:构建一个完整的应用
添加路由:扩展基于模板创建的项目
CLI 参考:掌握所有可用命令

模板小贴士

模板是优秀的起点,而非最终方案
根据具体需求自定义模板
阅读模板代码,学习 FastAPI 最佳实践
使用版本控制记录您的修改

使用模板

可用的模板

模板说明

1. fastapi-default

2. fastapi-async-crud

3. fastapi-custom-response

4. fastapi-dockerized

5. fastapi-psql-orm

6. fastapi-empty

基于模板创建项目

模板功能对比

各模板的专属设置

使用 fastapi-psql-orm

使用 fastapi-dockerized

使用 fastapi-custom-response

各模板的项目结构

fastapi-default 结构

fastapi-psql-orm 结构

定制模板

1. 添加新路由

2. 修改配置

3. 添加环境变量

测试模板

基于模板的开发流程

1. 选择合适的模板

2. 创建并配置

3. 开发

4. 部署

最佳实践

1. 谨慎选择模板

2. 环境管理

3. 定制策略

4. 测试

故障排查

数据库连接问题(PostgreSQL 模板)

Docker 构建失败

依赖缺失

下一步

1. `fastapi-default`

2. `fastapi-async-crud`

3. `fastapi-custom-response`

4. `fastapi-dockerized`

5. `fastapi-psql-orm`

6. `fastapi-empty`

使用 `fastapi-psql-orm`

使用 `fastapi-dockerized`

使用 `fastapi-custom-response`

`fastapi-default` 结构

`fastapi-psql-orm` 结构