SpaceX-API 查询与分页功能深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00707/article/details/148415419

SpaceX-API 查询与分页功能深度解析

SpaceX-API :rocket: Open Source REST API for SpaceX launch, rocket, core, capsule, starlink, launchpad, and landing pad data. 项目地址: https://gitcode.com/gh_mirrors/spa/SpaceX-API

前言

SpaceX-API 是一个提供 SpaceX 公司相关数据的接口服务，包含了火箭、发射任务、载荷等丰富信息。本文将重点解析该 API 强大的查询和分页功能，帮助开发者高效获取所需数据。

基础查询结构

SpaceX-API 的所有 /query 端点都遵循相同的请求格式：

{
  "query": {},
  "options": {}
}

query 对象：用于定义查询条件，支持完整的 MongoDB 查询语法
options 对象：用于配置返回结果的格式、分页等选项

查询条件详解

query 支持 MongoDB 的所有查询操作符，以下是几个典型应用场景：

1. 日期范围查询

{
  "query": {
    "date_utc": {
      "$gte": "2017-06-22T00:00:00.000Z",
      "$lte": "2017-06-25T00:00:00.000Z"
    }
  }
}

注意：日期必须使用 ISO 8601 格式

2. 全文搜索

{
  "query": {
    "$text": {
      "$search": "crs"
    }
  }
}

此功能会搜索集合中所有建立了文本索引的字段（默认所有字符串字段都会被索引）

3. 复合条件查询

{
  "query": {
    "date_utc": {
      "$gte": "2017-06-22T00:00:00.000Z",
      "$lte": "2017-06-25T00:00:00.000Z"
    },
    "$or": [
      {"flight_number": {"$gt": 30}},
      {"tbd": true}
    ],
    "date_precision": {
      "$in": ["month", "day"]
    }
  }
}

分页与结果控制

options 对象提供了丰富的配置选项：

常用选项

select：指定返回字段（1表示包含，0表示排除）
sort：排序规则（1升序，-1降序）
offset/page：分页位置
limit：每页记录数
pagination：是否启用分页
populate：关联文档填充

分页响应结构

{
  "docs": [],
  "totalDocs": 0,
  "offset": 0,
  "limit": 10,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

关联文档填充

SpaceX-API 使用 UUID 引用关联文档，通过 populate 选项可以获取完整的关联对象而非仅 ID。

基础填充示例

{
  "options": {
    "populate": ["payloads"]
  }
}

选择性字段填充

{
  "options": {
    "populate": [{
      "path": "payloads",
      "select": {"name": 1}
    }]
  }
}

嵌套填充

{
  "options": {
    "populate": [{
      "path": "payloads",
      "populate": [{
        "path": "launch"
      }]
    }]
  }
}

实用查询示例

获取下一次即将进行的发射

{
  "query": {"upcoming": true},
  "options": {
    "limit": 1,
    "sort": {"flight_number": "asc"}
  }
}

复杂分页查询

{
  "query": {
    "date_utc": {
      "$gte": "2017-01-01T00:00:00.000Z",
      "$lte": "2017-12-31T23:59:59.999Z"
    },
    "success": true
  },
  "options": {
    "select": {"name": 1, "date_utc": 1},
    "sort": {"date_utc": -1},
    "page": 2,
    "limit": 5,
    "populate": ["rocket", "payloads"]
  }
}