1. 为什么分页和接口文档总在联调时掉链子DRF 的分页和 coreapi 自动文档单看都不难难的是把它们放进同一个项目里一次跑通。我见过太多项目分页类写好了?page2返回的还是全量数据文档页能打开但 schema 里分页参数一个都不显示或者本地跑得好好的换台机器就报AutoSchema has no attribute get_link。这些问题的根子往往不在 DRF 本身而在配置骨架没搭对、版本没对齐、验证动作缺失。这篇就围绕PageNumberPagination、LimitOffsetPagination和 coreapi 自动生成接口文档这条线给出一套可以直接复制的配置骨架。同时把 TaoToken 统一 Key 接入 AI 工具的配置示例嵌进来让分页接口和文档 schema 的验证动作能一次跑完。适合正在用 DRF 写列表接口、又想让接口文档自动跟着代码走的同学。读完你能拿到三种分页类的完整参数对照、settings.json/config.toml骨架、coreapi 文档路由配置以及分页参数和 schema 的验证命令。2. TaoToken 前置统一 Key 与 API 通道准备在写分页和文档配置之前先把 AI 工具的接入通道理清楚。TaoToken 在这里扮演的是统一 Key 和 API 通道的角色你不需要在多个工具里反复填不同的地址和密钥一个 Key 走通模型对话、编码辅助和文档生成这几类场景。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 注意这个地址后面不加 UTM 参数。实际接入时你需要在控制台生成 API Key然后把它写进工具的配置文件里。几个常用的 deep link 按场景分一下需要验证模型对话效果走模型对话页长期做编码和 Agent 任务看 Coding Plan管理密钥和额度进 console生成或轮换 Key用 api-keys查接入细节翻 doc如果是 Claude Code 这类 Anthropic 风格的工具参考 ClaudeCodeAnthropic 页面。注意API Key 只放在本地配置文件或环境变量里不要提交到 Git 仓库。分页和文档配置属于项目代码Key 属于凭证两者要分开管理。3. 可复制配置分页类 coreapi TaoToken 骨架3.1 三种分页类的参数对照DRF 自带三种分页组件选哪种取决于你的数据量和交互需求。下面这张表把关键参数列清楚方便你直接对照改。分页类核心参数默认值适用场景PageNumberPaginationpage_size / page_query_param / page_size_query_param / max_page_sizepage_size 取全局 PAGE_SIZE常规列表需要页码跳转LimitOffsetPaginationdefault_limit / limit_query_param / offset_query_param / max_limitdefault_limit 取全局 PAGE_SIZE需要灵活控制取多少条CursorPaginationpage_size / cursor_query_param / orderingordering 为 -created大数据量只支持上下页页码分页的page_size_query_param允许前端通过 URL 参数临时改每页条数但会被max_page_size卡住上限。偏移分页的offset是标杆位置limit是从标杆后取几条注意它不包含 offset 指向的那条。游标分页靠ordering排序后生成 cursor效率高但不支持跳页。3.2 自定义分页类代码在项目里建一个pagination.py把三种分页类都写进去按需引用。from rest_framework.pagination import ( PageNumberPagination, LimitOffsetPagination, CursorPagination, ) class MyPageNumberPagination(PageNumberPagination): page_size 3 page_query_param page page_size_query_param size max_page_size 20 class MyLimitOffsetPagination(LimitOffsetPagination): default_limit 3 limit_query_param limit offset_query_param offset max_limit 20 class MyCursorPagination(CursorPagination): page_size 3 cursor_query_param cursor ordering -id视图类继承ListAPIView时通过pagination_class指定用哪个。如果整个项目统一用一种就在REST_FRAMEWORK里配DEFAULT_PAGINATION_CLASS视图里不用再写。from rest_framework.generics import ListAPIView from .models import Publish from .serializers import PublishSerializer from .pagination import MyPageNumberPagination class PublishListAPIView(ListAPIView): queryset Publish.objects.all() serializer_class PublishSerializer pagination_class MyPageNumberPagination3.3 settings.json / config.toml 骨架如果你用 JSON 或 TOML 管理配置下面两个骨架可以直接改。JSON 版适合 Django 项目里读配置TOML 版适合独立工具或脚本。{ django: { rest_framework: { DEFAULT_PAGINATION_CLASS: rest_framework.pagination.PageNumberPagination, PAGE_SIZE: 3, DEFAULT_SCHEMA_CLASS: rest_framework.schemas.coreapi.AutoSchema } }, taotoken: { api_base: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: gpt-4o-mini } }[django.rest_framework] DEFAULT_PAGINATION_CLASS rest_framework.pagination.PageNumberPagination PAGE_SIZE 3 DEFAULT_SCHEMA_CLASS rest_framework.schemas.coreapi.AutoSchema [taotoken] api_base https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-miniDEFAULT_SCHEMA_CLASS这一行很关键。新版 DRF 默认用rest_framework.schemas.openapi.AutoSchema而 coreapi 需要的是rest_framework.schemas.coreapi.AutoSchema。不配这一行文档页大概率报get_link找不到。3.4 coreapi 文档路由配置先装 coreapipip install coreapi然后在总路由里加文档入口from django.urls import path from rest_framework.documentation import include_docs_urls urlpatterns [ path(docs/, include_docs_urls(title接口文档站点)), ]文档描述写在视图类的 docstring 里。单一方法视图直接写说明多方法视图按get:/post:分行写ViewSet 用 action 名区分。class BookViewSet(ListModelMixin, RetrieveModelMixin, GenericViewSet): list: 返回图书列表数据支持分页参数 page 和 size。 retrieve: 返回图书详情数据。 4. 验证请求分页参数与 schema 一次跑通配置写完启动服务按下面顺序验证。先确认分页接口返回结构再确认文档 schema 里分页参数可见。第一步请求页码分页接口curl http://127.0.0.1:8000/publish/?page2size3预期返回里包含count、next、previous、results四个字段results长度不超过 3。如果results还是全量说明pagination_class没生效检查视图类是否真的继承了ListAPIView或GenericAPIView。第二步请求偏移分页接口curl http://127.0.0.1:8000/publish/?offset3limit4预期从第 4 条开始取 4 条limit超过max_limit时会被截断到上限。第三步验证文档 schemacurl http://127.0.0.1:8000/docs/浏览器打开文档页找到列表接口展开参数区应该能看到page、size或limit、offset这些查询参数。如果参数区是空的回到DEFAULT_SCHEMA_CLASS检查是否指向 coreapi。第四步用 TaoToken 的 API 通道做一次模型对话验证确认 Key 可用curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}返回里有choices字段就说明通道正常。这一步和分页无关但能帮你确认 AI 工具侧的配置没拖后腿。5. 本篇常见错排查5.1 分页不生效返回全量数据最常见的原因是视图类没有正确继承。APIView本身不带分页能力必须继承ListAPIView或GenericAPIView并设置pagination_class。另一个原因是queryset写成了Model.objects.all()但序列化时手动遍历了绕过了分页器。检查get_queryset和list方法有没有被重写。5.2 文档页报 AutoSchema has no attribute get_link这是版本错配。新版 DRF 默认 schema 类是 openapi 的coreapi 需要显式指定。在REST_FRAMEWORK里加REST_FRAMEWORK { DEFAULT_SCHEMA_CLASS: rest_framework.schemas.coreapi.AutoSchema, }注意变量名是REST_FRAMEWORK不是REST_FRAMEWORD拼错也会导致配置不生效。5.3 分页参数在文档里不显示coreapi 只会把视图类 docstring 和序列化器字段映射到文档。分页参数属于查询参数需要在视图的 docstring 里手动说明或者确认DEFAULT_SCHEMA_CLASS配置正确。如果文档页能打开但参数区空白先看 docstring 有没有写再看 schema 类对不对。5.4 PAGE_SIZE 全局配置和分页类冲突REST_FRAMEWORK里的PAGE_SIZE是全局默认值分页类里显式写的page_size会覆盖它。如果你在分页类里写了page_size 3又在 settings 里写了PAGE_SIZE 10实际生效的是 3。排查时以分页类里的值为准。5.5 TaoToken Key 读取失败如果配置文件里写的是api_key_env确认环境变量真的导出了。用echo $TAOTOKEN_API_KEY检查输出为空就说明没设置。不要把 Key 直接写死在代码里也不要把带 Key 的配置文件提交到仓库。6. 接入文档与 Key 管理入口分页和文档配置跑通之后接下来要处理的是 Key 的日常管理和接入细节。生成或轮换 Key 走 api-keys 页面接入参数和字段说明翻 doc 页面。如果你在做长期编码任务或 Agent 类工具Coding Plan 页面有对应的配置说明。需要快速验证模型对话效果直接用模型对话页试一条请求就行。把这些入口按场景分开用比每次从首页找要省事。分页接口和 coreapi 文档属于项目侧配置TaoToken 的 Key 和通道属于工具侧配置两边分开维护联调时才能快速定位问题出在哪一层。