Skip to content

示例:最小可运行应用 ​

一个文件、一个端点、一条命令就能跑起来。这个示例用来验证环境装好了没有,也是全书所有代码的起点。


学习目标 ​

  • 能在 5 分钟内把 FastAPI 应用跑起来
  • 理解 uvicorn / fastapi dev 与 app 对象三者之间的关系
  • 会用 curl 与 /docs 两种方式验证接口

目录结构 ​

text
hello/
├── README.md          # 本文件
├── pyproject.toml     # 依赖声明(fastapi[standard])
└── main.py            # 唯一源码文件

单文件就够:这一步不涉及数据库、不需要分层,先确认工具链能用。


安装与启动 ​

bash
cd examples/hello

# 方式一:uv(推荐,自动建虚拟环境)
uv run fastapi dev main.py

# 方式二:已有环境,直接装依赖
pip install "fastapi[standard]"
uvicorn main:app --reload --port 8000

fastapi dev 是 FastAPI CLI 提供的开发模式:自动热重载、默认监听 127.0.0.1:8000。生产用它对应的 fastapi run,不带 --reload。


代码全文 ​

python
# main.py
from fastapi import FastAPI

app = FastAPI(
    title="Hello API",
    description="最小可运行的 FastAPI 应用",
    version="0.1.0",
)


@app.get("/", summary="根路径")
async def read_root() -> dict[str, str]:
    return {"message": "Hello, FastAPI!"}


@app.get("/health", summary="健康检查")
async def health() -> dict[str, str]:
    return {"status": "ok"}

三行的信息量:

代码作用
app = FastAPI(...)创建 ASGI 应用实例,title / description / version 会显示在 /docs 上
@app.get("/")注册路由:HTTP 方法 + 路径
async def异步处理函数;不涉及阻塞 I/O 时 def 也能跑,第 13 章会讲清区别
返回值注解 -> dict[str, str]FastAPI 据此生成响应 Schema,出现在 /docs 里

预期输出 ​

启动成功的终端输出(截取关键行):

text
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

修改 main.py 并保存,应看到 WatchFiles detected changes ... Reloading —— 说明热重载生效。


验证步骤 ​

1. 用 curl 调接口 ​

bash
curl -i http://127.0.0.1:8000/

预期:

text
HTTP/1.1 200 OK
content-type: application/json

{"message":"Hello, FastAPI!"}
bash
curl -i http://127.0.0.1:8000/health

预期:

text
HTTP/1.1 200 OK
content-type: application/json

{"status":"ok"}

2. 访问交互文档 ​

地址说明
http://127.0.0.1:8000/docsSwagger UI,可直接点击 "Try it out" 发请求
http://127.0.0.1:8000/redocReDoc,阅读型的接口文档
http://127.0.0.1:8000/openapi.jsonOpenAPI Schema 原文,可导入 Postman / 生成 SDK

在 /docs 里应能看到两个端点,且 "Schemas" 区域列出了 HTTPValidationError 与 ValidationError(FastAPI 自动加上)。

3. 确认 404 行为 ​

bash
curl -i http://127.0.0.1:8000/nope

预期 404 Not Found,响应体为 {"detail":"Not Found"}。这就是第 8 章要展开的统一错误结构的最小形态。


下一步 ​


👉 返回课程目录

本文阅读--次|全站访问--次|访客--人