FastAPI Hello World应用

📂 所属阶段：第一阶段 — 快速筑基（基础篇）
🔗 前置知识：FastAPI简介与优势 · 环境搭建

目录

Hello World：5行搞定第一个接口

让我们直接切入正题，创建一个极简但完整的FastAPI应用。在项目根目录下新建main.py文件：

from fastapi import FastAPI  # 1. 导入核心类

app = FastAPI()  # 2. 创建应用实例（FastAPI的入口）

# 3. 定义路由装饰器（指定HTTP方法GET + 路径/）
@app.get("/")
def hello_world():  # 4. 定义路径操作函数（处理请求的核心逻辑）
    return {"message": "Hello FastAPI World!"}  # 5. 自动转JSON返回

逐行拆解关键逻辑

  • 导入FastAPI类：就像用Python内置库一样，从fastapi模块拿我们的核心工具。
  • 创建应用实例：app是整个API的“大脑”，所有的配置、路由、中间件都要绑定到它身上。
  • 装饰器的作用：@app.get("/")是双重身份的“标注”——告诉FastAPI：「当收到GET方法请求根路径/时，就调用下面的hello_world」。
  • 自动JSON序列化：返回Python字典/列表/普通对象（搭配Pydantic的话），FastAPI会自动处理成标准JSON格式，不用手动写json.dumps！

运行应用与探索自动文档

FastAPI官方推荐搭配ASGI服务器Uvicorn运行，它支持热重载、多进程等生产级特性。

前置准备：激活虚拟环境

在终端执行（如果你在环境搭建篇创建了venv）：

  • Windows（PowerShell/CMD）： 
    .\venv\Scripts\activate  # PowerShell推荐
  • macOS/Linux： 
    source venv/bin/activate

运行命令（开发模式）

uvicorn main:app --reload --host 0.0.0.0 --port 8000

参数解释：

  • main:app：main.py文件中的app实例
  • --reload：开发神器！修改代码后自动重启服务器
  • --host 0.0.0.0：允许局域网内其他设备访问（只自己用可以不加）
  • --port 8000：监听8000端口（默认就是8000，可以不加）

启动成功后会看到类似输出：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345]
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

📖 免费的交互式API文档

FastAPI最惊艳的特性之一——自动生成、可直接交互的API文档！启动后访问这两个地址：

  1. Swagger UI（推荐调试用）：http://127.0.0.1:8000/docs
    界面友好，支持直接发送请求、查看响应、下载代码片段（Python/JS/Java等）
  2. ReDoc（推荐给甲方/前端看）：http://127.0.0.1:8000/redoc
    界面更简洁美观，适合做API产品文档

快速扩写核心交互功能

Hello World只是开胃菜，我们快速加3个Web开发最常用的功能，感受FastAPI的简洁与强大。

1. 路径参数（比如获取单个商品）

路径参数是URL路径里的变量，用{}包裹，FastAPI会自动帮你类型转换和基本验证：

from fastapi import FastAPI

app = FastAPI()

# 路径参数item_id自动转成int类型
@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id, "item_name": f"测试商品{item_id}"}

在Swagger UI里试一下：

  • 输入item_id=123：正常返回，类型是int
  • 输入item_id=abc：Swagger会提示错误，FastAPI返回422验证失败的JSON，非常清晰

2. 查询参数（比如分页、搜索）

查询参数是URL末尾?后面的键值对，比如/items?skip=0&limit=10。FastAPI支持可选参数和默认值：

from fastapi import FastAPI
from typing import Optional  # Python 3.10+可以用str | None代替

app = FastAPI()

# 所有参数都默认，不传也能用
@app.get("/items/")
def get_items_list(
    skip: int = 0,  # 跳过前n个
    limit: int = 10,  # 最多返回n个
    q: Optional[str] = None  # 可选搜索词
):
    # 模拟返回数据
    mock_items = [{"item_id": i} for i in range(skip, skip + limit)]
    result = {"items": mock_items, "skip": skip, "limit": limit}
    if q:
        result["search_query"] = q
    return result

3. POST请求体（比如创建商品）

POST请求体是客户端通过请求体传给服务器的数据（通常是JSON），FastAPI需要搭配Pydantic模型做类型定义和严格验证——这也是FastAPI“高性能、低Bug率”的核心原因之一。

先创建一个简单的Pydantic模型，定义商品的必填/可选字段和约束：

from fastapi import FastAPI
from pydantic import BaseModel  # 导入Pydantic核心类
from typing import Optional

app = FastAPI()

# 定义请求体模型
class ItemCreate(BaseModel):
    name: str  # 必填，字符串类型
    price: float  # 必填，浮点数类型
    description: Optional[str] = None  # 可选，默认None
    tax: Optional[float] = None  # 可选，默认None

# 用POST方法，接收ItemCreate类型的请求体
@app.post("/items/")
def create_item(item: ItemCreate):
    # 把Pydantic模型转成字典（方便后续处理）
    item_dict = item.model_dump()
    # 加个小逻辑：有税的话算总价
    if item.tax:
        item_dict["total_price"] = item.price * (1 + item.tax / 100)
    # 返回创建成功的商品（带自动生成的id）
    return {"item_id": 123, **item_dict}

在Swagger UI里点「Try it out」，输入符合格式的JSON（比如下面这个），就能看到带总价的返回结果啦：

{
  "name": "机械键盘",
  "price": 399.0,
  "description": "青轴机械键盘，手感超级棒",
  "tax": 13
}

避坑指南与开发小工具

✅ 避坑1：路径的顺序问题

FastAPI是按代码定义的顺序匹配路由的，所以固定路径要放在变量路径前面：

# ❌ 错误顺序：users/me会被当成user_id=me，报类型错误
@app.get("/users/{user_id}")
def get_user(user_id: int): ...

@app.get("/users/me")
def get_current_user(): ...

# ✅ 正确顺序：固定路径先匹配
@app.get("/users/me")
def get_current_user(): ...

@app.get("/users/{user_id}")
def get_user(user_id: int): ...

✅ 避坑2：开发模式和生产模式的区别

  • 开发模式：可以用--reload，可以开debug=True（创建app时加参数），但这些绝对不能在生产环境用！
  • 生产模式：去掉--reload和debug=True，可以用多进程（后面的进阶篇会讲）。

🛠️ 开发小工具：打印请求信息

调试的时候可以加个简单的中间件，打印每个请求的方法、路径和响应状态：

from fastapi import FastAPI, Request
import time

app = FastAPI()

# 中间件：每个请求都会经过这里
@app.middleware("http")
async def log_request(request: Request, call_next):
    start_time = time.time()
    # 打印请求信息
    print(f"📥 Request: {request.method} {request.url.path}")
    # 处理请求
    response = await call_next(request)
    # 计算处理时间
    process_time = (time.time() - start_time) * 1000
    # 打印响应状态和处理时间
    print(f"📤 Response: {response.status_code} | {process_time:.2f}ms")
    # 把处理时间加到响应头里（方便前端看）
    response.headers["X-Process-Time"] = f"{process_time:.2f}ms"
    return response

总结

通过这篇5分钟就能读完的入门教程，你已经掌握了FastAPI Hello World应用的核心三件套：

  1. 创建应用：用FastAPI()创建入口实例
  2. 定义路由：用装饰器@app.get/post/...()绑定HTTP方法、路径和处理函数
  3. 参数与验证：路径参数、查询参数、POST请求体（搭配Pydantic做严格验证）

另外，别忘了善用Swagger UI调试接口，它能帮你省很多手动写测试请求的时间！

下一篇我们会深入学习路径参数和查询参数的高级验证，敬请期待～