1. FastAPI请求与响应基础入门作为一个现代Python Web框架FastAPI最吸引人的特性之一就是它简洁直观的请求响应处理机制。记得我第一次从Flask切换到FastAPI时最惊喜的就是发现原来处理HTTP请求可以如此优雅。今天我们就来深入探讨这个框架的核心能力。在FastAPI中请求和响应的处理遵循几个基本原则基于Python类型提示的自动数据验证内置的OpenAPI文档生成高性能的请求解析和响应序列化灵活的可扩展性这些特性使得FastAPI既能满足快速开发的需求又能应对复杂的业务场景。下面我们通过一个简单的示例来感受一下from fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_item(item_id: int): return {item_id: item_id}这个简单的例子已经展示了FastAPI处理请求响应的核心模式通过类型注解声明参数类型框架自动处理验证和转换返回值自动转换为JSON响应。2. 请求处理深度解析2.1 路径参数与查询参数路径参数是URL路径的一部分比如/items/42中的42。在FastAPI中声明和使用非常简单app.get(/items/{item_id}) async def read_item(item_id: int, q: str None): return {item_id: item_id, q: q}这里item_id会被自动转换为整数类型如果传入非数字值FastAPI会自动返回422错误响应。查询参数q是可选的通过None设置默认值。提示路径参数和查询参数的区别在于是否在URL路径中声明。路径参数是必需的而查询参数通常是可选的。2.2 请求体处理POST、PUT等请求通常需要处理请求体。FastAPI通过Pydantic模型使这变得异常简单from pydantic import BaseModel class Item(BaseModel): name: str description: str None price: float tax: float None app.post(/items/) async def create_item(item: Item): return item这个例子中FastAPI会自动读取请求体作为JSON转换为指定的Pydantic模型验证数据类型在文档中生成对应schema2.3 表单和文件上传处理表单数据和文件上传也很直观from fastapi import File, UploadFile app.post(/files/) async def create_file(file: bytes File(...)): return {file_size: len(file)} app.post(/uploadfile/) async def create_upload_file(file: UploadFile File(...)): return {filename: file.filename}File和UploadFile的区别在于bytes方式会一次性读取整个文件到内存UploadFile更适合大文件支持异步操作3. 响应处理全攻略3.1 基本响应类型FastAPI默认会将返回值转换为JSON响应但你可以完全控制响应from fastapi.responses import JSONResponse app.get(/items/, response_modelList[Item]) async def read_items(): items [{name: Foo, price: 42.0}] return JSONResponse(contentitems, status_code200)response_model参数确保了返回数据的类型安全即使你返回的是字典FastAPI也会根据模型进行验证。3.2 自定义响应你可以返回任何Starlette的Response对象实现完全自定义的响应from fastapi.responses import HTMLResponse app.get(/html/, response_classHTMLResponse) async def read_html(): return html bodyh1Hello World/h1/body /html FastAPI提供了多种内置响应类型HTMLResponsePlainTextResponseRedirectResponseStreamingResponseFileResponse3.3 响应状态码和头部设置状态码和响应头有多种方式from fastapi import status app.post(/items/, status_codestatus.HTTP_201_CREATED) async def create_item(item: Item): return item app.get(/headers/) async def read_items(): content {message: Hello World} headers {X-Custom-Header: custom-value} return JSONResponse(contentcontent, headersheaders)4. 高级技巧与最佳实践4.1 依赖注入系统FastAPI强大的依赖注入系统可以简化请求处理from fastapi import Depends def get_query_token(token: str): if token ! secret: raise HTTPException(status_code400, detailInvalid token) return token app.get(/protected/) async def read_protected(token: str Depends(get_query_token)): return {token: token}依赖可以复用、嵌套甚至缓存结果极大提高了代码的可维护性。4.2 异常处理自定义异常处理让API更加友好from fastapi import HTTPException app.get(/items/{item_id}) async def read_item(item_id: str): if item_id not in items: raise HTTPException( status_code404, detailItem not found, headers{X-Error: Item not found}, ) return {item: items[item_id]}你也可以注册全局异常处理器来处理自定义异常。4.3 性能优化技巧使用response_model而不是手动转换因为FastAPI在Rust层面优化了Pydantic的序列化对大响应考虑使用StreamingResponse合理使用依赖项的缓存避免在路径操作函数中进行阻塞IO操作5. 常见问题排查5.1 请求验证失败当收到422响应时检查请求体是否符合模型定义路径/查询参数类型是否正确是否缺少必需字段5.2 响应序列化问题如果遇到响应序列化错误确保返回的数据可以被json序列化复杂类型如datetime需要使用jsonable_encoder检查response_model定义是否正确5.3 跨域问题处理CORS问题from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[*], allow_credentialsTrue, allow_methods[*], allow_headers[*], )6. 实战经验分享在实际项目中我发现这些实践特别有价值文档友好充分利用response_model和response_description让API文档更清晰app.post( /items/, response_modelItem, response_descriptionThe created item, status_code201 )版本控制通过响应头或URL路径实现API版本管理app.get(/v1/items/) async def read_items_v1(): return {version: v1}性能监控使用中间件添加响应时间头app.middleware(http) async def add_process_time_header(request, call_next): start_time time.time() response await call_next(request) process_time time.time() - start_time response.headers[X-Process-Time] str(process_time) return response安全加固始终设置适当的安全头from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware app.add_middleware(HTTPSRedirectMiddleware)FastAPI的请求响应系统看似简单实则强大。掌握这些基础用法后你可以处理绝大多数Web API开发场景。随着项目复杂度增加你会发现更多高级特性如WebSocket、后台任务等都能无缝集成到这个简洁的模型中。