异常教程

FastAPI 安装（长文讲解）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言

在现代 Web 开发领域，FastAPI 凭借其高性能、易维护和强类型注解特性，迅速成为开发者构建 API 服务的首选框架之一。无论是编程初学者还是有一定经验的开发者，掌握 FastAPI 的安装与基础配置都是迈向实战的第一步。本文将从环境准备、安装步骤、配置优化到实际案例，系统性地讲解如何高效完成 FastAPI 的安装与部署。

安装前的准备工作：打好基础更稳扎稳打

1. 确认 Python 环境

FastAPI 是 Python 的 Web 框架，因此安装前需确保系统已安装 Python 3.7 或更高版本。你可以通过命令行输入以下指令验证版本：

python --version  
python3 --version

如果未安装 Python，需根据操作系统选择对应版本的安装包。例如在 Windows 系统中，可通过官网下载安装器；macOS 用户可通过 Homebrew 执行 brew install python3；Linux 用户则可通过包管理器如 apt 或 yum 进行安装。

形象比喻：
将 Python 环境比作一块“编程画布”，而 FastAPI 是在这块画布上作画的“画笔”。只有先准备好画布（Python 环境），才能开始后续的创作（API 开发）。

2. 虚拟环境管理

为避免项目依赖冲突，建议通过虚拟环境隔离不同项目的 Python 环境。主流的虚拟环境工具有 venv（Python 标准库）、conda 或 pipenv。以下以 venv 为例：

python -m venv my-fastapi-env  

my-fastapi-env\Scripts\activate  
source my-fastapi-env/bin/activate

为什么需要虚拟环境？
想象你同时开发两个项目：A 需要依赖库 requests==2.25，而 B 需要 requests==2.26。若不使用虚拟环境，两个版本可能冲突。虚拟环境就像为每个项目分配独立的“工具箱”，避免工具（库）混乱。

FastAPI 的核心安装步骤

1. 安装 FastAPI

确认虚拟环境已激活后，使用 pip 安装 FastAPI：

pip install fastapi

此外，还需安装 ASGI 服务器（如 uvicorn），用于启动 FastAPI 应用：

pip install uvicorn[standard]

注意：uvicorn 是 FastAPI 的推荐服务器，支持异步处理和热重载功能。

2. 验证安装是否成功

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

from fastapi import FastAPI  

app = FastAPI()  

@app.get("/")  
async def read_root():  
    return {"message": "Hello, FastAPI!"}

通过以下命令启动服务：

uvicorn main:app --reload

若控制台显示 INFO: Uvicorn running on http://127.0.0.1:8000，则说明安装成功。访问 http://127.0.0.1:8000 可查看返回的 JSON 数据。

进阶配置：让环境更高效

1. 依赖管理与版本控制

使用 requirements.txt 或 pyproject.toml 管理项目依赖。例如：

pip freeze > requirements.txt  

pip install -r requirements.txt

在 pyproject.toml 中使用 poetry 管理依赖时，格式如下：

[tool.poetry.dependencies]  
python = "^3.9"  
fastapi = "^0.95.0"  
uvicorn = { version = "^0.22.0", extras = ["standard"] }

2. 跨平台安装注意事项

  • Windows：确保在命令提示符或 PowerShell 中运行命令，避免路径中包含空格。
  • macOS：若遇到权限问题，可在命令前添加 sudo，但需谨慎使用。
  • Linux：部分发行版可能需要安装额外依赖，例如 libssl-dev。

案例说明：
某开发者在 Ubuntu 系统安装时遇到 uvicorn 启动失败，发现缺少 openssl 开发库。通过 sudo apt install libssl-dev 解决了问题。

实战案例：构建一个简易天气查询 API

1. 项目结构设计

my_weather_api/  
├── main.py  
├── models/  
│   └── weather.py  
├── dependencies/  
│   └── auth.py  
└── requirements.txt

2. 编写核心代码

在 main.py 中定义接口：

from fastapi import FastAPI, Depends  
from models.weather import WeatherData  
from dependencies.auth import get_api_key  

app = FastAPI()  

@app.get("/weather/{city}")  
async def get_weather(  
    city: str,  
    api_key: str = Depends(get_api_key)  
):  
    # 模拟天气数据  
    return WeatherData(  
        city=city,  
        temperature=22.5,  
        condition="sunny"  
    ).dict()

3. 运行与测试

启动服务后，通过浏览器或 curl 测试接口：

curl "http://127.0.0.1:8000/weather/Shanghai?api_key=12345"

预期返回：

{  
    "city": "Shanghai",  
    "temperature": 22.5,  
    "condition": "sunny"  
}

常见问题与解决方案

1. 安装时出现权限错误

现象：安装 uvicorn 时提示 Permission denied。
解决方法：

  • 使用 --user 参数：pip install uvicorn[standard] --user
  • 或切换到虚拟环境后重试。

2. 端口被占用

现象：启动时提示 Error: Cannot start server process。
解决方法：

lsof -i :8000  
kill -9 <PID>

3. 依赖版本冲突

现象：运行时出现 ModuleNotFoundError 或 ImportError。
解决方法：

  • 清理旧版本依赖：pip uninstall fastapi uvicorn
  • 重新安装指定版本：pip install fastapi==0.95.0 uvicorn==0.22.0

高级主题：FastAPI 的扩展与优化

1. 异步处理与性能提升

FastAPI 原生支持异步函数，通过 async def 定义接口可显著提升并发能力。例如：

@app.get("/async-task")  
async def run_async_task():  
    await some_async_operation()  # 模拟异步操作  
    return {"status": "completed"}

2. 依赖注入与模块化设计

通过 Depends 实现依赖注入，使代码更易维护。例如：

def verify_token(token: str = Header(...)):  
    if token != "secret":  
        raise HTTPException(status_code=401, detail="Invalid token")  
    return token  

@app.get("/protected")  
async def protected_route(token: str = Depends(verify_token)):  
    return {"user": "authenticated"}

结论

通过本文的步骤，你已掌握 FastAPI 的安装、配置及基础实战方法。从环境准备到依赖管理，再到接口开发与问题排查，每个环节都体现了 FastAPI 的简洁与高效特性。对于初学者，建议从简单接口入手，逐步尝试异步、认证等高级功能；中级开发者则可结合现有项目，探索 FastAPI 在微服务或高性能场景中的应用。

下一步行动建议：

  1. 访问 FastAPI 官方文档 获取更多案例。
  2. 尝试将现有 Flask 或 Django 项目迁移到 FastAPI。
  3. 参与开源社区，了解 FastAPI 的最新特性与最佳实践。

通过持续实践与学习，你将能充分发掘 FastAPI 在 API 开发中的潜力，构建出健壮、可扩展的 Web 服务。

最新发布

查看更多文章