# Web 开发

Python 是 Web 开发的热门选择，本章介绍 FastAPI 和 Flask 两个主流框架的使用和最佳实践。

```{toctree}
:maxdepth: 2

fastapi
flask
api_design
security
```

## 框架对比

| 特性 | FastAPI | Flask |
|------|---------|-------|
| 类型 | 异步优先 | 同步为主 |
| 性能 | 高（异步） | 中等 |
| 类型提示 | 原生支持 | 可选 |
| 自动文档 | Swagger/OpenAPI | 需要扩展 |
| 学习曲线 | 中等 | 低 |
| 生态系统 | 成长中 | 成熟 |
| 适用场景 | API、微服务 | Web 应用、API |

## 快速对比

### FastAPI

```python
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str
    age: int

@app.post("/users/")
async def create_user(user: User):
    # 自动验证、序列化、文档
    return {"user": user, "message": "Created"}

# 自动生成 OpenAPI 文档：/docs
```

### Flask

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/users/", methods=["POST"])
def create_user():
    data = request.get_json()
    # 手动验证
    if not data.get("name"):
        return jsonify({"error": "Name required"}), 400
    return jsonify({"user": data, "message": "Created"})
```

## 选择建议

```{mermaid}
graph TD
    A[项目类型?] --> B{纯 API}
    A --> C{Web 应用}
    A --> D{微服务}
    
    B --> E{需要高性能?}
    E -->|是| F[FastAPI]
    E -->|否| G[FastAPI 或 Flask]
    
    C --> H{需要模板渲染?}
    H -->|是| I[Flask]
    H -->|否| F
    
    D --> F
```

::::{grid} 2
:gutter: 2

:::{grid-item-card} 选择 FastAPI 当
1. 构建 RESTful API
2. 需要自动 API 文档
3. 利用类型提示和验证
4. 需要异步/高并发
5. 构建微服务
:::

:::{grid-item-card} 选择 Flask 当
1. 需要服务端渲染
2. 项目较简单
3. 团队熟悉 Flask
4. 需要大量扩展支持
5. 快速原型开发
:::

::::

## 项目结构

### 推荐的 FastAPI 项目结构

```
my_api/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI 应用入口
│   ├── config.py         # 配置
│   ├── dependencies.py   # 依赖注入
│   ├── models/           # Pydantic 模型
│   │   ├── __init__.py
│   │   └── user.py
│   ├── schemas/          # 数据库模型（SQLAlchemy）
│   │   ├── __init__.py
│   │   └── user.py
│   ├── routers/          # 路由
│   │   ├── __init__.py
│   │   └── users.py
│   ├── services/         # 业务逻辑
│   │   ├── __init__.py
│   │   └── user_service.py
│   └── utils/            # 工具函数
├── tests/
│   ├── __init__.py
│   └── test_users.py
├── requirements.txt
└── pyproject.toml
```

### 推荐的 Flask 项目结构

```
my_app/
├── app/
│   ├── __init__.py       # 应用工厂
│   ├── config.py         # 配置
│   ├── models/           # 数据库模型
│   │   └── user.py
│   ├── views/            # 视图/路由
│   │   ├── __init__.py
│   │   └── users.py
│   ├── services/         # 业务逻辑
│   ├── templates/        # Jinja2 模板
│   └── static/           # 静态文件
├── migrations/           # 数据库迁移
├── tests/
├── requirements.txt
└── run.py
```

## 开发环境设置

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS

# FastAPI
pip install "fastapi[all]"  # 包含 uvicorn

# Flask
pip install flask flask-sqlalchemy flask-migrate

# 开发工具
pip install pytest httpx black mypy

# 运行 FastAPI
uvicorn app.main:app --reload

# 运行 Flask
flask run --debug
```