2. 第一个RESTful端点

任务说明

本案例将实现一个FastAPI应用，包含三个GET端点：一个返回固定JSON响应的根端点、一个包含路径参数的端点、一个包含查询参数的端点。通过本案例，你将掌握FastAPI中最基础的请求处理与参数绑定方式。

实现代码

# main.py
from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

# 1. 固定JSON响应端点
@app.get("/")
def read_root():
    return {"message": "Hello FastAPI", "status": "ok"}

# 2. 路径参数端点
@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "type": "path_parameter"}

# 3. 查询参数端点
@app.get("/search")
def search_items(
    keyword: str,
    limit: int = Query(10, ge=1, le=100),
    sort: Optional[str] = None
):
    return {
        "keyword": keyword,
        "limit": limit,
        "sort": sort,
        "type": "query_parameter"
    }

代码说明

上述代码中，read_root函数演示了最基本的GET端点，直接返回一个Python字典，FastAPI会自动将其序列化为JSON响应。get_user函数展示了路径参数的使用，user_id被声明为int类型，FastAPI会自动进行类型转换与校验——若传入非整数，将返回422验证错误。search_items函数演示了查询参数：keyword为必填参数，limit带有默认值10且通过Query约束取值范围在1到100之间，sort为可选参数。

运行与验证

# 安装依赖
pip install fastapi uvicorn

# 启动服务
uvicorn main:app --reload --port 8000

服务启动后，可通过以下方式验证各端点：

• 访问 http://127.0.0.1:8000/，预期返回 {"message":"Hello FastAPI","status":"ok"}
• 访问 http://127.0.0.1:8000/users/42，预期返回 {"user_id":42,"type":"path_parameter"}
• 访问 http://127.0.0.1:8000/search?keyword=fastapi&limit=5，预期返回包含keyword、limit、sort字段的JSON
• 访问 http://127.0.0.1:8000/users/abc，预期返回422验证错误，证明类型校验生效
• 访问 http://127.0.0.1:8000/search?limit=200（缺少keyword），预期返回422错误，证明必填参数校验生效

同时，访问 http://127.0.0.1:8000/docs 可查看FastAPI自动生成的交互式API文档，所有端点及参数约束均会在此可视化呈现。

验证判定标准

当上述五个访问路径返回的结果与预期一致时，即可判定本案例实现正确。重点确认：路径参数类型转换生效、查询参数默认值与约束生效、必填参数缺失时返回422错误。