FastAPI 新手入门第 1 篇：第一个接口

这一篇先不讲数据库、登录、项目分层，也不急着解释一堆后端概念。

先做一件很小的事：写一个 FastAPI 接口，把服务启动起来，然后在浏览器里看到它返回 JSON。

只要这一步跑通，后面的参数、请求体、数据校验、错误处理都会更好理解。因为你已经知道一件事：Python 函数可以变成一个能被浏览器访问的接口。

先准备一个最小项目

我会把这个系列的示例代码放在 fastapi-beginner-lab 这个项目里。第一篇的目录很简单：

fastapi-beginner-lab/ app/ __init__.py main.py pyproject.toml

这里先不用关心复杂目录。app/main.py放接口代码，pyproject.toml放项目依赖。

安装 FastAPI

先写pyproject.toml。这一段只做一件事：告诉 Python 项目需要fastapi[standard]。

[project] name = "fastapi-beginner-lab" version = "0.1.0" description = "Example project for a FastAPI beginner tutorial series." requires-python = ">=3.10" dependencies = [ "fastapi[standard]>=0.115.0", ] [tool.fastapi] entrypoint = "app.main:app"

fastapi[standard]会安装 FastAPI 常用的标准依赖，也包括后面要用到的fastapi命令。entrypoint = "app.main:app"的意思是：FastAPI 应用对象在app/main.py文件里的app变量上。

接着创建虚拟环境并安装依赖，只需要依次输入下面三行命令：

python-m venv.venv.\.venv\Scripts\Activate.ps1 python-m pip install-e.

如果你看到安装过程正常结束，就可以开始写接口了。

写第一个接口

这段代码只需要看三个位置：FastAPI()创建应用，@app.get("/")声明访问路径，return决定返回给浏览器的数据。

fromfastapiimportFastAPI app=FastAPI()@app.get("/")defread_root():return{"message":"Hello FastAPI"}@app.get("/ping")defping():return{"message":"pong"}

这就是第一版后端服务。它有两个接口：

• GET /：返回{"message": "Hello FastAPI"}。
• GET /ping：返回{"message": "pong"}，用来确认服务还活着。

这里的返回值是 Python 字典。FastAPI 会把它转换成 JSON 响应，浏览器看到的就是一段 JSON。

把服务跑起来

在fastapi-beginner-lab目录下运行：

$env:PYTHONIOENCODING ="utf-8"$env:PYTHONUTF8 ="1"fastapi dev app/main.py

前两行是给 Windows 终端准备的。FastAPI 的启动日志里可能会输出 emoji，如果终端还在使用 GBK 编码，可能会遇到UnicodeEncodeError。先把当前终端的 Python 输出切到 UTF-8，会少掉这个坑。

正常启动后，终端里会出现类似这样的地址：

http://127.0.0.1:8000

打开浏览器访问：

http://127.0.0.1:8000/

应该能看到：

{"message":"Hello FastAPI"}

再访问：

http://127.0.0.1:8000/ping

应该能看到：

{"message":"pong"}

到这里，第一个接口已经跑起来了。

打开自动生成的接口文档

FastAPI 还会自动生成一个接口调试页面。访问：

http://127.0.0.1:8000/docs

你会看到两个接口：GET /和GET /ping。

点开GET /ping，再点Try it out和Execute，页面里会显示请求地址、状态码和响应内容。这个页面背后用的是 Swagger UI，但现在不用急着记这个名字。

先记住它的用途：不用额外安装 Postman，也能在浏览器里调用接口。

看一眼 openapi.json

还有一个地址值得看一下：

http://127.0.0.1:8000/openapi.json

这个地址会返回一大段 JSON。它描述了当前服务有哪些接口、每个接口支持什么方法、可能返回什么结果。

/docs页面就是根据这份 JSON 生成的。也就是说，FastAPI 不只是帮我们写了一个调试页面，它还把接口信息整理成了一份机器能读懂的说明书。

这一点后面会很有用。前端、测试工具、接口文档工具，都可以围绕这份说明书工作。

这几行代码做了什么

现在回头看app/main.py，第一篇只需要理解这几行：

app=FastAPI()@app.get("/ping")defping():return{"message":"pong"}

app = FastAPI()创建了一个应用对象。后面所有接口都会挂到这个对象上。

@app.get("/ping")表示：当浏览器用GET方法访问/ping时，FastAPI 会执行下面的ping()函数。

return {"message": "pong"}是接口返回的数据。FastAPI 会把 Python 字典转换成 JSON。

这就是最小的 FastAPI 工作方式：路径对应函数，函数返回数据。

动手改一下

现在给自己留一个很小的改动：新增一个/hello接口。

在app/main.py里加上这段代码：

@app.get("/hello")defhello():return{"message":"hello fastapi"}

保存后不用手动重启服务。fastapi dev会监听文件变化，通常会自动重新加载。

打开：

http://127.0.0.1:8000/docs

如果你能在页面里看到GET /hello，并且点Execute后拿到下面的响应，这一篇就算学完：

{"message":"hello fastapi"}

下一篇我们继续往这个项目里加东西：让接口接收 URL 里的参数。到那时，你会看到浏览器地址栏里的数字，怎么变成 Python 函数里的变量。