SpaceX-API v4 Payloads 查询接口完全指南：POST /v4/payloads/query 的过滤、分页与字段填充实战

后端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点击查看免费下载POST /v4/payloads/query是 SpaceX-API 中用于批量检索有效载荷Payload数据的核心查询端点它把 MongoDB 的find()查询语法与 mongoose-paginate-v2 的分页能力开放给调用方让开发者可以按类型、轨道参数、质量、客户等多个维度自由过滤数据。读完本文你将掌握该端点的请求体结构、分页元数据语义、$text全文检索、跨集合populate字段填充等全部实战用法并能在自己的应用中直接复用这些查询模式。接口概览该端点与docs/payloads/v4/query.md中描述的一致属于公开接口无需认证即可调用项目值请求方法POST请求 URLhttps://api.spacexdata.com/v4/payloads/query认证要求False请求头Content-Type: application/json成功状态码200 OK失败状态码400 Bad Request请求体是一个 JSON 对象由query和options两个字段构成{ query: {}, options: {} }其中query接受任何合法的 MongoDBfind()查询语句options接受 mongoose-paginate-v2 定义的分页与投影参数。在源码 routes/payloads/v4/index.js 中可以看到该路由将请求体解构后直接交给Payload.paginate(query, options)处理query、options均带有默认空对象因此即使发送空请求体也不会报错router.post(/query, cache(300), async (ctx) { const { query {}, options {} } ctx.request.body; try { const result await Payload.paginate(query, options); ctx.status 200; ctx.body result; } catch (error) { ctx.throw(400, error.message); } });请求体详解query 与 options完整的查询与分页规范见仓库文档 docs/queries.md本端点完全遵循该通用规范。queryMongoDB 过滤条件query支持 MongoDB 的全部查询操作符例如精确匹配{ type: Satellite }范围操作{ mass_kg: { $gte: 1000 } }逻辑组合{ $or: [...] }、{ $and: [...] }数组匹配{ norad_ids: { $in: [43216, 43217] } }全文检索{ $text: { $search: dragon } }options分页与投影options支持的常用参数如下完整列表可参见 mongoose-paginate-v2 文档参数类型说明selectObject | String指定返回的字段默认返回全部字段sortObject | String排序规则如{ mass_kg: desc }offsetNumber跳过前 N 条记录与page二选一pageNumber页码从 1 开始limitNumber每页返回条数paginationBoolean设为false时返回全部文档不加 limit 限制默认truepopulateArray | Object | String用其他集合的文档填充引用字段一个将二者组合使用的完整请求示例{ query: { reused: true, mass_kg: { $gte: 500 } }, options: { sort: { mass_kg: desc }, limit: 10, select: { name: 1, type: 1, mass_kg: 1 } } }对应的curl命令curl -X POST https://api.spacexdata.com/v4/payloads/query \ -H Content-Type: application/json \ -d {query:{reused:true,mass_kg:{$gte:500}},options:{sort:{mass_kg:desc},limit:10,select:{name:1,type:1,mass_kg:1}}}成功响应分页元数据与文档数组查询成功返回200 OK响应体是 mongoose-paginate-v2 的标准分页结构。下面是从 docs/payloads/v4/query.md 继承的完整响应示例以Tintin A B双星任务为例{ docs: [ { dragon: { capsule: null, mass_returned_kg: null, mass_returned_lbs: null, flight_time_sec: null, manifest: null, water_landing: null, land_landing: null }, name: Tintin A B, type: Satellite, reused: false, launch: 5eb87d14ffd86e000604b361, customers: [ SpaceX ], norad_ids: [ 43216, 43217 ], nationalities: [ United States ], manufacturers: [ SpaceX ], mass_kg: 800, mass_lbs: 1763.7, orbit: SSO, reference_system: geocentric, regime: low-earth, longitude: null, semi_major_axis_km: 6737.42, eccentricity: 0.0012995, periapsis_km: 350.53, apoapsis_km: 368.04, inclination_deg: 97.4444, period_min: 91.727, lifespan_years: 1, epoch: 2020-06-13T13:46:31.000Z, mean_motion: 15.69864906, raan: 176.6734, arg_of_pericenter: 174.2326, mean_anomaly: 185.9087, id: 5eb0e4c6b6c3bb0006eeb21e } ], totalDocs: 136, offset: 0, limit: 10, totalPages: 14, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: true, prevPage: null, nextPage: 2 }docs数组之外的字段即为分页元数据含义如下字段含义totalDocs满足query条件的文档总数offset本次查询跳过的文档数limit每页条数本例为默认值 10totalPages总页数page当前页码pagingCounter当前页第一条记录在全部结果中的序号从 1 开始hasPrevPage/hasNextPage是否存在上一页 / 下一页prevPage/nextPage上一页 / 下一页页码不存在时为nullPayload 文档字段说明docs中每个元素对应一条有效载荷记录字段定义与 docs/payloads/v4/schema.md 及 models/payloads.js 中的 Mongoose Schema 完全一致基础信息字段字段类型说明nameString有效载荷名称唯一且在模型层建有全文索引见下文typeString载荷类型如Satellite、Dragon 1.0等reusedBoolean是否复用默认falselaunchObjectId关联的发射记录 ID引用Launch集合customers[String]客户列表norad_ids[Number]NORAD 编目编号nationalities[String]所属国家 / 地区manufacturers[String]制造商列表mass_kg/mass_lbsNumber载荷质量千克 / 磅轨道参数字段对应 TLE 轨道根数未入轨的载荷为null字段说明orbit轨道类型如SSO太阳同步轨道、LEO、GTO等reference_system参考坐标系如geocentricregime轨道区域如low-earthlongitude定点经度地球静止轨道载荷使用semi_major_axis_km半长轴公里eccentricity偏心率periapsis_km/apoapsis_km近地点 / 远地点高度公里inclination_deg轨道倾角度period_min轨道周期分钟lifespan_years设计寿命年epoch轨道数据的纪元时间mean_motion平均运动圈 / 天raan升交点赤经度arg_of_pericenter近地点幅角度mean_anomaly平近点角度dragon 嵌套对象当载荷搭载于龙飞船时填充以下字段——capsule引用Capsule集合的 ObjectId、mass_returned_kg/mass_returned_lbs返回质量、flight_time_sec飞行时长、manifest载荷清单、water_landing/land_landing水上 / 陆上着陆标志。另外注意响应中的标识符字段是id而非 MongoDB 默认的_id——这是模型通过mongoose-id插件见 models/payloads.js自动转换的结果。源码级实现原理全文索引与 $text 搜索模型层在name字段上显式声明了文本索引models/payloads.jsconst index { name: text, }; payloadSchema.index(index);这从实现层面印证了 docs/queries.md 中所有字符串字段都会被索引的说明——就 Payload 而言全文检索实际覆盖了name字段。因此可以这样搜索名称中包含关键字的载荷{ query: { $text: { $search: dragon } } }跨集合引用与 populate由于launch和dragon.capsule在模型中分别声明了ref: Launch与ref: Capsule见 models/payloads.js它们本质上是以 UUID 形式存于其他集合的文档引用。通过populate可以在一次请求中把 UUID 替换为完整对象。例如查询全部载荷并填充关联的发射信息{ query: {}, options: { populate: [launch] } }也可以只填充龙飞船胶囊字段{ options: { populate: [ { path: dragon.capsule } ] } }populate还支持嵌套与字段裁剪。比如在填充launch的同时仅返回载荷的name字段{ options: { populate: [ { path: launch, select: { name: 1, date_utc: 1 } } ], select: { name: 1, launch: 1 } } }反向的经典场景见 docs/queries.md/v4/launches/query端点中payloads数组存放载荷 UUID可通过{options: {populate: [payloads]}}填充为完整载荷对象同样可以嵌套填充载荷内的launch字段实现发射 → 载荷 → 发射的递归展开。缓存机制路由注册时使用了cache(300)中间件routes/payloads/v4/index.jsTTL 为 300 秒。从 middleware/cache.js 的实现可以看出仅在生产环境NODE_ENV production且 Redis 可用时启用缓存缓存键由方法 URL 请求体经 BLAKE3 哈希生成因此不同的查询条件会命中不同的缓存条目POST属于缓存白名单方法命中时返回spacex-api-cache: HIT响应头未命中写入后返回MISS非生产环境或 Redis 不可用时中间件直接放行不影响接口可用性。这意味着高频且稳定的查询条件可以享受最多 5 分钟的响应提速。实战查询示例以下示例均直接可复制到curl或 Postman 中验证。1. 获取全部载荷默认分页每页 10 条curl -X POST https://api.spacexdata.com/v4/payloads/query \ -H Content-Type: application/json \ -d {query:{}, options:{}}2. 按类型过滤 按质量排序 分页{ query: { type: Satellite }, options: { sort: { mass_kg: desc }, page: 2, limit: 20 } }3. 范围查询质量超过 1000 kg 且已复用的载荷{ query: { mass_kg: { $gte: 1000 }, reused: true } }4. 组合逻辑属于指定轨道区域或质量大于阈值{ query: { $or: [ { regime: low-earth }, { mass_kg: { $gt: 2000 } } ] } }5. 关闭分页一次性返回全部结果{ query: { customers: SpaceX }, options: { pagination: false } }注意pagination: false会返回全部匹配文档适合数据量可预期的场景对大型结果集仍建议显式使用limit。6. 字段裁剪与填充组合{ query: {}, options: { select: { name: 1, type: 1, mass_kg: 1, launch: 1 }, populate: [ { path: launch, select: { flight_number: 1, name: 1 } } ], sort: { mass_kg: desc }, limit: 5 } }错误响应当query或options中传入非法语法例如操作符拼写错误、字段类型不匹配时接口返回400 Bad Request响应体为 Mongoose 抛出的原始错误信息其中附带修复建议。该行为来自路由的catch分支routes/payloads/v4/index.js例如在query中写入{mass_kg: {$gte: not-a-number}}这类类型错误的表达式就会收到包含具体字段与期望类型的错误提示。相关端点如果需要按单个 ID 或全量方式获取数据可以搭配同目录下的其他端点GET /v4/payloads一次性返回全部载荷无分页GET /v4/payloads/:id按id获取单条载荷不存在时返回404 Not Found。结合 docs/queries.md 中给出的日期范围查询与全文检索模式你还可以把本指南中的$gte/$lte、$text、populate等技巧自由组合构建出满足业务需要的复杂载荷数据查询管线。赞分享后端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 龙飞船查询接口POST /v4/dragons/query实战指南MongoDB 风格过滤与分页SpaceX API 龙飞船查询接口POST /v4/dragons/query实战指南MongoDB 风格过滤与分页 本文以 SpaceX API 开源后端API设计SpaceX-API Launch 查询接口实战指南使用 POST /v4/launches/query 实现 MongoDB 聚合查询与分页SpaceX API Launch 查询接口实战指南使用 POST /v4/launches/query 实现 MongoDB 聚合查询与分页 本文基于 Sp后端API设计SpaceX-API v4 Rockets Query 接口详解使用 POST /v4/rockets/query 实现火箭数据的复杂查询与分页SpaceX API v4 Rockets Query 接口详解使用 POST /v4/rockets/query 实现火箭数据的复杂查询与分页 本文以 Sp后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考