从零搭建个人 API 服务:用 FastAPI 实现接口开发与部署

本文适合第一次接触 Web API 的 Python 开发者。示例基于 Python 3.9 及以上版本,最终会得到一个可以在本地运行、测试并查看自动文档的健康检查服务

730技术分享5573 字
从零搭建个人 API 服务:用 FastAPI 实现接口开发与部署

当一个脚本需要被浏览器、桌面程序或其他服务调用时,把功能封装成 API 往往比反复执行命令更方便。API 可以接收请求、处理数据,再用统一格式返回结果,是不同程序之间常见的协作方式。

FastAPI 是一个现代 Python Web 框架。它支持类型提示、参数校验和异步处理,还能根据代码自动生成接口文档。即使只写少量代码,也能快速搭建一个结构清楚的服务。

本文所说的“部署”是指把 API 作为一个稳定的本地服务运行,不涉及 Docker、Nginx 或公网服务器。

开发模式适合边写边调试,部署模式更适合持续运行。两者不应该使用完全相同的启动参数。

FastAPI Logo


一、先认识这个示例

我们将创建一个名为 Personal Health API 的服务,它包含两个手动编写的接口:

请求方式地址用途
GET/返回服务说明和文档入口
GET/health返回服务当前状态、名称和版本

FastAPI 还会自动提供以下地址:

地址内容
/docsSwagger UI 交互式接口文档
/redocReDoc 风格接口文档
/openapi.jsonOpenAPI 格式的接口描述

健康检查接口看起来很简单,但它在真实项目中十分常见。监控程序可以定期请求这个地址,判断服务是否仍然能够响应。

这个示例不需要保存业务数据,因此不连接数据库。服务关闭后也没有需要保留的运行状态,适合用来学习 FastAPI 的最小开发流程。


二、准备 Python 环境

先新建一个空目录,并进入该目录:

POWERSHELL
mkdir personal-apicd personal-api

为了避免依赖与其他 Python 项目互相影响,建议创建虚拟环境。

Windows PowerShell

POWERSHELL
python -m venv .venv.\.venv\Scripts\Activate.ps1python -m pip install --upgrade pippython -m pip install fastapi "uvicorn[standard]"

Linux 和 macOS

BASH
python3 -m venv .venvsource .venv/bin/activatepython -m pip install --upgrade pippython -m pip install fastapi "uvicorn[standard]"

安装完成后,可以执行下面的命令确认环境中的包:

BASH
python -m pip show fastapi uvicorn

其中,FastAPI 负责定义接口和处理请求,Uvicorn 负责启动 ASGI 服务。可以把前者理解为应用本身,把后者理解为让应用真正监听端口的运行器。


三、编写第一个 FastAPI 服务

在项目目录中新建 main.py,写入以下代码:

PYTHON
from typing import Literal from fastapi import FastAPIfrom pydantic import BaseModel app = FastAPI( title="Personal Health API", description="一个用于演示 FastAPI 开发流程的健康检查服务", version="1.0.0",)

代码中的 app = FastAPI(...) 创建了应用实例,@app.get(...) 则把 Python 函数注册为一个 GET 接口。客户端访问对应地址时,FastAPI 会调用函数并把返回值转换成 JSON。

HealthResponse 是接口的响应模型。它明确规定 /health 必须返回哪些字段以及字段类型。Literal["ok"] 进一步限制了 status 的值,让代码、校验规则和自动文档保持一致。

这里最值得注意的不是代码量,而是类型提示同时参与了开发、校验和文档生成。


四、以开发模式启动服务

确保终端位于 main.py 所在目录,然后执行:

BASH
python -m uvicorn main:app --reload

命令中的参数分别表示:

  • main:文件名 main.py 去掉扩展名后的模块名。
  • app:代码中创建的 FastAPI 应用变量。
  • --reload:文件变化后自动重启,适合开发阶段。

正常启动后,终端会显示类似内容:

TEXT
Uvicorn running on http://127.0.0.1:8000

在浏览器中打开 http://127.0.0.1:8000/,应该能看到:

JSON
{ "message": "Personal API is running", "docs": "/docs"}

再访问 http://127.0.0.1:8000/health,响应如下:

JSON
{ "status": "ok", "service": "personal-api", "version": "1.0.0"}

需要停止服务时,在运行 Uvicorn 的终端中按 Ctrl+C。


五、使用自动生成的接口文档

打开 http://127.0.0.1:8000/docs,可以看到 FastAPI 自动生成的 Swagger UI。展开 GET /health,点击 Try it out,再点击 Execute,页面就会发送真实请求并显示响应状态、响应头和 JSON 内容。

如果更喜欢偏阅读型的文档,可以访问 http://127.0.0.1:8000/redoc。这两份文档都来自 http://127.0.0.1:8000/openapi.json,不需要手工维护接口清单。

自动文档带来了几个直接好处:

  • 开发者可以立即查看可用接口。
  • 前端或调用方可以确认请求与响应结构。
  • 修改响应模型后,文档会随代码一起更新。
  • 调试简单接口时,不必额外安装请求工具。

需要注意,自动文档只能描述代码中已经定义的规则。接口用途、调用限制和错误处理仍然应该写清楚,不能只依赖生成页面。


六、从终端验证接口

除了浏览器,还可以直接从命令行发送请求。

PowerShell

POWERSHELL
Invoke-RestMethod http://127.0.0.1:8000/health

输出类似:

TEXT
status service version------ ------- -------ok personal-api 1.0.0

如果希望在 Windows 中查看原始 JSON,可以调用系统自带的 curl.exe:

POWERSHELL
curl.exe http://127.0.0.1:8000/health

Linux 和 macOS

BASH
curl http://127.0.0.1:8000/health

还可以尝试访问一个不存在的地址:

BASH
curl http://127.0.0.1:8000/not-found

FastAPI 会返回 404 Not Found,响应体为:

JSON
{ "detail": "Not Found"}

这说明服务不仅能返回正常结果,也会用标准 HTTP 状态码表达错误。


七、以本地部署模式运行

开发时使用 --reload 很方便,但它会监视文件并额外启动重载进程,不适合长期运行。代码确认无误后,可以关闭开发服务,再用下面的命令启动本地部署实例:

BASH
python -m uvicorn main:app --host 127.0.0.1 --port 8000

这里没有使用 --reload,并且通过 --host 127.0.0.1 限制只有本机能够访问。只供个人电脑上的程序调用时,这是更稳妥的默认设置。

如果确实需要让同一局域网内的其他设备访问,可以改为:

BASH
python -m uvicorn main:app --host 0.0.0.0 --port 8000

0.0.0.0 表示监听所有网络接口,但它不是浏览器中要访问的地址。其他设备需要使用运行服务的电脑局域网 IP,例如 http://192.168.1.10:8000/health。

将监听地址改为 0.0.0.0 会扩大可访问范围,还可能触发系统防火墙提示。不要把没有身份认证和 HTTPS 的示例服务直接暴露到公网。

本地部署的基本流程如下:

  1. 激活创建项目时使用的虚拟环境。
  2. 确认当前目录中存在 main.py。
  3. 使用不带 --reload 的命令启动 Uvicorn。
  4. 请求 /health,确认返回状态为 ok。
  5. 保持终端运行,停止服务时按 Ctrl+C。

八、常见问题与排查方法

现象常见原因处理方法
找不到 python 命令Python 未安装或未加入环境变量重新安装 Python,Windows 也可尝试 py 命令
PowerShell 禁止运行激活脚本当前执行策略限制脚本为当前进程临时调整策略,或直接使用虚拟环境中的 Python
No module named uvicorn依赖安装到了另一个 Python 环境激活虚拟环境后使用 python -m pip install 安装
Could not import module "main"当前目录不对或文件名不匹配进入 main.py 所在目录并检查启动参数
端口已被占用另一个程序正在使用 8000停止占用程序,或改用 --port 8001
本机能访问,其他设备不能仍监听 127.0.0.1 或被防火墙拦截改为 0.0.0.0,并检查局域网和防火墙规则

如果 PowerShell 因执行策略无法激活虚拟环境,可以只为当前终端进程临时放行:

POWERSHELL
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.\.venv\Scripts\Activate.ps1

也可以不激活环境,直接调用其中的 Python:

POWERSHELL
.\.venv\Scripts\python.exe -m uvicorn main:app --reload

遇到启动错误时,优先检查三个位置:终端当前目录、Python 解释器路径和完整报错信息。反复重新安装全部软件通常不是最高效的排查方式。


九、完成检查清单

  • 创建并激活独立虚拟环境
  • 安装 FastAPI 和 Uvicorn
  • 编写根接口和健康检查接口
  • 使用响应模型约束 JSON 结构
  • 通过 /docs 调试接口
  • 使用终端发送请求
  • 区分开发模式与本地部署模式
  • 根据真实项目增加身份认证
  • 为业务数据接入数据库
  • 上公网前配置 HTTPS 和访问控制

十、下一步可以学什么

完成健康检查接口后,可以继续添加路径参数、查询参数和请求体。例如,个人笔记 API 可以使用 POST 接收新笔记,再通过 GET 查询内容。如果数据需要在服务重启后保留,就应该接入 SQLite、MySQL 等数据库,而不是只存放在内存中。

进一步学习时,可以参考以下官方资料:

当服务需要对公网开放时,还要继续考虑域名、HTTPS、身份认证、日志、进程守护和反向代理。这些内容属于生产部署范畴,不应直接照搬本文的本地运行命令。


总结

从创建虚拟环境、安装依赖,到编写接口、查看自动文档和启动 Uvicorn,一个最小 FastAPI 服务只需要很少的代码。但在这个过程中,我们已经接触了 API 路由、响应模型、HTTP 状态码、ASGI 服务器以及开发与部署模式的区别。

FastAPI 的优势不只是“启动快”,而是它能让类型提示、数据校验和接口文档围绕同一份代码协同工作。先用健康检查接口掌握完整流程,再逐步增加业务数据、数据库和身份认证,会比一开始堆叠大量功能更容易理解和维护。

一个能够稳定启动、正确响应并方便验证的小接口,就是构建更大服务的可靠起点。

评论

0

登录后参与评论

登录

暂无评论