示例:最小可运行应用
一个文件、一个端点、一条命令就能跑起来。这个示例用来验证环境装好了没有,也是全书所有代码的起点。
学习目标
- 能在 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 8000fastapi 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/docs | Swagger UI,可直接点击 "Try it out" 发请求 |
| http://127.0.0.1:8000/redoc | ReDoc,阅读型的接口文档 |
| http://127.0.0.1:8000/openapi.json | OpenAPI 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 章要展开的统一错误结构的最小形态。
下一步
- 想加路径参数、查询参数 → 第 3 章:路由与路径/查询参数
- 想接收 JSON 请求体 → 第 4 章:请求体与 Pydantic 模型
- 想按工程结构组织 →
crud-api
👉 返回课程目录