02. FastAPI 第一个程序与启动项目

一个请求怎样进入程序

浏览器发送 HTTP 请求 → Uvicorn 接收连接 → FastAPI 按方法和路径找到函数 → 函数返回数据 → 客户端收到响应。GET /hello 与 POST /hello 是两个不同的操作。

可运行的最小程序

完成上一篇依赖安装，在练习目录创建 main.py：

from fastapi import FastAPI

app = FastAPI(title="我的第一个 API", version="1.0.0")

@app.get("/")
def home():
    return {"message": "你好，FastAPI"}

@app.get("/health")
def health():
    return {"status": "ok"}

在 main.py 所在目录启动：

uv run uvicorn main:app --reload --host 127.0.0.1 --port 8000

main:app 表示导入 main.py 里的 app 对象；不是文件路径。--reload 会在修改文件后重启开发进程。按 Ctrl+C 停止。也可以使用 uv run fastapi dev main.py，本系列统一用 Uvicorn 命令，便于理解模块入口。

访问 http://127.0.0.1:8000/，应看到 {"message":"你好，FastAPI"}。随后访问 /docs 操作交互文档，访问 /openapi.json 查看接口描述。PowerShell 验证：

Invoke-RestMethod http://127.0.0.1:8000/health
curl.exe -i http://127.0.0.1:8000/health

逐行理解代码

FastAPI() 创建应用；@app.get("/") 注册路由；函数叫 home 还是 index 不影响 URL。返回字典时，框架会生成 JSON 响应。中文在传输中使用 UTF-8，显示为转义形式也可能是等价 JSON。

一次响应包括状态码、响应头和正文。常见状态码：200 成功，201 创建成功，204 成功且无正文，400 请求有误，401 未通过认证，403 权限不足，404 资源不存在，422 参数校验失败，500 服务端错误。

启动失败时怎么排查

1. Could not import module：确认当前目录和 main.py 文件名。
2. 找不到 app：确认变量名与冒号后名称一致。
3. 端口被占用：先找出已有服务，或改为 --port 8001。
4. /hello 返回 404：检查实际注册的路径、前缀以及是否启动了另一个项目。
5. 浏览器打开 / 正常而 POST 不会发：地址栏只适合 GET，用 /docs 发其他方法。

127.0.0.1 只允许本机访问；0.0.0.0 是监听所有网卡的地址，浏览器仍应使用实际 IP。学习阶段先使用本机监听。

通过 uvicorn.run 在代码中启动

除了命令行方式，也可以在 main.py 中直接调用 uvicorn.run() 启动，便于调试（比如在 IDE 中打断点）：

from fastapi import FastAPI
import uvicorn

app = FastAPI(title="我的第一个 API", version="1.0.0")

@app.get("/")
def home():
    return {"message": "你好，FastAPI"}

@app.get("/health")
def health():
    return {"status": "ok"}

if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

然后像普通脚本一样运行：

uv run python main.py

说明：

• 第一个参数 "main:app" 同样是模块路径，不是文件路径；写成字符串是为了让 reload=True 生效。
• 如果不需要热重载，也可以直接传对象：uvicorn.run(app, host="127.0.0.1", port=8000)。
• 生产环境一般用命令行 uvicorn main:app --host 0.0.0.0 --port 8000 或结合进程管理器启动，uvicorn.run 更适合开发和调试。

练习：增加 GET /about，返回项目名和作者；观察改动后终端自动重载，并分别验证存在和不存在的 URL。