如何通过AnQiCMS获取指定模型（`moduleId`）的最新文档列表？

在网站内容管理中，我们常常需要动态地展示某一类内容的最新更新，例如新闻文章、产品发布或是博客动态。对于使用 AnQiCMS 搭建的网站而言，借助其提供的强大 API 接口，获取指定模型下的最新文档列表是一项非常基础且实用的操作。这不仅能帮助开发者快速构建动态页面，也能为用户提供及时更新的信息，优化网站的用户体验。

要实现这一功能，我们主要会用到 AnQiCMS 提供的 /api/archive/list 文档列表接口。这个接口设计得非常灵活，通过组合不同的参数，我们可以精确地筛选、排序并获取所需的内容。

理解 archive/list 接口

首先，我们来了解一下这个核心接口。它的调用地址通常是 {域名地址}/api/archive/list，并通过 GET 方法发送请求。这里的 {域名地址} 需要替换成您实际的网站域名，例如 https://www.anqicms.com/api/archive/list。

这个接口有很多参数，但为了获取指定模型下的最新文档列表，我们需要特别关注以下几个：

1. moduleId (模型 ID)：这是请求中必不可少的一个参数。每个在 AnQiCMS 后台创建的内容模型（例如“文章”、“产品”等）都有一个唯一的数字 ID。通过指定 moduleId，我们告诉系统我们想获取的是哪个模型下的文档。
2. order (排序方式)：这是实现“最新”效果的关键。AnQiCMS 支持根据多个字段进行排序，其中与时间相关的有 created_time（发布时间）和 updated_time（更新时间）。为了获取最新内容，我们会将其设置为 created_time desc 或 updated_time desc，其中 desc 表示降序排列，即最新的在前。
3. limit (显示数量)：这个参数用来控制您希望获取多少条最新文档。例如，如果您想显示最近的 5 篇文章，就可以设置 limit=5。如果需要从某一条记录开始获取一定数量的数据，也可以使用 offset,limit 的格式，比如 limit=2,10 表示从第 3 条开始获取 10 条数据。
4. type (列表类型)：默认情况下，type 的值为 list，它会直接返回指定数量的文档。如果您需要进行分页展示（例如，显示总页数或总条数），则可以将 type 设置为 page，此时配合 page 参数可以获取指定页码的内容。不过，对于简单的“最新列表”需求，保持默认的 type=list 即可。

实际操作示例

假设您的“文章”模型的 moduleId 是 1，您现在想获取该模型下最新发布的 5 篇文章。您可以通过以下方式构造 API 请求：

GET {您的域名}/api/archive/list?moduleId=1&order=created_time desc&limit=5

当您发送这个 GET 请求后，AnQiCMS 将会返回一个 JSON 格式的数据。成功的情况下，code 字段会是 0，而 data 字段则会包含您请求的文档列表。

返回的数据结构大致如下：

{
  "code": 0,
  "data": [
    {
      "id": 101,
      "created_time": 1705000000, // 较新的发布时间
      "updated_time": 1705000050, // 较新的更新时间
      "title": "AnQiCMS新功能发布：AI智能写作模块上线！",
      "description": "详细介绍AnQiCMS最新推出的AI智能写作功能，帮助您高效创作内容。",
      "module_id": 1,
      "category_id": 5,
      "views": 120,
      "thumb": "https://yourdomain.com/uploads/images/ai-feature.webp",
      "link": "https://yourdomain.com/news/101.html",
      // ... 其他文档信息
    },
    {
      "id": 100,
      "created_time": 1704900000,
      "updated_time": 1704900030,
      "title": "AnQiCMS 3.0版本更新日志",
      "description": "回顾AnQiCMS 3.0版本的各项优化与改进，提升您的使用体验。",
      "module_id": 1,
      "category_id": 1,
      "views": 150,
      "thumb": "https://yourdomain.com/uploads/images/version-3.0.webp",
      "link": "https://yourdomain.com/news/100.html",
      // ... 其他文档信息
    }
    // ... 剩余3条最新文档
  ],
  "msg": ""
}

在返回的 data 数组中，每一项都是一个文档对象。您可以轻松从中提取 title（标题）、description（简介）、thumb（缩略图）、link（文档链接）等信息，并将其呈现在您的网站或应用界面上。created_time 和 updated_time 字段是以 Unix 时间戳的形式返回的，您可以将其转换为可读的日期格式。

实用技巧与**实践

• 明确 moduleId： 在您的 AnQiCMS 后台，进入“内容模型”管理界面，可以查看到每个模型的 ID。确保您使用的 moduleId 是正确的。
• 灵活运用 order 参数： 除了 created_time desc，您还可以尝试 updated_time desc 来获取最近修改的文档，或者 views desc 来获取热门文档。
• 适度设置 limit： 根据页面布局和内容展示需求，合理设置 limit 值，避免一次性请求过多数据，影响加载速度。
• 错误处理机制： 在前端或后端代码中集成 API 调用时，务必检查返回的 code 字段。如果 code 不为 0，则表示请求失败，此时可以通过 msg 字段获取错误原因，并进行相应的处理或提示。

通过上述方法，您可以轻松地利用 AnQiCMS 的 API 获取任何指定内容模型下的最新文档列表，为您的网站或应用注入活力。

---

常见问题 (FAQ)

Q1: 我如何知道我的内容模型的 moduleId 是什么？ A1: 您可以在 AnQiCMS 后台管理界面找到 moduleId。通常在“系统设置”或“内容模型”相关菜单中，每个模型都会显示其对应的 ID。例如，点击某个内容模型的编辑页面，URL 中或模型名称旁边通常会标注该模型的 ID。您也可以通过调用 /api/module/list 接口获取所有内容模型的列表，其中会包含 id 和 title 字段。

Q2: 如果我需要获取某个分类（而不是整个模型）下的最新文档，应该怎么操作？ A2: 如果您只想获取某个特定分类下的最新文档，可以在 archive/list 接口中额外增加 categoryId 参数，并将其值设置为目标分类的 ID。例如，GET {您的域名}/api/archive/list?moduleId=1&categoryId=10&order=created_time desc&limit=5 会获取模型 ID 为 1、分类 ID 为 10 的最新 5 篇文章。您可以在 AnQiCMS 后台的“分类管理”中找到对应分类的 ID。

Q3: 如何确保我的网站能持续获取到最新内容，而不会因为 API 请求频率过高导致问题？ A3: 对于频繁访问的“最新文档”列表，建议在您的服务器端或前端（根据实际情况）实施缓存机制。例如，每隔 5-10 分钟请求一次 API 更新数据，然后将数据缓存起来供用户访问，而不是每次页面加载都直接请求 API。这样可以显著降低 API 请求压力，同时提高页面加载速度。