FastAPI环境搭建与项目初始化

📂 所属阶段：第一阶段 — 快速筑基（基础篇）
🔗 相关章节：FastAPI简介与优势 · Hello-World应用

目录

系统要求

FastAPI对系统环境的要求如下：

操作系统支持

  • Windows: Windows 7 或更高版本
  • macOS: macOS 10.12 或更高版本
  • Linux: 任何主流发行版

Python版本要求

  • 最低版本: Python 3.7+
  • 推荐版本: Python 3.8+ (推荐使用最新稳定版)
  • FastAPI支持: Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12

硬件要求

  • 内存: 至少 2GB RAM (推荐 4GB+)
  • 磁盘空间: 至少 500MB 可用空间
  • CPU: 任何现代处理器

Python环境准备

检查Python版本

在开始之前，首先检查系统中安装的Python版本：

# 检查Python版本
python --version
# 或者
python3 --version

# 检查pip版本
pip --version
# 或者
pip3 --version

如果您的系统中没有安装Python 3.7+，需要先安装：

Windows安装Python

  1. 访问 Python官网
  2. 下载最新的Python 3.x版本
  3. 安装时勾选 "Add Python to PATH"
  4. 验证安装：python --version

macOS安装Python

# 使用Homebrew安装
brew install python

# 或使用MacPorts
sudo port install python311

Linux安装Python

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip

# CentOS/RHEL/Fedora
sudo yum install python3 python3-pip
# 或 (较新版本)
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip

升级pip

安装完成后，建议升级pip到最新版本：

# Windows
python -m pip install --upgrade pip

# macOS/Linux
python3 -m pip install --upgrade pip

虚拟环境创建

使用venv创建虚拟环境

Python 3.3+内置了venv模块，是最推荐的虚拟环境创建方式：

# 创建虚拟环境
python -m venv fastapi-env

# 或者指定Python版本
python3 -m venv fastapi-env

# 在Windows上激活虚拟环境
fastapi-env\Scripts\activate

# 在macOS/Linux上激活虚拟环境
source fastapi-env/bin/activate

激活虚拟环境后，命令行提示符前面会出现(fastapi-env)，表示当前在虚拟环境中。

验证虚拟环境

# 检查当前Python路径
which python  # macOS/Linux
where python  # Windows

# 检查pip路径
which pip     # macOS/Linux
where pip     # Windows

虚拟环境管理命令

# 激活虚拟环境
# Windows
fastapi-env\Scripts\activate
# macOS/Linux
source fastapi-env/bin/activate

# 退出虚拟环境
deactivate

# 删除虚拟环境（删除整个文件夹）
rm -rf fastapi-env  # macOS/Linux
rmdir /s fastapi-env  # Windows

使用requirements.txt管理依赖

创建requirements.txt文件来管理项目依赖：

fastapi==0.110.0
uvicorn[standard]==0.29.0
pydantic==2.6.4
python-multipart==0.0.9

安装依赖：

pip install -r requirements.txt

FastAPI安装

基础安装

# 安装FastAPI
pip install fastapi

# 安装ASGI服务器（推荐uvicorn）
pip install uvicorn[standard]

完整安装（推荐）

# 安装FastAPI及其推荐的依赖
pip install "fastapi[all]"

这将安装FastAPI以及以下推荐的包：

  • python-multipart: 用于form数据处理
  • itsdangerous: 用于sessions
  • jinja2: 用于模板渲染
  • python-dotenv: 用于环境变量
  • email-validator: 用于email验证
  • uvicorn[standard]: ASGI服务器

安装特定版本

# 安装特定版本
pip install fastapi==0.100.0

# 安装最新版本
pip install --upgrade fastapi

# 查看可用版本
pip index versions fastapi

验证安装

# 检查安装的包
pip list | grep fastapi
pip list | grep uvicorn

项目结构初始化

创建项目目录结构

# 创建项目根目录
mkdir my-fastapi-project
cd my-fastapi-project

# 在项目根目录下创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# 安装FastAPI和uvicorn
pip install "fastapi[all]"
pip install uvicorn[standard]

推荐的项目结构

创建以下目录结构：

my-fastapi-project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── endpoints.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── user.py
│   ├── database/
│   │   ├── __init__.py
│   │   └── connection.py
│   └── config/
│       ├── __init__.py
│       └── settings.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── requirements.txt
├── requirements-dev.txt
├── .gitignore
├── .env
├── Dockerfile
├── docker-compose.yml
└── README.md

初始化项目文件

创建基础的app/main.py文件：

from fastapi import FastAPI

app = FastAPI(
    title="我的FastAPI项目",
    description="一个使用FastAPI构建的示例项目",
    version="0.1.0",
    contact={
        "name": "开发者",
        "email": "developer@example.com",
    },
    license_info={
        "name": "MIT License",
        "url": "https://opensource.org/licenses/MIT",
    },
)

@app.get("/")
async def read_root():
    return {"message": "欢迎使用FastAPI项目!"}

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "FastAPI"}

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

创建配置文件

创建app/config/settings.py：

from pydantic_settings import BaseSettings
from typing import Optional

class Settings(BaseSettings):
    app_name: str = "FastAPI Application"
    admin_email: str = "admin@example.com"
    database_url: str = "sqlite:///./test.db"
    secret_key: str = "your-secret-key-here"
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
    
    class Config:
        env_file = ".env"

settings = Settings()

创建.env文件：

APP_NAME=My FastAPI Project
ADMIN_EMAIL=admin@example.com
DATABASE_URL=sqlite:///./app.db
SECRET_KEY=supersecretkeythatshouldbeverylongandrandom
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

创建requirements.txt

fastapi[all]>=0.100.0,<1.0.0
uvicorn[standard]>=0.20.0,<1.0.0
pydantic>=2.0.0,<3.0.0
pydantic-settings>=2.0.0,<3.0.0
sqlalchemy>=2.0.0,<3.0.0
python-jose[cryptography]>=3.3.0,<4.0.0
passlib[bcrypt]>=1.7.0,<2.0.0
python-multipart>=0.0.6,<1.0.0
alembic>=1.10.0,<2.0.0

创建requirements-dev.txt：

-r requirements.txt
pytest>=7.0.0,<8.0.0
pytest-asyncio>=0.20.0,<1.0.0
pytest-cov>=4.0.0,<5.0.0
black>=23.0.0,<24.0.0
flake8>=6.0.0,<7.0.0
mypy>=1.0.0,<2.0.0
pre-commit>=3.0.0,<4.0.0

开发工具配置

VS Code配置

创建.vscode/settings.json：

{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true,
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": [
        "--line-length",
        "88"
    ],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    }
}

创建.vscode/extensions.json：

{
    "recommendations": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff",
        "ms-vscode.vscode-json"
    ]
}

配置pre-commit钩子

创建.pre-commit-config.yaml：

repos:
  - repo: https://github.com/psf/black
    rev: 23.1.0
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
        name: isort (python)

  - repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

安装pre-commit：

pip install pre-commit
pre-commit install

配置mypy类型检查

创建mypy.ini：

[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

[mypy-uvicorn.*]
ignore_missing_imports = True

[mypy-passlib.*]
ignore_missing_imports = True

验证安装

创建测试应用

创建一个简单的测试应用来验证安装：

# test_fastapi.py
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

@app.post("/items/")
async def create_item(item: Item):
    return item

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("test_fastapi:app", host="127.0.0.1", port=8000, reload=True)

运行测试应用

# 运行应用
python test_fastapi.py

# 或者使用uvicorn命令
uvicorn test_fastapi:app --reload

# 访问以下URL验证：
# http://127.0.0.1:8000/docs - Swagger UI
# http://127.0.0.1:8000/redoc - ReDoc

使用curl测试API

# 测试GET请求
curl http://127.0.0.1:8000/items/1?q=test

# 测试POST请求
curl -X POST "http://127.0.0.1:8000/items/" \
     -H "Content-Type: application/json" \
     -d '{"name":"Foo","price":50.5}'

常见问题解决

问题1: Python版本不兼容

错误信息:

ERROR: Package 'fastapi' requires a different Python: 3.6.8 not supported

解决方案:

  • 升级Python到3.7+
  • 或使用支持的Python版本安装

问题2: 权限错误

错误信息:

PermissionError: [Errno 13] Permission denied

解决方案:

  • 使用虚拟环境（推荐）
  • 或使用--user参数：pip install --user fastapi

问题3: SSL证书错误

错误信息:

ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

解决方案:

# Windows
pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org fastapi

# 或升级证书
pip install --upgrade certifi

问题4: uvicorn启动失败

可能原因和解决方案:

# 检查端口是否被占用
netstat -tulpn | grep :8000  # Linux/macOS
netstat -an | findstr :8000   # Windows

# 更改端口
uvicorn main:app --port 8001

问题5: 依赖冲突

解决方案:

# 创建新的干净虚拟环境
rm -rf venv
python -m venv venv
source venv/bin/activate  # 或 venv\Scripts\activate
pip install fastapi uvicorn

性能优化建议

  1. 生产环境使用:
# 安装生产级ASGI服务器
pip install gunicorn uvloop httptools
  1. 使用异步数据库驱动:
# PostgreSQL
pip install asyncpg

# MySQL
pip install aiomysql

# SQLite (内置支持aiofiles)
pip install aiofiles

相关教程

建议始终使用虚拟环境进行开发，这样可以避免包冲突问题。同时，记得定期更新依赖包以获得最新功能和安全修复。 在生产环境中，建议使用Gunicorn配合Uvicorn来部署FastAPI应用，这样可以获得更好的性能和稳定性。

总结

通过本文的学习，您已经掌握了FastAPI开发环境的完整搭建流程：

  1. 环境准备: 确保Python 3.7+环境
  2. 虚拟环境: 使用venv创建隔离的开发环境
  3. FastAPI安装: 安装FastAPI及其相关依赖
  4. 项目结构: 创建规范的项目目录结构
  5. 开发配置: 配置开发工具和代码质量检查
  6. 验证安装: 通过测试应用验证环境

现在您的FastAPI开发环境已经准备就绪，可以开始构建您的第一个FastAPI应用了！