25｜FastAPI 安装与第一个接口

前端用 fetch 调用接口，背后是一个正在运行的服务进程——监听端口、接收 HTTP 请求、处理后返回 JSON。这个服务进程可以用很多方式写，FastAPI 是 Python 生态里写这类接口最主流的框架之一。这篇从安装环境开始，写出第一个能响应 HTTP 请求的接口。

一、为什么用框架

不借助任何框架，用 Python 标准库也能写一个 HTTP 服务：

from http.server import HTTPServer, BaseHTTPRequestHandler

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(b'{"message": "hello"}')

HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()

能跑，但问题马上来：一个 URL 对应一个 if self.path == "/articles" 分支，JSON 序列化手动写，请求体手动解析，跨域手动处理，参数校验手动判断。接口一多，代码全是这些重复活。

框架把重复活收走了——URL 和函数的对应关系用装饰器声明，JSON 序列化自动做，参数校验声明式配置，接口文档自动生成。FastAPI 在这些基础上还带了类型提示和异步支持，写起来跟写普通 Python 函数差不多。

二、安装环境

uv init article-api
cd article-api
uv add fastapi uvicorn

包	作用
fastapi	框架本身，提供路由、校验、文档
uvicorn	ASGI 服务器，负责接收 HTTP 连接、转给 FastAPI 处理

两个都要装。uvicorn 是运行入口，没有它 FastAPI 应用无法直接对外提供服务。

验证安装：

uv run python -c "import fastapi; print(fastapi.__version__)"

三、第一个接口

新建文件 main.py：

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/") 是装饰器——告诉 FastAPI："GET 请求 / 这个路径时，执行下面的函数"。函数返回字典，FastAPI 自动转成 JSON 响应。

启动开发服务器：

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

参数	作用
main:app	main.py 文件里的 app 变量
--reload	代码修改后自动重启（开发环境专用）
--port 8000	监听 8000 端口

打开浏览器访问 http://localhost:8000/，看到 {"message": "hello"} 即表示服务正常运行。

四、自动文档

FastAPI 根据代码中的类型注解自动生成接口文档。启动服务后访问：

地址	内容
http://localhost:8000/docs	Swagger UI 交互式文档
http://localhost:8000/redoc	ReDoc 静态文档

文档里会列出所有接口、请求参数、响应模型，还可以直接发起测试请求。这是类型注解带来的附加价值——不需要额外写文档，代码即文档。

五、项目结构

小型项目可以所有代码放在 main.py，功能多了之后按职责拆分：

article-api/
├── main.py           # 应用入口，创建 FastAPI 实例
├── routers/          # 路由模块（按业务拆分）
│   ├── articles.py
│   └── users.py
├── models.py         # 数据模型（Pydantic）
├── database.py       # 数据库连接
└── pyproject.toml

main.py 只负责组装：

from fastapi import FastAPI
from routers import articles, users

app = FastAPI()
app.include_router(articles.router, prefix="/articles", tags=["articles"])
app.include_router(users.router, prefix="/users", tags=["users"])

六、常见错误

启动命令写错

# 错误：找不到 app
uv run uvicorn app:main --port 8000

# 正确：文件名在前，变量名在后
uv run uvicorn main:app --port 8000

忘记安装 uvicorn

# 错误：只装 fastapi，没有 ASGI 服务器
uv add fastapi
uv run uvicorn main:app   # ModuleNotFoundError: No module named 'uvicorn'

# 正确
uv add fastapi uvicorn

生产环境用 --reload

# 错误：reload 会监控文件变化并重启，性能开销大，且不安全
uvicorn main:app --reload

# 正确：生产环境去掉 --reload，用多个 worker
uvicorn main:app --workers 4

在 uv 环境外运行

# 错误：没有激活虚拟环境，用的系统 Python
python main.py

# 正确：通过 uv run 使用项目虚拟环境
uv run python main.py