搭建开发环境与安装 FastAPI

在开始编写FastAPI应用之前，我们需要搭建一个完善的开发环境。这个过程不仅仅是简单地安装几个软件包，而是需要理解每个工具的作用、它们之间的协作关系，以及如何配置它们以获得最佳的开发体验。 一个良好的开发环境能够显著提升我们的开发效率，减少调试时间，帮助我们编写出更高质量的代码。

在这一部分，我们将系统地学习如何从零开始搭建FastAPI开发环境，包括Python环境的配置、虚拟环境的管理、FastAPI及其依赖的安装，以及开发工具的配置。

Python环境的准备

Python是FastAPI的基础，因此我们需要首先确保系统上安装了正确版本的Python。FastAPI要求Python 3.7或更高版本，但为了充分利用FastAPI的所有特性，特别是类型提示和异步编程功能，我们强烈建议使用Python 3.8或更高版本。 Python 3.8引入了许多改进，包括更好的类型提示支持、性能优化，以及更完善的异步编程特性，这些都对FastAPI应用的开发非常重要。

Python版本的选择与安装

在选择Python版本时，我们需要考虑几个因素。首先是稳定性，新版本的Python可能包含一些尚未完全测试的特性，而较旧的版本可能缺少我们需要的功能。对于FastAPI开发，Python 3.9或3.10是一个很好的选择，它们在稳定性和功能之间取得了良好的平衡。Python 3.11引入了更多的性能改进，但可能某些第三方库还没有完全兼容。Python 3.12是最新的版本，提供了最新的特性和性能优化，但我们需要确保所有依赖库都支持这个版本。

在Windows系统上安装Python相对简单，我们可以从Python官网下载安装程序。安装程序会引导我们完成整个安装过程，包括选择安装路径、是否添加到PATH环境变量等。 将Python添加到PATH环境变量非常重要，这样我们就可以在任何位置通过命令行访问Python。安装完成后，我们可以打开命令提示符或PowerShell，输入python --version来验证安装是否成功。 如果系统上同时安装了Python 2和Python 3，我们可能需要使用python3命令来调用Python 3。

在macOS系统上，系统通常已经预装了Python，但可能是较旧的版本。我们可以使用Homebrew来安装最新版本的Python，这是macOS上最流行的包管理器。首先需要安装Homebrew，然后使用brew install python3命令来安装Python。 Homebrew会自动处理依赖关系，并将Python安装到标准位置。安装完成后，我们可以使用python3 --version来验证安装。

在Linux系统上，大多数发行版都预装了Python，但版本可能较旧。我们可以使用系统的包管理器来安装或更新Python。在Ubuntu或Debian系统上，可以使用apt-get install python3来安装Python 3。 在CentOS或RHEL系统上，可以使用yum install python3。对于需要最新版本的情况，我们可以从源码编译安装Python，但这需要更多的配置工作。

Python版本管理工具的使用

在实际开发中，我们可能需要同时管理多个Python版本，或者在不同的项目中使用不同的Python版本。这时，Python版本管理工具就变得非常重要。pyenv是一个流行的Python版本管理工具，它允许我们在同一台机器上安装和切换多个Python版本。pyenv的工作原理是通过修改PATH环境变量，将特定版本的Python放在路径的前面，这样当我们运行python命令时，就会使用pyenv指定的版本。

安装pyenv后，我们可以使用pyenv install 3.10.0来安装特定版本的Python，使用pyenv global 3.10.0来设置全局默认版本，使用pyenv local 3.10.0来为当前项目设置本地版本。pyenv还支持通过.python-version文件来指定项目的Python版本，这样当我们进入项目目录时，pyenv会自动切换到正确的版本。这种机制使得不同项目可以使用不同的Python版本，而不会相互干扰。

除了pyenv，还有其他一些版本管理工具，比如conda。conda不仅管理Python版本，还管理Python包和环境。conda特别适合数据科学和机器学习项目，因为它可以管理复杂的依赖关系。对于FastAPI开发，如果我们不需要conda的其他功能，pyenv可能是一个更轻量级的选择。

虚拟环

虚拟环境允许我们为每个项目创建独立的Python环境，每个环境都有自己的Python解释器和包集合。这种隔离机制解决了多个项目可能依赖不同版本包的问题，避免了包版本冲突。

想象一下这样的场景：我们有两个项目，项目A需要requests库的2.25版本，而项目B需要requests库的2.28版本。如果没有虚拟环境，我们只能安装一个版本，这会导致其中一个项目无法正常工作。 有了虚拟环境，我们可以为项目A创建一个环境并安装requests 2.25，为项目B创建另一个环境并安装requests 2.28，两个项目可以互不干扰地运行。

虚拟环境还帮助我们保持系统Python环境的整洁。系统Python环境通常用于系统工具和脚本，如果我们直接在系统环境中安装项目依赖，可能会污染系统环境，甚至影响系统工具的正常运行。使用虚拟环境，我们可以放心地安装任何需要的包，而不用担心影响系统。

创建和管理虚拟环境

Python 3.3及更高版本内置了venv模块，这是创建虚拟环境的标准方法。使用venv创建虚拟环境非常简单，只需要运行python -m venv venv_name命令，其中venv_name是我们想要创建的虚拟环境的名称。通常，我们使用venv或.venv作为环境名称，这是一个约定俗成的做法，大多数开发者都能理解。

创建虚拟环境后，我们需要激活它才能使用。在Windows系统上，激活命令是venv_name\Scripts\activate，在macOS和Linux系统上，激活命令是source venv_name/bin/activate。激活后，命令提示符前面会出现虚拟环境的名称，提示我们当前正在使用虚拟环境。在虚拟环境中，我们安装的所有包都会安装到这个环境中，而不是系统Python环境。

当我们完成工作后，可以使用deactivate命令来退出虚拟环境。退出后，我们就回到了系统Python环境。需要注意的是，虚拟环境是特定于项目的，我们应该在项目根目录下创建虚拟环境，并且通常将虚拟环境目录添加到.gitignore文件中，避免将其提交到版本控制系统。

除了venv，还有其他一些虚拟环境工具，比如virtualenv。virtualenv是venv的前身，提供了更多的配置选项。对于大多数情况，venv已经足够使用，但如果我们需要更高级的功能，可以考虑使用virtualenv。另一个流行的选择是pipenv，它结合了pip和virtualenv的功能，还提供了依赖管理的特性。

依赖管理工具的选择

在Python项目中，管理依赖是一个重要的任务。我们需要记录项目依赖哪些包，以及这些包的版本要求。这样，其他开发者或部署环境就可以根据这些信息安装正确的依赖。Python生态系统中有多种依赖管理工具，每种工具都有其特点和适用场景。

pip的基础使用

pip是Python的官方包管理器，是安装Python包的标准工具。pip随Python一起安装，我们可以直接使用pip install package_name来安装包。pip会从PyPI（Python Package Index）下载包并安装到当前Python环境中。PyPI是Python包的官方仓库，包含了数十万个Python包。

使用pip安装包时，我们可以指定版本号。例如，pip install fastapi==0.104.1会安装特定版本的FastAPI，pip install fastapi>=0.100.0会安装0.100.0或更高版本。版本号的选择很重要，我们应该根据项目的需求选择合适的版本。通常，我们使用最新的稳定版本，但如果项目已经运行在生产环境中，我们可能需要锁定版本号，避免自动更新带来的意外问题。

pip还支持从requirements.txt文件安装依赖。requirements.txt是一个文本文件，每行包含一个包名和可选的版本号。我们可以使用pip install -r requirements.txt来安装文件中列出的所有包。这种方式的优势是我们可以将项目的依赖信息保存到版本控制系统中，其他开发者可以轻松地安装相同的依赖。

创建requirements.txt文件也很简单，我们可以使用pip freeze > requirements.txt命令来生成当前环境中所有已安装包的列表。这个命令会输出所有包及其精确版本号，确保环境的可重现性。但是，pip freeze会包含所有包，包括我们可能不需要的依赖的依赖。为了保持requirements.txt的简洁，我们应该只包含项目直接依赖的包，让pip自动处理传递依赖。

requirements.txt的维护

维护requirements.txt文件是项目开发中的一个重要任务。随着项目的发展，我们可能会添加新的依赖，更新现有依赖的版本，或者移除不再需要的依赖。每次修改依赖后，我们都应该更新requirements.txt文件，确保它反映当前项目的实际依赖。

在团队开发中，requirements.txt文件的一致性非常重要。所有团队成员应该使用相同版本的依赖，这样可以避免"在我机器上能运行"的问题。为了确保一致性，我们可以在CI/CD流程中验证requirements.txt文件，或者在项目文档中明确说明如何安装依赖。

requirements.txt文件还可以包含注释，以#开头。我们可以使用注释来说明为什么需要某个依赖，或者记录某些特殊配置。例如，我们可以在文件中添加注释说明某个包是开发依赖还是生产依赖，虽然pip本身不区分这些，但注释可以帮助团队成员理解依赖的用途。

现代依赖管理工具

虽然pip和requirements.txt是Python依赖管理的标准方式，但现代项目可能需要更强大的依赖管理工具。poetry是一个现代的Python依赖管理工具，它提供了更好的依赖解析、锁定文件生成、虚拟环境管理等功能。poetry使用pyproject.toml文件来定义项目配置和依赖，这是一个更结构化的方式。

poetry的依赖解析算法比pip更智能，它可以更好地处理版本冲突，确保所有依赖都能兼容。poetry还会生成poetry.lock文件，这个文件锁定了所有依赖的精确版本，包括传递依赖。这确保了在不同环境中安装的依赖完全一致，提高了项目的可重现性。

使用poetry创建新项目很简单，只需要运行poetry new project_name或poetry init。poetry会自动创建项目结构，包括pyproject.toml文件。我们可以使用poetry add package_name来添加依赖，使用poetry install来安装依赖。poetry还会自动管理虚拟环境，我们不需要手动创建和激活虚拟环境。

另一个流行的依赖管理工具是pip-tools，它提供了requirements.in和requirements.txt的分离。我们可以在requirements.in中定义项目的直接依赖，然后使用pip-compile来生成包含所有传递依赖的requirements.txt。这种方式结合了requirements.txt的简单性和现代工具的便利性。

对于FastAPI项目，选择哪种依赖管理工具主要取决于项目规模和团队偏好。对于小型项目，pip和requirements.txt可能就足够了。对于大型项目或团队项目，poetry或pip-tools可能提供更好的体验。无论选择哪种工具，重要的是保持一致性，确保所有团队成员使用相同的工具和流程。

FastAPI的安装与配置

安装FastAPI本身是一个相对简单的过程，但我们需要理解FastAPI的依赖生态系统，以及如何正确配置FastAPI应用。FastAPI不是一个孤立的框架，它依赖于多个其他库，每个库都有其特定的作用。理解这些依赖关系有助于我们更好地使用FastAPI，并在遇到问题时能够快速定位和解决。

FastAPI核心包的安装

安装FastAPI最直接的方法是使用pip：pip install fastapi。这个命令会安装FastAPI及其核心依赖。FastAPI的主要依赖包括Starlette和Pydantic。Starlette是一个轻量级的ASGI框架，FastAPI基于Starlette构建，继承了Starlette的高性能和异步支持。Pydantic是一个数据验证库，FastAPI使用Pydantic来进行请求和响应的数据验证和序列化。

除了核心包，我们通常还需要安装一个ASGI服务器来运行FastAPI应用。虽然FastAPI本身是一个ASGI应用，但它不包含服务器。我们需要一个ASGI服务器来运行应用。最流行的选择是uvicorn，这是一个高性能的ASGI服务器，专为Python异步应用设计。安装uvicorn也很简单：pip install uvicorn。

对于开发环境，我们可能还需要安装一些额外的工具。例如，我们可以安装python-multipart来支持文件上传，安装email-validator来验证邮箱地址。这些不是FastAPI的核心依赖，但如果我们使用相关功能，就需要安装它们。FastAPI的文档会明确说明哪些功能需要哪些额外的依赖。

在安装FastAPI时，我们需要注意版本兼容性。FastAPI的版本应该与Python版本兼容，也应该与Starlette和Pydantic的版本兼容。通常，安装最新版本的FastAPI会自动安装兼容的依赖版本，但如果我们使用较旧的Python版本，可能需要安装较旧版本的FastAPI。

uvicorn服务器的配置

uvicorn是运行FastAPI应用的标准服务器，理解如何配置uvicorn对于开发和部署都很重要。最基本的运行方式是使用命令行：uvicorn main:app --reload，其中main是包含FastAPI应用的Python文件，app是FastAPI实例的名称，--reload选项会在代码改变时自动重启服务器，这对于开发非常有用。

uvicorn提供了许多配置选项，我们可以通过命令行参数或配置文件来设置。例如，我们可以使用--host参数来指定服务器绑定的主机地址，使用--port参数来指定端口号，使用--workers参数来指定工作进程数。对于生产环境，我们通常需要多个工作进程来处理并发请求，但对于开发环境，单个进程就足够了。

uvicorn还支持通过配置文件来设置选项，这对于复杂的配置更加方便。我们可以创建一个uvicorn配置文件，使用TOML或YAML格式，然后在启动时指定配置文件。这种方式使得配置更加清晰，也更容易管理不同环境的配置。

除了命令行和配置文件，我们还可以在代码中配置uvicorn。我们可以创建一个启动脚本，使用uvicorn的Python API来启动服务器。这种方式提供了最大的灵活性，我们可以在启动前执行一些初始化操作，比如加载配置、连接数据库等。

开发依赖的安装

在开发过程中，我们通常需要一些额外的工具来提升开发体验。这些工具不是应用运行所必需的，但对于开发很有帮助。例如，我们可以安装代码格式化工具black，它可以帮助我们保持代码风格的一致性。安装linter工具flake8或pylint可以帮助我们发现代码中的问题。安装测试框架pytest可以帮助我们编写和运行测试。

这些开发工具通常不会安装到生产环境，因此我们需要区分开发依赖和生产依赖。使用requirements.txt时，我们可以创建两个文件：requirements.txt用于生产依赖，requirements-dev.txt用于开发依赖。在安装时，我们可以先安装生产依赖，然后在开发环境中安装开发依赖。

使用poetry时，我们可以使用poetry add --dev package_name来添加开发依赖。poetry会在pyproject.toml中区分开发依赖和生产依赖，在安装时可以选择只安装生产依赖或同时安装开发依赖。这种区分使得依赖管理更加清晰，也避免了在生产环境中安装不必要的包。

开发工具的配置

选择合适的开发工具并正确配置它们，可以显著提升我们的开发效率。现代IDE和编辑器提供了许多有用的功能，比如代码补全、语法高亮、错误检查、调试支持等。对于FastAPI开发，我们需要确保这些工具能够充分利用Python的类型提示和FastAPI的特性。

代码编辑器的选择

选择代码编辑器是个人偏好的问题，但有一些编辑器对Python和FastAPI开发特别友好。VS Code是一个流行的选择，它是免费的、跨平台的，并且有丰富的Python扩展。VS Code的Python扩展提供了代码补全、类型检查、调试等功能，对于FastAPI开发非常有用。VS Code还支持Jupyter Notebook，这对于数据分析和原型开发很有帮助。

PyCharm是另一个流行的选择，特别是对于专业Python开发。PyCharm提供了强大的代码分析、重构工具、调试器等功能。PyCharm的专业版还提供了Web框架支持，包括FastAPI。虽然PyCharm是商业软件，但它也提供了免费的社区版，对于大多数开发任务已经足够。

无论选择哪个编辑器，重要的是要配置好Python解释器。编辑器需要知道使用哪个Python解释器，这样才能提供准确的代码补全和错误检查。通常，我们应该选择项目虚拟环境中的Python解释器，这样编辑器就能访问项目中安装的包，提供正确的代码补全。

代码格式化工具的使用

代码格式化工具可以帮助我们保持代码风格的一致性，这对于团队开发特别重要。black是Python社区最流行的代码格式化工具，它采用"无妥协"的方式，自动格式化代码，不需要我们手动调整。black的格式化规则是固定的，这消除了关于代码风格的争论，让团队可以专注于代码逻辑。

使用black很简单，我们可以通过命令行运行black .来格式化当前目录下的所有Python文件。black还提供了许多选项，比如指定行长度、是否格式化字符串等。我们可以在项目根目录创建pyproject.toml文件来配置black的选项，这样团队成员都会使用相同的配置。

除了black，还有其他格式化工具，比如autopep8和yapf。autopep8基于PEP 8风格指南，yapf提供了更多的配置选项。但对于大多数项目，black已经足够使用，它的简单性和一致性使其成为首选。

代码检查工具的应用

代码检查工具（linter）可以帮助我们发现代码中的潜在问题，比如未使用的变量、可能的错误、代码风格问题等。flake8是一个流行的Python linter，它结合了pycodestyle、pyflakes和mccabe的功能。flake8可以检查PEP 8风格违规、语法错误、复杂度等问题。

使用flake8也很简单，我们可以运行flake8 .来检查当前目录下的所有Python文件。flake8会输出发现的问题，包括文件位置、行号、错误代码和描述。我们可以配置flake8忽略某些错误，或者在配置文件中设置规则。

pylint是另一个强大的linter，它提供了更深入的代码分析。pylint可以检查代码质量、设计问题、可能的bug等。pylint的输出更加详细，包括每个问题的严重程度和建议的修复方法。但是，pylint的检查可能过于严格，对于某些项目可能不太适用。

对于FastAPI项目，我们建议使用flake8作为主要的linter，因为它提供了良好的平衡，既能发现重要问题，又不会过于严格。我们可以在CI/CD流程中集成linter检查，确保提交的代码符合质量标准。

类型检查工具

Python的类型提示是FastAPI的核心特性之一，使用类型检查工具可以帮助我们确保类型提示的正确性。mypy是Python最流行的类型检查工具，它可以静态检查Python代码中的类型错误。mypy可以检查函数参数和返回值的类型、变量的类型、泛型的使用等。

使用mypy检查代码很简单，我们可以运行mypy .来检查当前目录下的所有Python文件。mypy会报告发现的类型错误，包括类型不匹配、缺少类型注解等问题。对于FastAPI项目，mypy特别有用，因为FastAPI大量使用类型提示，类型检查可以帮助我们及早发现错误。

配置mypy时，我们可以在mypy.ini或pyproject.toml文件中设置选项。我们可以配置mypy的严格程度，选择检查哪些类型的错误。对于新项目，我们建议使用较严格的配置，这样可以更好地利用类型提示的优势。对于现有项目，我们可以逐步增加严格程度，避免一次性修改太多代码。

除了mypy，还有其他类型检查工具，比如pyright。pyright是微软开发的类型检查工具，它提供了更快的检查速度和更好的IDE集成。VS Code的Pylance扩展就基于pyright。选择哪个工具主要取决于个人偏好和项目需求。

创建第一个FastAPI应用

现在我们已经搭建好了开发环境，安装了必要的工具和依赖，是时候创建我们的第一个FastAPI应用了。这个简单的应用将帮助我们理解FastAPI的基本概念和工作方式，为后续的深入学习打下基础。

项目结构的规划

在开始编写代码之前，我们应该规划好项目结构。虽然对于简单的应用，所有代码可以放在一个文件中，但良好的项目结构有助于代码的组织和维护。一个典型的FastAPI项目结构包括项目根目录、源代码目录、测试目录、配置文件等。

项目根目录通常包含项目的配置文件，比如requirements.txt、README.md、.gitignore等。源代码可以放在一个单独的目录中，比如app或src。这种结构使得项目更加清晰，也便于后续的扩展。对于大型项目，我们可能还需要将代码进一步组织成模块，每个模块负责特定的功能。

创建项目目录后，我们应该初始化git仓库，这样可以跟踪代码的变化。我们还需要创建.gitignore文件，排除不需要版本控制的文件，比如虚拟环境目录、Python缓存文件、IDE配置文件等。这可以保持仓库的整洁，避免提交不必要的文件。

编写第一个API端点

创建FastAPI应用的第一步是导入FastAPI类并创建应用实例。我们可以创建一个名为main.py的文件，然后编写以下代码：

|
from fastapi import FastAPI
 
app = FastAPI()

这行代码创建了一个FastAPI应用实例。app变量是我们应用的入口点，我们将在后续的代码中使用它来定义路由和处理函数。

接下来，我们可以定义第一个API端点。在FastAPI中，我们使用装饰器来定义路由。例如，我们可以创建一个简单的根路径端点：

|
@app.get("/")
def read_root():
    return {"Hello": "World"}

这个函数定义了一个GET请求处理器，当客户端访问根路径时，会返回一个JSON响应。FastAPI会自动将Python字典转换为JSON格式，这是FastAPI的便利特性之一。

我们还可以创建带路径参数的端点。例如，我们可以创建一个返回用户信息的端点：

|
@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

这个端点接受一个路径参数user_id，类型是整数。FastAPI会自动验证参数类型，如果客户端传递了非整数类型的值，FastAPI会返回422错误，并提供详细的错误信息。这种自动验证是FastAPI的强大特性之一，它基于Python的类型提示，不需要我们编写额外的验证代码。

运行和测试应用

编写完代码后，我们需要运行应用来测试它。使用uvicorn运行应用很简单，我们可以在项目根目录运行以下命令：

|
uvicorn main:app --reload

这个命令会启动uvicorn服务器，加载main.py文件中的app实例，并启用自动重载功能。自动重载意味着当我们修改代码时，服务器会自动重启，应用更改。这对于开发非常有用，我们不需要手动重启服务器。

服务器启动后，我们可以通过浏览器访问http://127.0.0.1:8000来查看应用。FastAPI会自动生成API文档，我们可以访问http://127.0.0.1:8000/docs来查看Swagger UI，或者访问http://127.0.0.1:8000/redoc来查看ReDoc。这些文档是自动生成的，基于我们的代码和类型提示，不需要我们手动编写。

除了通过浏览器测试，我们还可以使用命令行工具如curl来测试API。例如，我们可以运行curl http://127.0.0.1:8000/来测试根路径端点。对于更复杂的测试，我们可以使用专门的API测试工具，比如Postman或HTTPie。这些工具提供了更友好的界面和更多的功能，比如保存请求、组织测试集合等。

理解FastAPI的工作流程

虽然我们的第一个应用很简单，但它已经展示了FastAPI的核心工作流程。当客户端发送请求时，请求首先到达uvicorn服务器。uvicorn是一个ASGI服务器，它实现了ASGI协议，这是Python异步Web应用的标准接口。

uvicorn接收到请求后，会将请求传递给FastAPI应用。FastAPI应用根据请求的路径和方法，找到对应的处理函数。FastAPI使用路由系统来匹配请求，路由系统会考虑路径参数、查询参数、请求体等因素。

找到处理函数后，FastAPI会进行数据验证和转换。如果处理函数有类型提示，FastAPI会使用Pydantic来验证请求数据，确保数据符合类型要求。如果验证失败，FastAPI会返回详细的错误信息。如果验证成功，FastAPI会将数据传递给处理函数。

处理函数执行后，返回响应数据。FastAPI会将响应数据序列化为JSON格式，并设置适当的HTTP头部。如果处理函数返回的是Pydantic模型，FastAPI会使用模型的序列化规则。如果返回的是Python字典或基本类型，FastAPI会自动转换为JSON。

最后，响应通过uvicorn返回给客户端。整个过程中，FastAPI和uvicorn都支持异步操作，这意味着它们可以高效地处理大量并发请求。这是FastAPI性能优势的重要来源。

小结

通过这一部分的学习，我们已经完成了开发环境的搭建，安装了FastAPI及其依赖，创建了第一个FastAPI应用。在下一个部分中，我们将深入学习FastAPI的核心特性，探索如何构建更复杂的API应用。