企业官网建设流程全解析

• 后端
• API设计

POST /v4/payloads/query是 SpaceX-API 中用于批量检索有效载荷（Payload）数据的核心查询端点，它把 MongoDB 的find()查询语法与 mongoose-paginate-v2 的分页能力开放给调用方，让开发者可以按类型、轨道参数、质量、客户等多个维度自由过滤数据。读完本文，你将掌握该端点的请求体结构、分页元数据语义、$text全文检索、跨集合populate字段填充等全部实战用法，并能在自己的应用中直接复用这些查询模式。

接口概览

该端点与docs/payloads/v4/query.md中描述的一致，属于公开接口，无需认证即可调用：

请求体是一个 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，本端点完全遵循该通用规范。

query：MongoDB 过滤条件

query支持 MongoDB 的全部查询操作符，例如：

• 精确匹配：{ "type": "Satellite" }
• 范围操作：{ "mass_kg": { "$gte": 1000 } }
• 逻辑组合：{ "$or": [...] }、{ "$and": [...] }
• 数组匹配：{ "norad_ids": { "$in": [43216, 43217] } }
• 全文检索：{ "$text": { "$search": "dragon" } }

options：分页与投影

options支持的常用参数如下（完整列表可参见 mongoose-paginate-v2 文档）：

一个将二者组合使用的完整请求示例：

{ "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数组之外的字段即为分页元数据，含义如下：

Payload 文档字段说明

docs中每个元素对应一条有效载荷记录，字段定义与 docs/payloads/v4/schema.md 及 models/payloads.js 中的 Mongoose Schema 完全一致：

基础信息字段

轨道参数字段（对应 TLE 轨道根数，未入轨的载荷为null）

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.js）：

const 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.js），TTL 为 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设计