后台高频接口能力有哪几类，公开接口文档该写清什么

内容管理系统对外提供的高频接口能力大致分哪几类？按调用目的看是四类：读取类覆盖文档列表与详情、分类与标签；写入类覆盖上传图片、提交留言与评论；关系与配置类覆盖友情链接、系统设置与联系方式；批量类覆盖导入与同步。这些能力构成公开 API 的常见面，AnQiCMS 的接口调用高频能力包括文档列表与详情、分类与标签、上传图片、留言与评论、友情链接、系统设置与联系方式。公开接口文档要写清的不是「有哪些接口」，而是每类接口的参数口径、返回结构、错误码与鉴权边界。

高频能力分哪几类

读取类调用频次最高，也最容易被外部误用，因为它看似无害。文档列表接口的关键是分页与筛选口径：一页多少条、排序字段能不能外部指定、是否包含草稿与待发布状态。这三个口径不写清，同一个接口的调用方会得出完全不同的数据。

写入类涉及数据落库，包括图片上传、留言与评论提交。这类的文档重点在限制条件：允许的格式与体积、频率上限、审核状态如何返回、失败时是部分成功还是整体拒绝。

关系与配置类通常是低频但关键的读取，比如友情链接与联系方式，外部页面与移动端会用来自家展示，字段命名与空值处理要稳定。

批量类是导入接口，用于把外部内容管理系统或表格里的历史数据搬进来，属于一次性但风险最高的调用。

文档该给参数还是给示例

两者都要，但顺序不同。参数表解决「能不能调通」：名称、类型、必填、取值范围、默认值。示例解决「调通之后怎么用」：一次典型请求、一次完整返回、一次错误返回。

只给示例不给参数表，调用方会猜边界；只给参数表不给示例，字段语义仍然含糊。返回结构里的字段含义建议逐条写，尤其是状态类字段——文档处于正式、草稿、待发布还是回收站，直接决定外部是否应当展示。AnQiCMS 的文档状态分为正式文档、草稿、待发布与回收站，删除正式文档是移入回收站而非物理删除，这层语义如果不在接口文档写明，调用方会把回收站当成不存在。

内容模型自定义带来的字段差异也要说明：自定义字段在不同模型下的名称与类型可能不同，公开接口需要给出扩展字段的读取方式，AnQiCMS 支持自定义内容模型与自定义字段，这类站点尤其需要写清扩展字段的读法。

鉴权与暴露范围写在哪

鉴权说明要写在每个类别的开头，而不是集中在文末附录。要回答三个问题：这个接口需要什么凭据、凭据怎么传递、哪些角色能调。凭据本身不要在文档里给出示例值，用占位名称表示即可。

暴露范围更需要明确：不是所有能力都适合对外开放。AnQiCMS 的 MCP 接口按意图域设置暴露范围，备份、升级与多站点这类全站级操作默认关闭，需要显式开启；工具面基于意图目录统一收敛，写操作支持回合级批量审批，外部客户端可以先看到待执行动作再确认。对文档作者来说，这意味着「能力清单」是分层的：公开可读、需鉴权可写、默认关闭需显式开启，三层要分开写，不能混成一张表。

批量导入接口的位置

批量导入通常不属于日常接口，但它是迁移与内容流水线的入口。AnQiCMS 提供导入接口 /api/import/archive，支持按标题查询内容是否已存在，用于批量导入场景；站内同时支持 ZIP 压缩包与 Excel 表格两种批量导入方式。

文档里这一节至少要写四件事：文件结构与命名约定、重复标题如何处理、失败项是否可重试、导入后内容是草稿还是直接发布。把这四项写清，能避免外部脚本反复重跑造成同一批内容被写入多次。

常见问题

接口文档多久更新一次？ 每次涉及字段、状态口径或鉴权方式变更时更新，并在版本记录里留一条说明，调用方需要能追溯变更点。

要不要公开全部能力？ 不必。默认对外只开放读取与必要的写入能力，全站级操作保持在需显式开启的状态。

写入接口最容易被忽略的是什么？ 频率限制与幂等约定。两者不写清，重试脚本会直接放大成脏数据。

返回结构变了怎么通知？ 用版本号区分接口版本，保留旧版本一段时间，并在文档中标注废弃时间与替代字段。