环境搭建与 Hello World

一、Python 环境准备

1. 检查 Python 版本

FastAPI 要求 Python 3.8+，推荐 3.10+ 以获得最佳类型提示支持：

python --version
# Python 3.10.12

2. 创建虚拟环境

虚拟环境隔离项目依赖，避免版本冲突：

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

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

# 激活虚拟环境
# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

激活后，命令行提示符会显示 (venv)：

(venv) C:\my-fastapi-project>

二、安装 FastAPI

基础安装

pip install fastapi

完整安装（推荐）

包含 Uvicorn（ASGI 服务器）和标准依赖：

pip install "fastapi[all]"

或分开安装：

pip install fastapi uvicorn[standard]

验证安装

pip list | grep -E "fastapi|uvicorn"
# fastapi 0.115.0
# uvicorn 0.32.0

三、Hello World 项目

1. 创建项目文件

# 项目结构
my-fastapi-project/
├── venv/              # 虚拟环境
├── main.py            # 主程序
└── requirements.txt   # 依赖列表

2. 编写第一个 API

创建 main.py：

from fastapi import FastAPI

# 创建 FastAPI 实例
app = FastAPI(
    title="Hello API",
    description="我的第一个 FastAPI 项目",
    version="1.0.0"
)

# 根路由
@app.get("/")
async def root():
    """返回欢迎信息"""
    return {
        "message": "Hello, FastAPI!",
        "docs": "/docs",
        "redoc": "/redoc"
    }

# 带参数的路由
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    """
    根据 ID 获取项目信息
    
    - **item_id**: 项目 ID（整数）
    - **q**: 可选的查询参数
    """
    return {
        "item_id": item_id,
        "q": q
    }

# POST 请求示例
@app.post("/items/")
async def create_item(name: str, price: float):
    """创建新项目"""
    return {
        "name": name,
        "price": price,
        "message": "Item created successfully"
    }

四、运行服务

1. 使用 Uvicorn 运行

# 基本运行
uvicorn main:app

# 常用参数
uvicorn main:app --reload      # 开发模式，自动重载
uvicorn main:app --host 0.0.0.0 --port 8080  # 指定地址和端口
uvicorn main:app --workers 4   # 多进程模式（生产环境）

参数说明：

参数	说明
`main:app`	模块名:FastAPI 实例名
`--reload`	代码变更自动重载（仅开发）
`--host`	绑定地址，`0.0.0.0` 允许外部访问
`--port`	端口号，默认 8000
`--workers`	工作进程数，生产环境使用

2. 使用 Python 直接运行

# main.py 末尾添加
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

然后：

python main.py

五、自动生成的 API 文档

FastAPI 的最大亮点：零配置自动生成交互式文档。

1. Swagger UI

访问：http://127.0.0.1:8000/docs

功能：

可视化所有 API 端点
在线测试接口
查看请求/响应模型
导出 OpenAPI 规范

2. ReDoc

访问：http://127.0.0.1:8000/redoc

特点：

更美观的文档界面
适合对外展示
支持搜索和导航

3. OpenAPI 规范

访问：http://127.0.0.1:8000/openapi.json

这是标准的 OpenAPI 3.0 规范，可被各种工具消费。

六、测试 API

1. 浏览器测试

直接访问：

2. 使用 Swagger UI 测试

打开 http://127.0.0.1:8000/docs
点击任意接口的 "Try it out"
填写参数
点击 "Execute"

3. 使用 curl

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

# 带参数
curl "http://127.0.0.1:8000/items/42?q=search"

# POST 请求
curl -X POST "http://127.0.0.1:8000/items/?name=Book&price=29.99"

4. 使用 Python requests

import requests

# GET 请求
response = requests.get("http://127.0.0.1:8000/items/42", params={"q": "test"})
print(response.json())

# POST 请求
response = requests.post(
    "http://127.0.0.1:8000/items/",
    params={"name": "Book", "price": 29.99}
)
print(response.json())

七、项目结构规范

小型项目结构：

my-project/
├── main.py           # 入口文件
├── routers/          # 路由模块
│   ├── __init__.py
│   ├── items.py
│   └── users.py
├── models/           # 数据模型
│   ├── __init__.py
│   └── schemas.py
├── database.py       # 数据库配置
└── requirements.txt

大型项目结构：

my-project/
├── app/              # 应用主目录
│   ├── __init__.py
│   ├── main.py       # 入口
│   ├── core/         # 核心配置
│   ├── models/       # 数据库模型
│   ├── schemas/      # Pydantic 模型
│   ├── routers/      # API 路由
│   ├── services/     # 业务逻辑
│   └── dependencies.py
├── tests/            # 测试
├── alembic/          # 数据库迁移
├── docker-compose.yml
└── Dockerfile

八、依赖管理

生成 requirements.txt

pip freeze > requirements.txt

精简版 requirements.txt

fastapi==0.115.0
uvicorn[standard]==0.32.0

安装依赖

pip install -r requirements.txt

九、常见问题

1. 端口被占用

# 查找占用 8000 端口的进程
# Windows:
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# macOS/Linux:
lsof -i :8000
kill -9 <PID>

2. 虚拟环境未激活

# 错误：ModuleNotFoundError: No module named 'fastapi'
# 解决：确保激活虚拟环境
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

3. 异步函数定义

# ✅ 正确：使用 async def
@app.get("/")
async def root():
    return {"message": "Hello"}

# ⚠️ 也可以：使用普通 def（但不推荐混用）
@app.get("/")
def root():
    return {"message": "Hello"}

十、小结

步骤	命令/操作
创建虚拟环境	`python -m venv venv`
激活环境	`venv\Scripts\activate`
安装 FastAPI	`pip install fastapi uvicorn[standard]`
运行服务	`uvicorn main:app --reload`
查看文档	http://127.0.0.1:8000/docs

#环境搭建与 Hello World

#一、Python 环境准备

#1. 检查 Python 版本

#2. 创建虚拟环境

#二、安装 FastAPI

#基础安装

#完整安装（推荐）

#验证安装

#三、Hello World 项目

#1. 创建项目文件

#2. 编写第一个 API

#四、运行服务

#1. 使用 Uvicorn 运行

#2. 使用 Python 直接运行

#五、自动生成的 API 文档

#1. Swagger UI

#2. ReDoc

#3. OpenAPI 规范

#六、测试 API

#1. 浏览器测试

#2. 使用 Swagger UI 测试

#3. 使用 curl

#4. 使用 Python requests

#七、项目结构规范

#八、依赖管理

#生成 requirements.txt

#精简版 requirements.txt

#安装依赖

#九、常见问题

#1. 端口被占用

#2. 虚拟环境未激活

#3. 异步函数定义

#十、小结