深入解析 SpaceX-API v4 payloads 端点：载荷数据获取、字段模型与查询实践

• 后端
• API设计

导读

/v4/payloads是开源项目 SpaceX-API 中用于查询 SpaceX 发射任务所搭载有效载荷（Payload）数据的核心 REST 端点，涵盖卫星、龙飞船货运等各类载荷的基本信息、轨道根数与返回数据。本文以 docs/payloads/v4/all.md 为主干，结合同目录下的字段 Schema、单条查询与 Query 文档，并对照仓库中models/payloads.js与routes/payloads/v4/index.js的实际实现，完整讲解该端点的方法、参数、响应结构与底层存储模型。读完本文，你将能够直接调用该端点获取全量载荷列表，理解每个字段的含义与默认值，并熟练使用:id单条查询与/query分页检索来构建自己的数据应用。

端点总览：方法、URL 与鉴权

all.md给出了该端点最基本的调用契约，本文档整理如下：

从源码层面看，该路由在 routes/payloads/v4/index.js 中定义，路由前缀为/(v4|latest)/payloads，意味着v4与latest两个版本路径指向同一实现：

const router = new Router({ prefix: '/(v4|latest)/payloads', }); // Get all payloads router.get('/', cache(300), async (ctx) => { try { const result = await Payload.find({}); ctx.status = 200; ctx.body = result; } catch (error) { ctx.throw(400, error.message); } });

可以看到该路由在进入业务逻辑前套用了cache(300)中间件，即响应会被 Redis 缓存 300 秒，并附带Cache-Control: max-age=300响应头。缓存中间件实现在 middleware/cache.js，它仅在NODE_ENV=production环境下生效，缓存键由方法 + URL + 请求体经 BLAKE3 哈希后生成，命中时响应头会标记spacex-api-cache: HIT，未命中则为MISS。

成功响应：全量载荷列表 JSON 解析

对GET https://api.spacexdata.com/v4/payloads发起请求后，接口返回一个 JSON数组（注意是数组而非对象），数组中每个元素代表一个载荷。原文档示例给出了首个元素（名为 "Tintin A & B" 的猎鹰 9 号双星测试载荷）的完整结构：

[ { "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" }, ... ]

响应元素大致可划分为四个语义分组：龙飞船返回模块信息（dragon）、载荷基础属性（名称/类型/复用/客户等）、质量与轨道信息（质量、轨道参数）、以及TLE 轨道根数（semi_major_axis_km 至 mean_anomaly）。下面结合 Schema 文档逐一说明每个字段的数据类型与含义。

Payload 数据模型：Schema 与字段逐项解读

载荷的数据结构定义在两处，且完全一致：一处是面向 API 使用者的文档 docs/payloads/v4/schema.md，另一处是驱动接口的 Mongoose Schema 源码 models/payloads.js。二者的字段名、类型与默认值一一对应，是理解该端点的权威依据。

基础属性字段

质量字段

轨道信息字段

TLE 轨道根数（开普勒根数）字段

这批字段描述载荷的实时轨道，源数据来自两行轨道根数（TLE）解算：

dragon 嵌套对象（龙飞船返回舱信息）

当载荷由龙飞船运输并涉及回收返回时，dragon对象携带返回数据；否则所有子字段均为null。其子结构同样定义在 models/payloads.js 中：

从源码可以确认的额外事实：name字段建立了全文检索文本索引（models/payloads.js 中payloadSchema.index({ name: 'text' })），因此/query接口支持针对name的$text全文搜索；同时模型挂载了mongoose-paginate-v2与mongoose-id两个插件，前者为/query端点提供分页能力，后者将_id序列化为字符串形式的id字段输出。

获取单个载荷：GET /v4/payloads/:id

当需要获取某个具体载荷时，使用 docs/payloads/v4/one.md 描述的路径参数版本：

Method:GET

URL:https://api.spacexdata.com/v4/payloads/:id

URL Parameters:id=[string]，其中id为载荷 ID（即上文中响应里的id字段，如5eb0e4c6b6c3bb0006eeb21e）。

Auth required:False

Success Response—200 OK，返回单个载荷对象，结构与全量列表中的元素完全一致（同样是 Tintin A & B 的完整字段，此处不再重复列出）。

Error Response—404 NOT FOUND，内容为Not Found，表示该 ID 不存在。

对应源码在 routes/payloads/v4/index.js：

// Get one payload router.get('/:id', cache(300), async (ctx) => { const result = await Payload.findById(ctx.params.id); if (!result) { ctx.throw(404); } ctx.status = 200; ctx.body = result; });

当 MongoDB 中找不到对应文档时，Mongoose 的findById返回null，路由随即抛出 404，与文档中的错误响应行为一致。

分页查询：POST /v4/payloads/query

请求与响应

/v4/payloads/query是查询引擎端点，采用POST方法（docs/payloads/v4/query.md）：

Method:POST

URL:https://api.spacexdata.com/v4/payloads/query

Auth required:False

Body: 一个包含query与options两个键的 JSON 对象：

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

• query接受任意合法的 MongoDBfind()查询条件；
• options接受 mongoose-paginate-v2 的分页选项（select、sort、limit、page、offset、populate等），完整说明见仓库根目录的查询指南 docs/queries.md。

Success Response—200 OK。与全量列表不同，此处返回分页包装对象而非裸数组，除docs数组（存放载荷文档）外还包含totalDocs（文档总数）、offset、limit、totalPages、page、pagingCounter、hasPrevPage、hasNextPage、prevPage、nextPage等分页元数据。示例响应中totalDocs为 136、totalPages为 14、hasNextPage为true，表明按每页 10 条规则共有 14 页数据。

Error Response—400 Bad Request，此时接口返回 Mongoose 错误信息并附带修正建议，通常是因为查询条件写法不符合 MongoDB 语法。

后端实现要点

分页路由在 routes/payloads/v4/index.js 中的实现非常简洁，直接委托给模型的分页插件：

// Query payloads 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均有默认值{}，因此即使发送空 Body 也会返回默认分页结果（每页 10 条）。需要特别说明：query端点同样经过了cache(300)缓存中间件，且缓存键包含请求体内容（见 middleware/cache.js），所以不同的查询条件会生成不同的 Redis 缓存键，互不干扰。

三个可复用的查询示例

以下示例均可在 docs/queries.md 找到完整版，此处结合 payloads 场景给出可直接运行的配置。

示例一：按轨道类型过滤并排序

筛选所有太阳同步轨道（SSO）载荷，按质量降序取前 20 条：

{ "query": { "orbit": "SSO" }, "options": { "sort": { "mass_kg": "desc" }, "limit": 20 } }

示例二：全文检索载荷名称

由于name字段建立了文本索引，可通过$text运算符做全文搜索：

{ "query": { "$text": { "$search": "Tintin" } }, "options": { "limit": 5 } }

示例三：弹出关联文档（populate）

launch与dragon.capsule字段分别外键引用 Launch 与 Capsule 集合，存储的是 UUID 字符串。若需要在一次请求中把引用替换为完整文档，可使用options.populate，例如同时展开发射信息：

{ "query": { "launch": { "$ne": null } }, "options": { "limit": 10, "populate": ["launch"] } }

更复杂的嵌套 populate（如先展开launch再展开其中的rocket）及字段筛选用法，参见 docs/queries.md 的 Populate 章节。

直接调用：curl 实战

无需注册或携带 Token，可直接用 curl 验证上述三个端点。以下命令在终端即可运行：

# 1. 获取全部载荷（返回数组） curl -s https://api.spacexdata.com/v4/payloads | head -c 2000 # 2. 获取单个载荷（将 :id 替换为真实 ID，如示例中的 Tintin A & B） curl -s https://api.spacexdata.com/v4/payloads/5eb0e4c6b6c3bb0006eeb21e # 3. 分页查询：筛选质量为空的载荷并弹出 launch 信息 curl -s -X POST https://api.spacexdata.com/v4/payloads/query \ -H "Content-Type: application/json" \ -d '{ "query": { "mass_kg": { "$ne": null } }, "options": { "limit": 3, "populate": ["launch"] } }'

由于接口有 300 秒 Redis 缓存，重复请求同一 URL 时可通过响应头spacex-api-cache: HIT与spacex-api-cache-online观察缓存命中情况（该机制仅在生产环境启用，见 middleware/cache.js）。

小结与延伸阅读

• 三个入口：GET /v4/payloads（全量数组）、GET /v4/payloads/:id（单条）、POST /v4/payloads/query（分页+条件+populate），全部公开免鉴权。
• 字段模型：载荷文档由基础属性、质量、轨道信息、TLE 轨道根数与嵌套的dragon返回模块组成，完整定义见 models/payloads.js 与 docs/payloads/v4/schema.md。
• 版本兼容：路由前缀/(v4|latest)/payloads表明latest别名指向相同实现，后续可通过 docs/launches/v5 了解 v5 系列的数据演进思路。

若需要围绕载荷做关联分析，可配合以下仓库文档交叉使用：

• 载荷字段launch关联的发射接口：docs/launches/v4/query.md
• 载荷dragon.capsule关联的龙飞船接口：docs/capsules/v4/all.md
• 查询与分页通用指南：docs/queries.md

• 后端
• API设计