FAST API部署和使用

第一部分：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 容器化部署（现代、标准的方式）

容器化部署提供了环境一致性、易于扩展和管理的巨大优势。

1. 创建 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"]
   

2. 创建 .dockerignore (可选但推荐)

   __pycache__
   *.pyc
   .env
   .git
   

3. 构建和运行 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
  

---

第三部分：生产环境额外考虑事项

1. 环境变量配置：使用 pydantic.BaseSettings（例如 pydantic-settings 库）或 python-decouple 来管理敏感信息（如数据库密码、API 密钥），不要将它们硬编码在代码中。

2. 反向代理：在生产环境中，通常会在 FastAPI 应用前面放置一个反向代理服务器，如 Nginx 或 Traefik。它们可以处理：

   • 静态文件：高效地提供图片、CSS、JS 等文件，减轻 FastAPI 的负担。
   • SSL 终止：处理 HTTPS 加密和解密。
   • 负载均衡：将流量分发到后端的多个应用实例。
   • GZip 压缩等。

3. 监控和日志：确保正确配置日志记录。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 的方式开始，这为未来的扩展和部署提供了最大的灵活性。