`archiveFilters`接口返回的`name`和`field_name`分别代表什么？

在安企CMS的开发和内容管理过程中，我们经常需要处理文档的筛选和展示。archiveFilters 接口正是为此而生，它提供了一种动态获取筛选条件的能力。理解其返回数据中的 name 和 field_name 字段，对于构建灵活多变的前端筛选功能至关重要。

name：用户友好的筛选条件显示名称

当我们通过 archiveFilters 接口获取文档筛选条件时，返回的数据中会包含一个 name 字段。这个 name 字段代表的是筛选条件的显示名称或用户友好名称。它以人类可读的语言（通常是中文）呈现，其主要作用是为了在网站前台界面向用户展示清晰直观的筛选选项。

例如，在接口返回的示例数据中，我们可以看到 name 为“城市”和“学历”。这些正是你通常会在页面上看到的，用于用户选择的标签。你可以将 name 理解为你在安企CMS后台为某个自定义字段定义的中文名称或描述，它直接面向最终用户，旨在提供良好的交互体验。

field_name：系统内部的筛选字段调用名称

与 name 字段相伴的是 field_name，它在功能上扮演着截然不同的角色。field_name 代表的是筛选条件的技术标识符或API调用名称。它通常是一个简短的英文单词或拼音，用于在后端逻辑和API请求中唯一识别某个筛选条件。

这个 field_name 是在安企CMS后台自定义字段设置时为字段定义的系统名称，它是系统内部用来处理数据和构建查询的键。举例来说，当 name 是“城市”时，其对应的 field_name 可能是“city”；当 name 是“学历”时，其 field_name 可能是“certificate”。

field_name 的核心作用在于它的唯一性和稳定性。当用户在前台界面选择了一个 name 为“城市”，选项为“北京”的筛选条件时，你的前端代码会利用其对应的 field_name “city”，将其作为参数传递给 archiveList 等接口。例如，请求 /api/archive/list?moduleId=1&city=北京，后端就能根据 field_name “city”准确地筛选出所有城市为“北京”的文档列表。

此外，在获取文档详情（archiveDetail）时，如果文档包含自定义字段，这些字段在 extra 对象中也是以 field_name 作为键名出现的。例如，extra 对象中可能会出现 author: { name: '作者', value: 'AnqiCMS', default: '' }，这里的 author 正是该自定义字段的 field_name。

name 与 field_name 的协作

简而言之，name 是提供给用户看的，方便用户理解和操作；而 field_name 则是提供给程序使用的，确保API调用和数据处理的准确性。这种分离的设计使得网站在拥有良好用户体验的同时，也能保持后端数据逻辑的清晰和高效。通过 archiveFilters 接口获取到这两者，开发者可以动态地构建各种筛选器，而无需硬编码筛选条件，从而极大地提升了网站的灵活性和可维护性。

常见问题解答 (FAQ)

1. 为什么需要同时存在 name 和 field_name 这两个字段？

这种设计旨在分离显示层和数据处理层。name 提供用户友好的界面展示，让用户能够轻松理解和选择筛选条件；而 field_name 则作为系统内部和API交互的唯一标识符，确保数据处理的准确性和稳定性。你可以将 name 视为标签，field_name 视为标签背后的“代码”。

2. field_name 可以随意修改吗？修改后会有什么影响？

通常不建议随意修改 field_name。因为 field_name 一旦设定，就可能在多个地方被引用，例如在 archiveList 接口的查询参数中，或者在 archiveDetail 返回的 extra 字段中作为键名。频繁修改可能会导致依赖此 field_name 的前端功能或第三方集成失效，因此在创建自定义字段时应慎重定义。

3. 如何在前端页面中利用 archiveFilters 返回的数据来构建筛选功能？

你可以遍历 archiveFilters 接口返回的 data 数组，使用每个项的 name 作为筛选按钮或下拉菜单的显示文本。当用户选择某个筛选条件后，获取其对应的 field_name 和 items 数组中选中项的 label（或实际值），然后将 field_name=label 作为查询参数，调用 archiveList 接口来获取筛选后的文档列表。这样可以实现动态、灵活的筛选功能。