第一个应用

这是什么：本章写出你的第一个 FastAPI 应用：4 行 Python 起一个真服务，浏览器访问返回 JSON，还自带一个能点能试的交互文档页面。

为什么用：跑通第一个应用，后面所有概念才有落脚点；而且 FastAPI 的招牌体验——/docs 自动文档——从第一分钟就能感受到。

如何用：先在 venv 里装好 fastapi 和 uvicorn 两个包，写一个 main.py，一条命令启动，浏览器里亲自点一遍。

安装：两个包就够了

按虚拟环境教程给项目建好 venv，然后：

pip install fastapi uvicorn

包	角色
`fastapi`	框架本体：路由、校验、文档都靠它
`uvicorn`	服务器：把你的应用真正跑在网络上的「发动机」

FastAPI 只负责「定义应用」，网络监听交给 ASGI 服务器，uvicorn 就是标准选择（对应 Flask 自带的 werkzeug 角色）。

写代码：4 行的 Hello World

新建 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def hello():
    return {"message": "Hello FastAPI"}

逐行拆解：

行	作用
`from fastapi import FastAPI`	引入框架主类
`app = FastAPI()`	创建应用实例（所有路由都挂在它身上）
`@app.get("/")`	装饰器：把下面的函数挂到「GET /」这个路由上
`return {"message": ...}`	返回 dict，FastAPI 自动转成 JSON 发给浏览器

注意对比 Flask：这里是 @app.get("/") 而不是 @app.route("/")——方法直接写进装饰器名，@app.post、@app.put、@app.delete 以此类推。

跑起来：uvicorn main:app --reload

uvicorn main:app --reload

「你会看到」：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345]
INFO:     Application startup complete.

这条命令的三个部分：

部分	含义
`main:app`	「文件名：变量名」——`main.py` 里的 `app` 变量就是应用
`--reload`	改代码自动重启服务（只用于开发，上线不带它）
默认端口	`8000`，想换就加 `--port 8001`

见证魔法：浏览器里点两处

第 1 处：打开 http://127.0.0.1:8000/，你会看到：

{"message":"Hello FastAPI"}

第 2 处：打开 http://127.0.0.1:8000/docs——自动生成的交互文档：你的接口列在页面上，点「Try it out」→「Execute」，不用写一行前端代码就能发请求、看响应。这不是你写的页面，是 FastAPI 根据代码自动生成的，以后每加一个接口它都会自动出现。

❓ 常见问题

Q1：报 'uvicorn' 不是内部或外部命令？

原因：uvicorn 装在 venv 里，但 venv 没激活，命令行找不到它。修复三步：① 确认终端提示符前有 (.venv) 之类的环境名；② 没激活就先跑激活命令（Windows：.venv\Scripts\activate）；③ 再跑 uvicorn main:app --reload。或者直接 python -m uvicorn main:app --reload，绕开 PATH 问题。

Q2：报 ModuleNotFoundError: No module named 'fastapi'？

原因：服务能启动说明 uvicorn 在，但 main.py 里 import fastapi 失败——十有八九是在另一个环境里装的包。修复三步：① 激活正确的 venv；② 在该环境里 pip install fastapi；③ 重新启动。venv 的意义就在这：一个项目一个世界（见虚拟环境教程）。

Q3：端口 8000 被占用，报 error while attempting to bind on address ('0.0.0.0', 8000)？

原因：别的程序（或你上次没关干净的 uvicorn）占着 8000。修复三步：① 换端口启动：uvicorn main:app --reload --port 8001；② 或找到旧进程杀掉；③ 浏览器访问时记得同步换端口。

记忆口诀：main 是文件 app 是名，reload 挂上自动醒；八千端口开 docs，接口文档自动型。

📝 本章小结

安装两个包：fastapi（框架）+ uvicorn（服务器）
4 行代码一个服务：FastAPI() 实例 + @app.get 挂路由 + 返回 dict 自动转 JSON
启动命令 uvicorn main:app --reload：文件名:变量名 + 热重载
/docs 自动交互文档是每章的试验场，以后写完接口先去那里点一遍

动手改

把返回值改成 {"message": "你好", "version": 1}，看 /docs 和页面怎么变
再加一个路由 @app.get("/about") 返回你的自我介绍，浏览器访问验证
故意把 main:app 写成 main:App 启动，看报什么错（大小写敏感，变量名要一致）

上一章：FastAPI 是什么 · 下一章：路由与参数 🐸