前台要取文档列表和分类，接口该怎么调

前台要取文档列表和分类，接口该怎么调？顺序是「先分类、再列表、后详情」：先把分类树与标签列表各取一次放在缓存里，列表接口按分类标识加分页参数翻页，用户点进某条数据时再用详情接口取正文与自定义字段。这套顺序的好处是请求可复用，首页与栏目页不会因为每屏都重新拉分类而多打几次接口。文档列表、详情、分类与标签属于后台对外提供的高频 API 调用能力，具体参数在接口文档里可以自查。

先列要取的数据

写调用代码之前，把页面需要的数据列成一张表，避免在模板里现加请求。

列表与详情的调用顺序

列表接口常见错法有三种。第一种是把全部字段都取回来：列表页只要标题、摘要与时间，正文与自定义字段留到详情接口再取，每页字段越少响应越快。第二种是翻页参数不带分类条件，翻到第二页时把别的栏目的数据也带出来。第三种是拿详情接口当列表用，一页二十条就发二十次请求。

详情接口返回的字段以文档为单位，拆出来的自定义字段可以直接渲染规格表；同时要留意状态字段：正式文档与草稿、待发布走不同的可见范围，草稿链接带 preview 参数用于预览，前台列表默认只应取正式文档。回收站里的内容不参与列表，误删的正式文档可以从回收站恢复，不需要通过接口绕行。

分类与标签怎么关联

分类表达栏目层级，标签表达横向主题，两者都能作为列表接口的筛选条件。前台通常同时需要「某个分类下的文章」和「某篇文章属于哪些分类与标签」，前者用分类标识过滤，后者读详情返回的关联字段。分类树建议按层级一次取全，前端自己组装面包屑；标签数量多时先取热门标签，再按用户点击加载标签下的列表，避免首页一次拉全量。

批量写入时先查重

接口除了读取，也承担写入。内容迁移或批量补稿时，先按标题查询该文档是否已存在，再决定创建还是更新，这是导入接口的常规用法：文档内容导入走 /api/import/archive 这个入口，import 负责写入、archive 侧支持按标题查询是否已存在，用它做「先查后写」能避免同一篇文章出现两份。批量导入本身支持压缩包与表格两种来源，字段映射在导入前确认：标题、分类、标签、正文与摘要对应哪些列，映射错位比导入失败更难发现。

写入后确认三件事：前台列表能否取到新内容、详情接口返回的字段是否齐全、站点地图与推送是否覆盖新增地址。批量操作建议放在低峰时段，一次不要灌太多，分批校验更容易定位错误。

常见问题

接口需要登录吗？ 读取公开内容的接口不需要；写入类调用需要按后台配置鉴权，凭据只放在服务端，不要暴露给浏览器脚本。

分页与筛选能同时用吗？ 能，参数一起传即可。注意翻页时保持筛选条件不变，否则各页之间会出现重复或漏项。

前台能不能直接取全部文章自己做筛选？ 少量内容可以，内容上千后应把筛选条件下沉到接口参数，由服务端过滤，否则首屏传输与渲染都会变慢。

导入接口写入的内容是草稿还是正式？ 取决于调用时传的草稿标记。先写成草稿、核对排版与字段后再放开，比直接发布更安全。