第一个 API：从 Hello World 到本地运行
本教程共 50 篇 · 第 4 篇 · 更新于 2026-08-12 · 约 7 分钟阅读
本节目标：亲手写出最小可运行的 FastAPI 应用，并把它在本地跑起来，用浏览器看到返回结果。
4-1 新建一个 main.py
在之前建好的项目目录（已激活 venv）里，新建一个名为 main.py 的文件。
后面的代码就写在这个文件里。文件名用 main.py 是惯例，FastAPI 的命令行工具也最容易找到它。
Tip你可以用任意编辑器（VS Code、PyCharm 甚至记事本）创建这个文件。保持目录干净，只放项目相关文件即可。
4-2 最小应用长什么样
把下面这 6 行代码原样写进 main.py：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}别看它短，这已经是一个完整能跑的 FastAPI 接口了。下面一行行拆开讲。
4-3 逐行拆解：导入与实例
第一行：
from fastapi import FastAPI这是把 FastAPI 这个类从库里导入进来。它提供了框架的全部能力。
第三行：
app = FastAPI()这里创建了 app 这个实例。它是你整个接口服务的”总入口”，以后定义路由、配置文档，都围着它转。
变量名用 app 是约定俗成。FastAPI 的命令行工具默认就会去找名为 app 的实例。
Note和 Flask 不同，FastAPI 创建实例时不需要传
__name__参数。直接FastAPI()即可。
4-4 逐行拆解：路径操作装饰器
第六行：
@app.get("/")这行叫做”路径操作装饰器”。它干了两件事：指定路径是根路径 /，指定 HTTP 方法是 GET。
“路径”指 URL 里从第一个斜杠开始的部分。比如 https://x.com/items/1 的路径就是 /items/1。
“操作”指 HTTP 方法。GET 一般用来表示”读取数据”。FastAPI 还支持 POST、PUT、DELETE 等，写法类似 @app.post("/")。
Tip装饰器
@app.get("/")就像一个帽子，扣在下面那个函数上，告诉 FastAPI：有人用 GET 访问/时，就交给这个函数处理。
4-5 逐行拆解：路径操作函数
第七、八行：
async def root():
return {"message": "Hello World"}这是”路径操作函数”。每当有人 GET /，FastAPI 就调用它。函数名 root 可随便起，但起个有意义的名字更清晰。
这里用了 async def，也就是异步函数。这是 FastAPI 推荐的默认写法，能更好地处理并发。
函数返回一个字典。FastAPI 会自动把它转成 JSON 响应发给客户端。你也能返回 list、字符串、数字，甚至 Pydantic 模型，框架都会自动序列化。
Note如果一定要做明显的阻塞操作（比如读大文件、调同步库），才用普通
def。入门阶段统一写async def就行。
4-6 关于 name == “main”
有些教程会在文件末尾加上一段：
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="127.0.0.1", port=8000)这段的作用是：当你直接执行 python main.py 时，用 Uvicorn 把应用跑起来。它叫”主程序守卫”。
但要注意，用官方推荐的 fastapi dev main.py 启动时，CLI 是直接 import 你的 app 实例的，并不会执行 python main.py，所以这段守卫其实是可选的。
Tip入门阶段推荐用
fastapi dev，不需要写__name__那段。等你熟悉后，把它加进去，就能用python main.py直接运行，两种方式都合法。
4-7 用 fastapi dev 跑起来
保存 main.py，在终端（已激活 venv）执行：
fastapi dev main.py你会看到类似输出：
FastAPI Starting development server 🚀
server Server started at http://127.0.0.1:8000
server Documentation at http://127.0.0.1:8000/docs
INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO Application startup complete.fastapi dev 是开发模式，带热重载：你改了代码，服务器会自动重启，不用手动关了再开。
4-8 等价的 uvicorn 命令
如果你更习惯 Uvicorn 原生命令，下面这条和 fastapi dev 效果一致：
uvicorn main:app --reloadUvicorn 是服务器名；main:app 表示”从 main.py 文件里找 app 实例”；--reload 同样是开发热重载。
fastapi dev 本质就是对 Uvicorn 的一层友好封装，二者选其一即可。新手我推荐前者，提示更友好。
Note生产环境不要用
--reload，也不能用fastapi dev。上线请改用fastapi run main.py（等价uvicorn main:app）。这章只讲本地开发。
4-9 用浏览器看结果
服务器跑起来后，打开浏览器访问：
http://127.0.0.1:8000页面会显示一段 JSON：
{"message": "Hello World"}这就说明你的第一个接口成功返回数据了。地址里的 127.0.0.1 是”本机”，8000 是默认端口。
Tip想停止服务器，回到终端按
Ctrl + C即可。重新运行再敲一遍fastapi dev main.py。
4-10 用接口工具访问（可选）
除了浏览器，你也能用命令行 curl 或接口测试工具发请求，更接近真实调用：
curl http://127.0.0.1:8000返回：
{"message":"Hello World"}这种直接拿 JSON 的方式，在写前端联调、做自动化测试时非常常用。
4-11 端口被占用怎么办
有时启动会报错，说地址 8000 已经被占用。多半是上次的服务没关干净，或别的程序占用了。
最简单的解法：回到终端按 Ctrl + C 关掉旧服务，再重新运行一次。
如果想换一个端口，用 --port 指定即可：
fastapi dev main.py --port 8080这样服务就跑在 http://127.0.0.1:8080，访问和测试时记得用新端口。
Tip改了端口后，对应的
/docs、/redoc也要换成新端口访问，比如http://127.0.0.1:8080/docs。
4-12 小结与下一步
恭喜，你已经跑通了人生第一个 FastAPI 接口。回顾今天的关键点：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}运行只需一句 fastapi dev main.py，等价于 uvicorn main:app --reload。
你也许注意到了启动日志里提到了 http://127.0.0.1:8000/docs。下一章，我们就揭开这个地址的神秘面纱——FastAPI 自动生成的互动文档。