第一部分：FastAPI 的使用（开发环境）
1. 安装
首先，你需要安装 FastAPI 和一个 ASGI 服务器，最常用的是 Uvicorn。
pip install "fastapi[standard]"
这个命令会安装 FastAPI 以及所有推荐的依赖，包括 Uvicorn（用于服务器）、Pydantic（用于数据模型）等。
2. 创建一个简单的应用
创建一个名为 main.py 的文件：
# main.py
from fastapi import FastAPI# 创建 FastAPI 应用实例
app = FastAPI()# 定义根路径的 GET 请求处理程序
@app.get("/")
async def read_root():return {"message": "Hello, World!"}# 定义一个带路径参数的 GET 请求处理程序
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):return {"item_id": item_id, "q": q}
3. 运行开发服务器
使用 Uvicorn 在本地运行你的应用：
uvicorn main:app --reload
main:app:main是你的模块文件名（不含.py），app是你在代码中创建的FastAPI()实例的名称。--reload: 让服务器在代码更改后自动重启。仅在开发时使用此选项。
输出会显示服务器运行地址，通常是 http://127.0.0.1:8000。
4. 交互式 API 文档
FastAPI 最强大的特性之一就是自动生成交互式 API 文档。启动服务器后，你可以访问：
- Swagger UI 文档:
http://127.0.0.1:8000/docs- 这是一个交互式界面，你可以直接看到所有端点，并尝试调用它们。
- ReDoc 文档:
http://127.0.0.1:8000/redoc- 这是一个更漂亮的、基于静态页面的文档。
5. 测试 API
你可以使用 curl、httpie 或任何 API 客户端（如 Postman, Insomnia）来测试你的 API。
# 测试根路径
curl http://localhost:8000# 测试带参数的路径
curl "http://localhost:8000/items/5?q=somequery"
第二部分：FastAPI 的部署（生产环境）
重要提示：千万不要在生产环境中使用 --reload 选项。
生产环境部署有多种方式，以下是几种最常见和推荐的方法。
方式 1: 使用 Uvicorn 直接运行（简单部署）
对于小型应用或初期部署，你可以直接运行 Uvicorn，但需要调整一些参数以获得更好的性能。
uvicorn main:app --host 0.0.0.0 --port 80 --workers 4
--host 0.0.0.0: 让服务器监听所有公共 IP，而不仅仅是本地回环地址 (127.0.0.1)。--port 80: 使用标准的 HTTP 端口 80。--workers 4: 启动多个工作进程（worker processes）。数量通常设置为CPU 核心数 * 2 + 1。这利用了多进程模式，大大提高了并发能力。
优点：简单快捷。
缺点：缺乏高级功能，如 graceful shutdown、更复杂的负载均衡等。通常用于过渡或简单场景。
方式 2: 使用 Gunicorn 作为进程管理器（推荐）
Uvicorn 提供了一个 Worker 类，可以与 Gunicorn 这样的成熟进程管理器配合使用。Gunicorn 负责管理多个 Uvicorn 工作进程，提供了更强大的生产环境特性。
首先，安装 Gunicorn 和 Uvicorn：
pip install "uvicorn[standard]" gunicorn
然后使用 Gunicorn 来启动你的应用：
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
main:app: 和之前一样。-w 4,--workers 4: 设置工作进程的数量。-k uvicorn.workers.UvicornWorker,--worker-class uvicorn.workers.UvicornWorker: 指定使用 Uvicorn 的工作器类。-b 0.0.0.0:8000,--bind 0.0.0.0:8000: 绑定地址和端口。
这是部署 FastAPI/Starlette 应用的非常流行和稳健的方式。
方式 3: 使用 Docker 容器化部署（现代、标准的方式）
容器化部署提供了环境一致性、易于扩展和管理的巨大优势。
-
创建
Dockerfile在你的项目根目录下创建一个名为
Dockerfile的文件（没有扩展名）。# 使用官方 Python 基础镜像 FROM python:3.9-slim# 设置工作目录 WORKDIR /app# 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt# 复制应用代码 COPY . .# 暴露端口 EXPOSE 80# 运行应用 # 方式 1: 直接使用 Uvicorn (适用于容器内部署) CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]# 方式 2: 使用 Gunicorn (更推荐用于生产) # CMD ["gunicorn", "main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:80"] -
创建
.dockerignore(可选但推荐)__pycache__ *.pyc .env .git -
构建和运行 Docker 镜像
# 构建镜像 docker build -t my-fastapi-app .# 运行容器 docker run -d -p 80:80 --name my-app my-fastapi-app现在你的应用就在 Docker 容器中运行了，可以通过宿主机的 80 端口访问。
你可以轻松地将这个 Docker 镜像部署到任何支持容器的平台，如：
- Kubernetes
- Docker Compose (用于本地或单机部署)
- Amazon ECS
- Google Cloud Run
- Azure Container Instances
方式 4: 使用其他 ASGI 服务器
除了 Uvicorn，你还可以选择其他 ASGI 服务器，例如：
- Hypercorn: 一个灵感来源于 Gunicorn 的 ASGI 服务器，也支持 HTTP/2。
pip install hypercorn hypercorn main:app --bind 0.0.0.0:8000
第三部分：生产环境额外考虑事项
-
环境变量配置：使用
pydantic.BaseSettings（例如pydantic-settings库）或python-decouple来管理敏感信息（如数据库密码、API 密钥），不要将它们硬编码在代码中。 -
反向代理：在生产环境中，通常会在 FastAPI 应用前面放置一个反向代理服务器，如 Nginx 或 Traefik。它们可以处理：
- 静态文件：高效地提供图片、CSS、JS 等文件，减轻 FastAPI 的负担。
- SSL 终止：处理 HTTPS 加密和解密。
- 负载均衡：将流量分发到后端的多个应用实例。
- GZip 压缩等。
-
监控和日志：确保正确配置日志记录。Uvicorn 和 Gunicorn 都有日志选项。考虑集成像 Prometheus 和 Grafana 这样的监控工具，FastAPI 有很好的 Prometheus 集成库（如
fastapi-prometheus-grafana）。
总结
| 环境 | 推荐方式 | 命令示例 |
|---|---|---|
| 开发 | Uvicorn + --reload | uvicorn main:app --reload |
| 生产（简单） | Uvicorn 多 Worker | uvicorn main:app --host 0.0.0.0 --port 80 --workers 4 |
| 生产（推荐） | Gunicorn + Uvicorn Worker | gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker ... |
| 生产（现代） | Docker + (Uvicorn/Gunicorn) | docker build ... |
对于新项目，强烈推荐从 Docker化 并结合 Gunicorn + Uvicorn Worker 的方式开始，这为未来的扩展和部署提供了最大的灵活性。
)
)
