4. 日志检索API需求分析：查询条件设计、分页与排序、时间范围过滤、字段筛选

日志检索API是准入门禁自助服务的核心数据接口，其设计质量直接影响运维人员排查效率与系统可用性。本章从四个维度展开需求分析：查询条件组合、分页与排序策略、时间范围过滤机制以及字段筛选与投影。每个维度均需兼顾功能完备性与性能开销，避免因设计缺陷导致接口响应缓慢或数据不完整。

4.1 查询条件设计：组合过滤与精确匹配

日志检索的查询条件通常包含精确匹配、模糊匹配、多值枚举与范围查询四种类型。设计时应遵循以下原则：

• 精确匹配：用于设备ID、用户ID、门禁点编号等唯一标识字段，采用等值查询。
• 模糊匹配：用于人员姓名、备注信息等文本字段，支持前缀或通配符搜索，但需限制通配符长度防止性能劣化。
• 多值枚举：用于事件类型（如“刷卡通过”“非法闯入”“超时未关”），允许一次传入多个值，内部以IN子句实现。
• 范围查询：用于数值型字段（如温度、电压、信号强度），支持大于、小于、区间等操作符。

以下为查询条件参数的典型结构：

{
  "filters": [
    { "field": "device_id", "operator": "eq", "value": "D001" },
    { "field": "event_type", "operator": "in", "value": ["access_granted", "access_denied"] },
    { "field": "person_name", "operator": "like", "value": "张%" },
    { "field": "signal_strength", "operator": "gte", "value": -70 }
  ],
  "logic": "AND"
}

4.2 分页与排序：游标分页 vs 偏移分页

日志数据量通常随时间线性增长，选择合适的分页策略至关重要。下表对比了两种主流方案：

排序字段通常选择时间戳或自增ID，且必须与游标字段一致。API应同时支持升序（asc）与降序（desc），默认按时间降序排列以展示最新日志。

游标分页的请求与响应示例：

// 请求
GET /api/v1/logs?cursor=2025-03-21T14:30:00Z&limit=50&sort=event_time&order=desc

// 响应
{
  "data": [ ... ],
  "next_cursor": "2025-03-21T14:25:00Z",
  "has_more": true
}

4.3 时间范围过滤：精度与性能的平衡

时间范围过滤是日志检索中最频繁使用的条件。设计时需明确以下要点：

• 时间格式：统一使用ISO 8601标准（如 2025-03-21T14:30:00Z），避免时区歧义。API内部统一转为UTC处理，返回时可根据请求头中的时区偏好转换。
• 范围参数：使用 start_time 与 end_time 两个独立参数，左闭右开区间 [start, end)。
• 默认值：若不传时间范围，默认返回最近24小时数据，防止用户无意识拉取全量数据。
• 最大跨度限制：单次查询时间跨度不得超过30天，超出时返回400错误并提示用户分批查询。

时间范围过滤在请求中的位置：

{
  "start_time": "2025-03-20T00:00:00Z",
  "end_time": "2025-03-21T23:59:59Z",
  "filters": [ ... ],
  "pagination": {
    "cursor": null,
    "limit": 100
  }
}

4.4 字段筛选：按需投影减少传输开销

日志记录通常包含数十个字段（如设备信息、人员信息、时间戳、事件详情、原始报文等），但客户端往往只需要其中几个。字段筛选（Field Selection）允许调用方指定返回字段，从而降低网络传输量与序列化开销。

设计规范：

• 使用 fields 参数传入逗号分隔的字段名列表。
• 若不传 fields，默认返回核心字段（id、event_time、event_type、device_id、person_id），避免返回完整大对象。
• 支持嵌套字段选择（如 device.name、person.department），但需限制嵌套深度不超过3层。

字段筛选请求示例：

GET /api/v1/logs?fields=id,event_time,event_type,device_id,person_name&cursor=...&limit=50

响应中仅包含请求的字段：

{
  "data": [
    {
      "id": "log_1001",
      "event_time": "2025-03-21T14:30:00Z",
      "event_type": "access_granted",
      "device_id": "D001",
      "person_name": "张三"
    }
  ],
  "next_cursor": "2025-03-21T14:25:00Z",
  "has_more": true
}

4.5 整体查询流程架构

下图展示了日志检索API从请求接收到结果返回的完整数据流，涵盖查询条件解析、分页游标处理、时间范围过滤与字段投影四个核心环节。

4.6 字段筛选与投影的SVG结构

下图进一步细化字段筛选的内部处理逻辑，展示如何从完整日志记录中按需提取指定字段并组装响应。

4.7 需求分析总结清单

以下表格汇总了日志检索API四个核心维度的设计要点与验收标准，供后续接口定义与开发参考：