qidao123.com技术社区-IT企服评测·应用市场

标题: FastAPI 核心机制：分页参数的实现与最佳实践 [打印本页]

---

作者: 老婆出轨    时间: 2025-3-13 00:19
标题: FastAPI 核心机制：分页参数的实现与最佳实践
title: FastAPI 核心机制：分页参数的实现与最佳实践
date: 2025/3/13
updated: 2025/3/13
author: cmdragon
excerpt:
在构建当代Web应用程序时，分页是一个不可或缺的功能。无论是处理大量数据还是优化用户体验，分页都起到了至关重要的作用。本文将深入探究如何在FastAPI中实现分页参数（如page、page_size以及总页数计算），并涵盖相关的核心机制、最佳实践、常见题目及办理方案。
categories:

• 后端开辟
  
• FastAPI
  

tags:

• FastAPI
  
• 分页
  
• Web开辟
  
• 数据库查询
  
• 性能优化
  
• 安全实践
  
• 错误处理
  

扫描二维码关注或者微信搜一搜：编程智域 前端至全栈交流与成长
探索数千个预构建的 AI 应用，开启你的下一个伟大创意
1. 分页的根本概念

分页是将大量数据分割成多个小块（即“页”），以便用户或系统可以逐步加载和处理这些数据。在Web应用中，分页通常用于处理数据库查询结果、API响应等场景。常见的分页参数包括：

• page：当前页码。
  
• page_size：每页显示的数据条数。
  
• total_pages：总页数。
  

2. FastAPI中的分页实现

在FastAPI中，分页可以通过查询参数来实现。以下是一个简朴的示例，展示了如何在FastAPI中实现分页功能。

1. from fastapi import FastAPI, Query
2. from typing import List, Optional
4. app = FastAPI()
6. # 模拟数据库数据
7. fake_items_db = [{"item_name": f"Item {i}"} for i in range(100)]
10. @app.get("/items/")
11. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0)):
12.     start = (page - 1) * page_size
13.     end = start + page_size
14.     items = fake_items_db[start:end]
15.     total_items = len(fake_items_db)
16.     total_pages = (total_items + page_size - 1) // page_size
17.     return {
18.         "items": items,
19.         "page": page,
20.         "page_size": page_size,
21.         "total_items": total_items,
22.         "total_pages": total_pages,
23.     }

复制代码

在这个示例中，我们定义了两个查询参数page和page_size，并通过计算start和end
来获取当前页的数据。我们还计算了总页数total_pages，并将其包含在响应中。
3. 分页参数的最佳实践

3.1 参数验证

为了确保分页参数的有效性，我们需要对page和page_size进行验证。FastAPI提供了Query参数验证功能，可以轻松实现这一点。

1. from fastapi import Query
4. @app.get("/items/")
5. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100)):
6.     # 分页逻辑
7.     pass

复制代码

在这个示例中，我们使用gt（大于）和le（小于等于）来限制page和page_size的取值范围。如果用户提供的参数不符合要求，FastAPI会主动返回422
Validation Error。
3.2 默认值设置

为分页参数设置合理的默认值可以提升用户体验。例如，将page_size的默认值设置为10或20，可以避免用户一次性加载过多数据。

1. @app.get("/items/")
2. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100)):
3.     # 分页逻辑
4.     pass

复制代码

3.3 总页数计算

总页数的计算公式为：

1. total_pages = (total_items + page_size - 1) // page_size

复制代码

这个公式确保了总页数的准确性，即使total_items不能被page_size整除。
4. 数据库查询中的分页

在现实应用中，分页通常与数据库查询结合使用。以下是一个使用SQLAlchemy进行分页查询的示例。

1. from sqlalchemy.orm import Session
2. from fastapi import Depends
3. from .database import SessionLocal
6. def get_db():
7.     db = SessionLocal()
8.     try:
9.         yield db
10.     finally:
11.         db.close()
14. @app.get("/items/")
15. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100),
16.                      db: Session = Depends(get_db)):
17.     start = (page - 1) * page_size
18.     items = db.query(Item).offset(start).limit(page_size).all()
19.     total_items = db.query(Item).count()
20.     total_pages = (total_items + page_size - 1) // page_size
21.     return {
22.         "items": items,
23.         "page": page,
24.         "page_size": page_size,
25.         "total_items": total_items,
26.         "total_pages": total_pages,
27.     }

复制代码

在这个示例中，我们使用offset和limit来实现分页查询，并通过count方法获取总数据条数。
5. 分页的安全性

5.1 避免SQL注入

在使用原始SQL查询时，必须留意避免SQL注入攻击。SQLAlchemy等ORM框架已经内置了防止SQL注入的机制，但在使用原始SQL时，仍需审慎。

1. from sqlalchemy.sql import text
4. @app.get("/items/")
5. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100),
6.                      db: Session = Depends(get_db)):
7.     start = (page - 1) * page_size
8.     query = text("SELECT * FROM items LIMIT :limit OFFSET :offset")
9.     items = db.execute(query, {"limit": page_size, "offset": start}).fetchall()
10.     total_items = db.execute(text("SELECT COUNT(*) FROM items")).scalar()
11.     total_pages = (total_items + page_size - 1) // page_size
12.     return {
13.         "items": items,
14.         "page": page,
15.         "page_size": page_size,
16.         "total_items": total_items,
17.         "total_pages": total_pages,
18.     }

复制代码

在这个示例中，我们使用参数化查询来避免SQL注入。
5.2 数据隐私

在处理敏感数据时，确保分页查询不会泄露隐私信息。例如，避免在分页查询中返回未授权的数据。
6. 性能优化

6.1 索引优化

在数据库查询中，为分页字段（如id、created_at等）创建索引可以明显提升查询性能。

1. CREATE INDEX idx_items_created_at ON items (created_at);

复制代码

6.2 缓存

对于频繁访问的分页数据，可以使用缓存机制（如Redis）来减少数据库查询次数。

1. from fastapi_cache import FastAPICache
2. from fastapi_cache.decorator import cache
5. @app.get("/items/")
6. @cache(expire=60)
7. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100)):
8.     # 分页逻辑
9.     pass

复制代码

在这个示例中，我们使用fastapi-cache库来缓存分页查询结果，缓存有效期为60秒。
7. 常见错误及办理方案

7.1 422 Validation Error

当分页参数不符合验证规则时，FastAPI会返回422 Validation Error。办理方案是确保分页参数的取值范围精确，并在API文档中明确阐明。

1. @app.get("/items/")
2. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100)):
3.     # 分页逻辑
4.     pass

复制代码

7.2 500 Internal Server Error

当数据库查询失败或分页逻辑出现错误时，可能会返回500 Internal Server Error。办理方案是捕获异常并返回友好的错误信息。

1. from fastapi import HTTPException
4. @app.get("/items/")
5. async def read_items(page: int = Query(1, gt=0), page_size: int = Query(10, gt=0, le=100),
6.                      db: Session = Depends(get_db)):
7.     try:
8.         start = (page - 1) * page_size
9.         items = db.query(Item).offset(start).limit(page_size).all()
10.         total_items = db.query(Item).count()
11.         total_pages = (total_items + page_size - 1) // page_size
12.         return {
13.             "items": items,
14.             "page": page,
15.             "page_size": page_size,
16.             "total_items": total_items,
17.             "total_pages": total_pages,
18.         }
19.     except Exception as e:
20.         raise HTTPException(status_code=500, detail=str(e))

复制代码

在这个示例中，我们捕获了所有异常，并返回500 Internal Server Error。
8. 课后Quiz

• 如何避免SQL注入攻击？
  
  
  
  • 使用参数化查询。
    
  • 避免拼接SQL语句。
    
  • 使用ORM框架。
    
  
  
• 如何优化分页查询的性能？
  
  
  
  • 为分页字段创建索引。
    
  • 使用缓存机制。
    
  • 减少查询返回的字段数目。
    
  
  
• 如何处理分页参数无效的情况？
  
  
  
  • 使用FastAPI的Query参数验证功能。
    
  • 返回422 Validation Error。
    
  • 在API文档中明确阐明参数要求。
    
  
  

常见报错办理方案：

• 422 Validation Error：查抄分页参数的取值范围，确保符合验证规则。
  
• 500 Internal Server Error：捕获异常并返回友好的错误信息，查抄数据库查询逻辑。
  
• 404 Not Found：确保分页参数不会导致查询结果为空，处理边界情况。
  

余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：FastAPI 核心机制：分页参数的实现与最佳实践 | cmdragon's Blog
往期文章归档：

<ul><a href="https://blog.cmdragon.cn/posts/615a966b68d9/" target="_blank" rel="noopener nofollow">FastAPI 错误处理与自定义错误消息完全指南：构建坚固的 API 应用
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

---

欢迎光临 qidao123.com技术社区-IT企服评测·应用市场 (https://dis.qidao123.com/)

Powered by Discuz! X3.4