FastAPI+Uvicorn：本地开发与部署的基础配置

一、FastAPI和Uvicorn简介¶

在Python Web开发领域，FastAPI是近年来非常流行的高性能Web框架，它基于标准Python类型提示，支持异步操作，且自动生成API文档，开发效率极高。而Uvicorn是一个轻量级的ASGI（异步服务器网关接口）服务器，专为高性能Python Web应用设计，也是FastAPI官方推荐的服务器之一。

简单来说，FastAPI负责定义API接口逻辑，Uvicorn负责接收请求、处理并发并返回响应。两者搭配使用，既能快速开发，又能稳定部署。

二、环境安装¶

1. 创建虚拟环境（推荐）¶

为避免依赖冲突，建议先创建虚拟环境：

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

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

# 激活虚拟环境（Mac/Linux）
source venv/bin/activate

2. 安装FastAPI和Uvicorn¶

在激活的虚拟环境中执行：

pip install fastapi uvicorn

安装完成后，可通过 pip list 验证是否成功安装。

三、本地开发环境配置¶

1. 编写第一个FastAPI应用¶

创建一个名为 main.py 的文件，写入以下代码：

from fastapi import FastAPI

# 初始化FastAPI应用
app = FastAPI()

# 定义一个根路由（"/"），返回JSON数据
@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI+Uvicorn！"}

# 定义一个带参数的路由（如"/items/123"）
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

2. 用Uvicorn启动应用¶

在终端执行以下命令启动服务器：

uvicorn main:app --reload

参数说明：
main:app：表示从 main.py 文件中导入 app 对象（即FastAPI实例）。
--reload：开发模式下自动重载代码（修改后无需手动重启）。

3. 验证接口是否运行¶

启动成功后，终端会显示类似信息：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345]

此时可通过以下方式测试接口：
- 浏览器访问：打开 http://127.0.0.1:8000，页面会显示 {"message": "Hello, FastAPI+Uvicorn！"}。
- 调用带参数接口：访问 http://127.0.0.1:8000/items/456?query=test，返回 {"item_id": 456, "query": "test"}。

四、生产环境部署基础¶

本地开发用 --reload 方便调试，但生产环境需关闭自动重载并优化配置。

1. 基础部署命令¶

直接使用Uvicorn启动（无需自动重载）：

uvicorn main:app --host 0.0.0.0 --port 8000

参数说明：
--host 0.0.0.0：允许外部设备访问（默认仅本地 127.0.0.1 访问）。
--port 8000：指定端口（可改为其他端口，如 80 需管理员权限）。

2. 多进程部署（提升性能）¶

若服务器有多个CPU核心，可通过 --workers 参数启动多进程：

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

--workers 4：启动4个工作进程（建议设置为CPU核心数的2倍）。

3. 部署到服务器（如阿里云/腾讯云）¶

上传代码：将 main.py 和虚拟环境上传到服务器（或直接在服务器内创建）。
启动应用：在服务器终端执行部署命令（需确保服务器开放对应端口，如8000）。
后台运行：若需长期运行，可结合 nohup 或 systemd 管理进程：

   # 使用nohup后台运行
   nohup uvicorn main:app --host 0.0.0.0 --port 8000 &

五、常见问题与解决¶

1. 端口被占用怎么办？¶

检查占用进程：lsof -i :8000（Mac/Linux）或 netstat -ano | findstr :8000（Windows）。
修改端口：执行 uvicorn main:app --port 8001，更换为未占用的端口。

2. 访问不到接口？¶

确认host参数：确保 --host 0.0.0.0 而非 127.0.0.1（本地回环地址仅允许本机访问）。
检查防火墙：服务器需开放对应端口（如8000），可通过 ufw allow 8000（Ubuntu）开放端口。

3. 安装失败？¶

更新pip：pip install --upgrade pip。
确认Python版本：FastAPI要求Python 3.6+，建议使用Python 3.9+。

六、总结¶

FastAPI+Uvicorn的本地开发与部署流程核心步骤：
1. 开发：用 uvicorn main:app --reload 快速调试接口。
2. 部署：用 uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 启动生产环境。

通过本文，你已掌握基础配置和常见问题处理。后续可探索FastAPI的异步接口、数据库集成或Uvicorn的高级参数（如SSL证书配置）。

动手实践：尝试修改 main.py 添加新接口，或部署到云服务器，体验完整开发流程吧！