SpaceX-API 发射任务数据模型深度解析：v5 Launch Schema 全字段详解与 Mongoose 实现对照

后端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 开源仓库中的 Launch Schema 文档 为骨架逐字段剖析/v5/launches接口返回的发射任务Launch数据模型——从必填字段、取值枚举、默认值到嵌套对象fairings、crew、cores、links与跨集合引用关系。文中不仅完整继承原文档的全部字段定义还对照仓库中 Mongoose 模型源码 与 路由实现帮助读者理解该 Schema 在数据写入、查询过滤、关联填充populate与自动数据同步中的真实行为从而在基于该开源 API 构建应用时能够精准地构造查询、解析响应并利用关联数据。一、Schema 总体概览一次发射任务需要描述什么在 SpaceX-API 中launches集合是数据关联度最高、结构最复杂的核心集合。一次发射Launch在 v5 数据模型中被建模为一张扁平的文档其字段可以划分为五个逻辑分组分组字段说明标识与排序flight_number、name、id发射编号、任务名称与文档唯一 ID时间相关date_utc、date_unix、date_local、date_precision、static_fire_date_utc、static_fire_date_unix、window发射与静态点火的时间戳及精度状态与结果upcoming、success、failures、details、tdb、net任务状态、成败记录与描述关联引用rocket、crew、ships、capsules、payloads、launchpad、cores、fairings指向其他集合的 ObjectId对外呈现为 UUID 字符串媒体与维护links、auto_update任务相关媒体链接与数据自动维护开关这一分组思路与仓库源码中 routes/launches/v5/index.js 的路由设计相互印证/past、/upcoming、/latest、/next四个便捷端点都直接依赖upcoming字段配合flight_number排序来筛选数据例如Launch.find({ upcoming: false }, null, { sort: { flight_number: asc } })。二、核心标量字段详解必填与枚举约束以下字段在 Schema 中均标记为required: true意味着写入数据库的每条发射记录都不可缺失这些字段。2.1 flight_number 与 nameflight_number: { type: Number, required: true }, name: { type: String, unique: true, required: true }flight_number发射序号Number是排序与检索历史任务的主要依据。v5 便捷端点统一按它升序asc或降序desc排序/past、/upcoming、/用升序/latest用降序。name任务名称String例如CRS-20、KoreaSat 5A。它带有unique: true约束在源码中对应name: { type: String, unique: true, required: true }见 models/launches.js保证同一任务名不会重复入库。2.2 时间戳三件套与精度枚举date_utc: { type: String, required: true }, date_unix: { type: Number, required: true }, date_local: { type: String, required: true }, date_precision: { type: String, required: true, enum: [half, quarter, year, month, day, hour] }同一时刻以三种形态冗余存储便于不同场景使用字段类型含义真实示例CRS-20date_utcStringUTC 时间的 ISO 8601 字符串2020-03-07T04:50:31.000Zdate_unixNumberUnix 时间戳秒1583556631date_localString发射场当地时间的 ISO 字符串2020-03-06T23:50:31-05:00date_precision是文档中带enum枚举约束的关键字段取值只能是half、quarter、year、month、day、hour六者之一描述上述日期被精确到的时间粒度。这一点在 models/launches.js 中被完整落地为 Mongoose 的enum校验器——如果写入非枚举值Mongoose 会抛出校验错误并反映在/query接口的400 Bad Request响应中。2.3 静态点火与任务状态字段static_fire_date_utc: { type: String, default: null }, static_fire_date_unix: { type: Number, default: null }, tdb: { type: Boolean, default: false }, net: { type: Boolean, default: false }, window: { type: Number, default: null }, success: { type: Boolean, default: null }, upcoming:{ type: Boolean, required: true }static_fire_date_utc/static_fire_date_unix静态点火Static Fire的时间任务尚未点火时默认为null。tdbTBD待定任务时间是否待定默认false。netNETNot Earlier Than该时间是否为不早于语义默认false。window发射窗口时长单位为秒Number例如 KoreaSat 5A 任务的窗口为8640秒。success任务是否成功true/false/null未执行时。upcoming是否即将发射必填布尔值是/past与/upcoming路由见 routes/launches/v5/index.js的过滤核心。2.4 failures 与 details任务失败明细failures: [ { time: { type: Number }, altitude: { type: Number }, reason: { type: String } } ], details: { type: String, default: null }failures是对象数组每个元素记录一次故障事件子字段类型含义timeNumber故障发生时间相对起飞秒数altitudeNumber故障时高度千米reasonString故障原因描述在源码中该子文档通过_id: false关闭了子文档 ObjectId 的自动生成见 models/launches.js避免数组内嵌对象产生多余的_id字段保持响应干净。details则是可空的自由文本任务说明默认null。三、关联引用字段UUID 与跨集合填充v5 Schema 中大量字段的类型标记为UUID。需要澄清的是这里的 UUID 在对外 API 响应中呈现为 24 位十六进制字符串如5e9e4501f509094ba4566f84其底层本质是MongoDB ObjectId——源码中全部对应为mongoose.ObjectId并通过ref声明指向目标集合见 models/launches.jsSchema 字段Mongoose 类型ref 目标集合含义rocketObjectIdRocket本次发射使用的火箭launchpadObjectIdLaunchpad发射工位crew[].crewObjectIdCrew乘组人员ships[]ObjectId[]Ship相关回收/支援船只capsules[]ObjectId[]Capsule使用的龙飞船等舱段payloads[]ObjectId[]Payload搭载的有效载荷cores[].coreObjectIdCore一级芯级cores[].landpadObjectIdLandpad着陆平台fairings.ships[]ObjectId[]Ship整流罩回收船这种 UUID 引用 populate 填充 的设计正是 查询与分页指南 的核心机制默认响应返回引用 ID但消费者可以在/v5/launches/query的options.populate中指定填充路径让 API 把 ID 原位替换为被引用文档的完整内容。例如填充payloads字段{ query: {}, options: { populate: [payloads] } }四、嵌套复合对象fairings、crew、cores 与 links4.1 fairings整流罩回收信息fairings: { reused: { type: Boolean, default: null }, recovery_attempt: { type: Boolean, default: null }, recovered: { type: Boolean, default: null }, ships: [UUID] }整流罩Fairings回收状态对象reused是否复用、recovery_attempt是否尝试回收、recovered是否回收成功三者默认均为nullships为参与回收任务的船只 UUID 数组。没有整流罩回收的任务中该字段整体为null见 GET all launches 示例 中fairings: null。4.2 crewv4 到 v5 的核心结构升级crew是 v5 版本相对 v4 最显著的破坏性变更。在 v4 Schema 中它是纯 UUID 数组crew: [UUID]而在 v5 中升级为对象数组为每位乘员携带职责角色信息crew: [ { crew: { type: UUID, default: null }, role: { type: String, default: null } } ]crew子对象中的crew字段是Crew集合的引用role则描述该乘员在此次任务中的角色如指令长、飞行工程师等。这一变更的官方说明记录在 v4 到 v5 变更说明 中。源码层面同样通过_id: false关闭了内嵌子文档 ID见 models/launches.js。值得注意的是数据同步任务 在回写Crew集合的launches数组时使用的是launch.crew.includes(crew.id)说明内部实现依然依赖引用 ID 进行匹配。4.3 cores芯级与回收状态明细cores: [ { core: { type: UUID, default: null }, flight: { type: Number, default: null }, gridfins: { type: Boolean, default: null }, legs: { type: Boolean, default: null }, reused: { type: Boolean, default: null }, landing_attempt: { type: Boolean, default: null }, landing_success: { type: Boolean, default: null }, landing_type: { type: String, default: null }, landpad: { type: UUID, default: null } } ]cores数组记录本次任务使用的每一枚一级芯级及其回收细节子字段含义core芯级引用Core集合flight该芯级第几次飞行gridfins是否安装栅格翼legs是否安装着陆腿reused芯级是否复用landing_attempt是否尝试回收着陆landing_success回收是否成功landing_type着陆方式真实数据中可见RTLS返场回收与ASDS海上平台回收landpad着陆平台引用Landpad集合CRS-20 任务的真实示例见 GET one launch 示例cores: [ { core: 5e9e28a7f359187afd3b2662, flight: 2, gridfins: true, legs: true, reused: true, landing_attempt: true, landing_success: true, landing_type: RTLS, landpad: 5e9e3032383ecb267a34e7c7 } ]4.4 links任务媒体链接集合links是媒体资源的聚合对象除flickr外其余字段默认均为null子字段类型内容patch.small/patch.largeString任务徽章Patch图片的小/大尺寸 URLreddit.campaign/reddit.launch/reddit.media/reddit.recoveryStringReddit 各专题讨论帖 URLflickr.small/flickr.originalString[]Flickr 图片 URL 数组小尺寸/原图presskitString官方新闻资料包 PDF URLwebcastString直播/回放视频 URLyoutube_idStringYouTube 视频 IDarticleString相关新闻文章 URLwikipediaString维基百科条目 URL真实示例CRS-20中flickr.original包含 5 张原图链接webcast与youtube_id指向同一段 YouTube 视频youtube_id是webcast中 URL 末尾的纯 ID 形态便于开发者直接嵌入播放器。五、auto_update数据自动维护标记auto_update: { type: Boolean, default: true }auto_update默认true标记该记录是否允许被后台同步任务自动更新。仓库中 jobs/launches.js 展示了这些自动化任务的实际运行方式任务会调用/launches/query拉取全部已发射记录然后反向更新capsules、cores、crew、landpads、launchpads、payloads、ships等集合中的launches引用数组并基于launch.rocket rocket.id与launch.success统计各火箭的success_rate_pct成功率。这些反向引用维护逻辑都建立在本文描述的 Schema 各关联字段之上。六、源码对照Mongoose 模型中的 Schema 落地文档中的 JSON Schema 与 models/launches.js 中的 Mongoose Schema 几乎一一对应除类型映射外还补充了文档未明确展示的工程化细节引用声明所有UUID字段实际为mongoose.ObjectId并带ref例如rocket: { type: mongoose.ObjectId, ref: Rocket }。校验器date_precision的enum与name的unique均由 Mongoose 原生校验支持。文本索引模型末尾为name和details两字段建立了文本索引launchSchema.index({ name: text, details: text })这使得 查询与分页指南 中演示的$text全文检索可以直接作用于发射任务集合。插件模型挂载了mongoosePaginate提供/query接口的分页能力对应 路由中的Launch.paginate()与idPlugin将_id同时暴露为对外友好的id字段。子文档去 IDfailures、crew、cores三个内嵌数组均使用_id: false。额外字段源码中还包含文档未列出的launch_library_id默认null用于对接外部发射资料库以及{ autoCreate: true }选项。七、基于 Schema 的实战查询示例理解了字段结构与类型约束后即可基于 查询与分页指南 构造高价值的查询。以下请求均POST至/v5/launches/query。7.1 按时间范围过滤date_utc 的 ISO 比较{ query: { date_utc: { $gte: 2017-06-22T00:00:00.000Z, $lte: 2017-06-25T00:00:00.000Z } } }7.2 全文检索依赖 name/details 文本索引{ query: { $text: { $search: crs } } }7.3 取下一次发射结合 upcoming 与排序{ query: { upcoming: true }, options: { limit: 1, sort: { flight_number: asc } } }7.4 复杂组合查询时间、逻辑或、枚举过滤{ 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: { sort: { flight_number: asc }, limit: 50 } }7.5 关联填充与选择性字段populate填充payloads并只取name字段{ options: { populate: [{ path: payloads, select: { name: 1 } }] } }分页响应结构固定为docs、totalDocs、limit、totalPages、page、hasPrevPage、hasNextPage等字段见 查询接口文档 的真实响应示例可直接用于构建前端分页控件。八、结语Schema 的写与读/v5/launches的完整数据流闭环如下后台定时任务通过 jobs/launches.js 写入与更新记录严格遵循 models/launches.js 的字段类型、枚举与唯一性约束外部开发者则通过 routes/launches/v5/index.js 暴露的GET /v5/launches、GET /v5/launches/:id、POST /v5/launches/query及四个便捷端点读取数据。掌握本文的 Schema 全貌等于同时拿到了写入端的字段约束清单与读取端的查询设计手册——无论是按时间过滤历史任务、追踪芯级回收状态还是通过 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 Landing Pad 数据模型详解v4 Schema 字段全解析与查询实战SpaceX API Landing Pad 数据模型详解v4 Schema 字段全解析与查询实战 Landing Pad着陆场是 SpaceX 火箭一级后端API设计DB-GPT AWEL 实战从零手写一个 Chat Data自然语言查数据库完整工作流DB GPT AWEL 实战从零手写一个 Chat Data自然语言查数据库完整工作流 DB GPT 的 AWELAI Workflow Express后端API设计深入解析 SpaceX-API v5 的过去发射记录接口GET /v5/launches/past 全字段解读与源码级实现分析深入解析 SpaceX API v5 的过去发射记录接口GET /v5/launches/past 全字段解读与源码级实现分析 本文基于 docs/launc后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考