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

后端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点击查看免费下载导读/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给出了该端点最基本的调用契约本文档整理如下项目值Method方法GETURL地址https://api.spacexdata.com/v4/payloadsAuth required鉴权False公开接口无需 API KeySuccess Code成功响应码200 OK从源码层面看该路由在 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-age300响应头。缓存中间件实现在 middleware/cache.js它仅在NODE_ENVproduction环境下生效缓存键由方法 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。二者的字段名、类型与默认值一一对应是理解该端点的权威依据。基础属性字段字段类型默认值说明nameStringnull唯一索引载荷名称如 Tintin A BSchema 中标记unique: truetypeStringnull载荷类型如Satellite、Dragon 1.1、Crew Dragon等reusedBooleanfalse载荷是否为复用件launchUUIDObjectIdnull关联的发射任务 ID外键引用Launch集合customersString[]—载荷客户列表如[SpaceX]norad_idsNumber[]—NORAD 卫星编号列表Tintin 测试星即对应 43216、43217 两个编号nationalitiesString[]—载荷所属国家/地区列表manufacturersString[]—载荷制造商列表质量字段字段类型默认值说明mass_kgNumbernull载荷质量千克mass_lbsNumbernull载荷质量磅示例中 800 kg 对应 1763.7 lbs轨道信息字段字段类型默认值说明orbitStringnull轨道类型缩写如SSO太阳同步轨道、LEO、GTO、ISS等reference_systemStringnull参考系示例为geocentric地心regimeStringnull轨道区域分类如low-earth近地轨道、geostationary等longitudeNumbernull定点经度对地球静止轨道卫星有意义其余轨道为nullTLE 轨道根数开普勒根数字段这批字段描述载荷的实时轨道源数据来自两行轨道根数TLE解算字段类型默认值含义以示例值为例semi_major_axis_kmNumbernull轨道半长轴示例 6737.42 kmeccentricityNumbernull轨道离心率示例 0.0012995接近正圆periapsis_kmNumbernull近地点高度示例 350.53 kmapoapsis_kmNumbernull远地点高度示例 368.04 kminclination_degNumbernull轨道倾角示例 97.4444°太阳同步轨道特征period_minNumbernull轨道周期分钟示例 91.727 minlifespan_yearsNumbernull设计寿命年epochStringnullTLE 历元时间ISO 8601如2020-06-13T13:46:31.000Zmean_motionNumbernull平均运动角速度圈/天示例 15.69864906raanNumbernull升交点赤经 RAAN度示例 176.6734arg_of_pericenterNumbernull近地点幅角度示例 174.2326mean_anomalyNumbernull平近点角度示例 185.9087dragon 嵌套对象龙飞船返回舱信息当载荷由龙飞船运输并涉及回收返回时dragon对象携带返回数据否则所有子字段均为null。其子结构同样定义在 models/payloads.js 中字段类型默认值说明capsuleUUIDObjectIdnull关联的龙飞船 Capsule ID外键引用Capsule集合mass_returned_kgNumbernull返回质量千克mass_returned_lbsNumbernull返回质量磅flight_time_secNumbernull在轨飞行时长秒manifestStringnull返回载荷清单描述water_landingBooleannull是否溅落海面回收land_landingBooleannull是否陆地着陆回收从源码可以确认的额外事实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:GETURL:https://api.spacexdata.com/v4/payloads/:idURL Parameters:id[string]其中id为载荷 ID即上文中响应里的id字段如5eb0e4c6b6c3bb0006eeb21e。Auth required:FalseSuccess 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.mdMethod:POSTURL:https://api.spacexdata.com/v4/payloads/queryAuth required:FalseBody: 一个包含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 } }示例三弹出关联文档populatelaunch与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设计【免费下载链接】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 载荷详情接口实战深入解析 GET /v4/payloads/:id 端点SpaceX API 载荷详情接口实战深入解析 GET /v4/payloads/:id 端点 本文以开源项目 SpaceX API 的官方文档 docs/p后端API设计SpaceX-API Landing Pad 数据模型详解v4 Schema 字段全解析与查询实战SpaceX API Landing Pad 数据模型详解v4 Schema 字段全解析与查询实战 Landing Pad着陆场是 SpaceX 火箭一级后端API设计SpaceX-API v4 Payloads 查询接口完全指南POST /v4/payloads/query 的过滤、分页与字段填充实战SpaceX API v4 Payloads 查询接口完全指南POST /v4/payloads/query 的过滤、分页与字段填充实战 POST /v4/p后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考