安装与配置 #

┌─────────────────────────────────────────────────────────────┐
│                    Python 版本要求                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Python 3.8   ✅ 最低要求                                   │
│   Python 3.9   ✅ 支持                                       │
│   Python 3.10  ✅ 推荐（更好的类型提示）                       │
│   Python 3.11  ✅ 推荐（性能提升）                            │
│   Python 3.12  ✅ 支持                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

python --version
# 或
python3 --version

pip install fastapi

pip install uvicorn[standard]

pip install fastapi uvicorn[standard]

┌─────────────────────────────────────────────────────────────┐
│                    虚拟环境的作用                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   系统Python                                                │
│   └── 全局包（可能与其他项目冲突）                            │
│                                                             │
│   项目A虚拟环境                                              │
│   └── fastapi==0.100.0                                      │
│                                                             │
│   项目B虚拟环境                                              │
│   └── fastapi==0.95.0                                       │
│                                                             │
│   ✅ 隔离项目依赖                                            │
│   ✅ 避免版本冲突                                            │
│   ✅ 便于部署和复现                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

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

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

# Windows
venv\Scripts\activate

# 安装依赖
pip install fastapi uvicorn[standard]

# 安装 Poetry
pip install poetry

# 创建项目
poetry new my-api
cd my-api

# 添加依赖
poetry add fastapi uvicorn[standard]

# 激活虚拟环境
poetry shell

# 安装 uv
pip install uv

# 创建项目
uv init my-api
cd my-api

# 添加依赖
uv add fastapi uvicorn[standard]

# 运行
uv run uvicorn main:app --reload

my-api/
├── main.py
└── requirements.txt

my-api/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI 应用入口
│   ├── config.py         # 配置管理
│   ├── dependencies.py   # 依赖注入
│   ├── routers/          # 路由模块
│   │   ├── __init__.py
│   │   ├── users.py
│   │   └── items.py
│   ├── models/           # Pydantic 模型
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── schemas/          # 请求/响应模式
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── services/         # 业务逻辑
│   │   ├── __init__.py
│   │   └── user_service.py
│   └── utils/            # 工具函数
│       ├── __init__.py
│       └── security.py
├── tests/                # 测试文件
│   ├── __init__.py
│   ├── conftest.py
│   └── test_main.py
├── .env                  # 环境变量
├── .gitignore
├── requirements.txt
└── README.md

fastapi>=0.100.0
uvicorn[standard]>=0.23.0
pydantic>=2.0.0
python-multipart>=0.0.6

pip install -r requirements.txt

pip freeze > requirements.txt

import os
from fastapi import FastAPI

app = FastAPI()

DEBUG = os.getenv('DEBUG', 'false').lower() == 'true'
DATABASE_URL = os.getenv('DATABASE_URL', 'sqlite:///./test.db')

@app.get('/config')
def get_config():
    return {
        'debug': DEBUG,
        'database_url': DATABASE_URL
    }

pip install pydantic-settings

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = 'My API'
    debug: bool = False
    database_url: str = 'sqlite:///./test.db'
    
    class Config:
        env_file = '.env'

settings = Settings()

APP_NAME=My FastAPI App
DEBUG=true
DATABASE_URL=postgresql://user:pass@localhost/db

# 基本运行
uvicorn main:app

# 开发模式（自动重载）
uvicorn main:app --reload

# 指定端口
uvicorn main:app --reload --port 8080

# 指定主机
uvicorn main:app --reload --host 0.0.0.0

# 多进程
uvicorn main:app --workers 4

# 使用 Gunicorn + Uvicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get('/')
def read_root():
    return {'Hello': 'World'}

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

┌─────────────────────────────────────────────────────────────┐
│                    API 文档地址                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Swagger UI:  http://localhost:8000/docs                   │
│   ReDoc:       http://localhost:8000/redoc                  │
│   OpenAPI:     http://localhost:8000/openapi.json           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "main:app",
                "--reload"
            ],
            "jinja": true
        }
    ]
}

# 查找占用端口的进程
lsof -i :8000

# 终止进程
kill -9 <PID>

# 或使用其他端口
uvicorn main:app --port 8001

# 确保在正确的目录
cd /path/to/project

# 确保虚拟环境已激活
source venv/bin/activate

# 检查 Python 路径
python -c "import sys; print(sys.path)"

# 错误示例
from app.main import app  # 可能导致导入问题

# 正确做法：在项目根目录运行
uvicorn app.main:app --reload

# 安装
pip install httpie

# GET 请求
http GET http://localhost:8000/

# POST 请求
http POST http://localhost:8000/items name="Item 1" price:=10.5

# GET 请求
curl http://localhost:8000/

# POST 请求
curl -X POST http://localhost:8000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Item 1", "price": 10.5}'