SpaceX-API Landing Pad 数据模型详解v4 Schema 字段全解析与查询实战【免费下载链接】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-APILanding Pad着陆场是 SpaceX 火箭一级助推器陆地回收与返回式着陆的关键基础设施本文以 SpaceX-API 仓库 docs/landpads/v4/schema.md 为核心逐字段剖析/v4/landpads端点的官方数据结构并结合仓库源码 models/landpads.js 与 routes/landpads/v4/index.js 验证字段约束、枚举值与数据关联最后给出基于真实响应示例的查询、过滤与分页实战方案。读完本文你将能准确构造 Landing Pad 读写请求、理解landing_attempts等字段的统计口径并复用该 Schema 组织自有太空数据服务。一、Landing Pad 在 SpaceX-API 中的定位在 SpaceX-API 的 v4 版本中Landing Pad 数据通过统一的版本化路由对外暴露路由前缀支持v4与latest双版本别名见 routes/landpads/v4/index.js 中的prefix: /(v4|latest)/landpads。所有GET与POST /query请求均经过 Redis 缓存根据 docs/README.md 中的缓存策略说明landpads 的标准缓存时长为 5 分钟与 capsules、cores、launchpads、crew、ships、payloads 同级而源码 routes/landpads/v4/index.js 中通过cache(300)中间件传入的 300 秒也正是该缓存时长。这意味着在连续查询同一批着陆场数据时命中缓存的响应速度会显著提升但也意味着新增数据最多需要 5 分钟才能对读请求可见。Landing Pad 数据对象与 Launch发射、Core芯级之间存在引用关系每个着陆场通过launches数组关联其承载过的发射任务反过来Launch 文档的cores[].landpad字段也指向该着陆场。这种双向关联是理解本 Schema 中launches字段类型设计的关键。二、官方 Schema 完整呈现以下 JSON 即 docs/landpads/v4/schema.md 中定义的官方字段约束{ name: { type: String, default: null }, full_name: { type: String, default: null }, status: { type: String, enum: [ active, inactive, unknown, retired, lost, under construction ], required: true }, type: { type: String, default: null }, locality: { type: String, default: null }, region: { type: String, default: null }, latitude: { type: Number, default: null }, longitude: { type: Number, default: null }, landing_attempts: { type: Number, default: 0 }, landing_successes: { type: Number, default: 0 }, wikipedia: { type: String, default: null }, details: { type: String, default: null }, launches: [ { type: UUID } ] }三、字段级深度解析将上述 Schema 与 models/landpads.js 中的 Mongoose 实现逐一对齐可以得到每个字段的完整语义3.1 标识与命名字段字段类型默认值说明nameStringnull简短代号如LZ-1、LZ-2、SLS等用于快速识别full_nameStringnull完整名称如Landing Zone 1着陆区 1typeStringnull着陆方式/场地类型。实际数据中常见值为RTLSReturn To Launch Site返回发射场陆地回收此外还存在其他回收形态如 ASDS 海上驳船由 ships 数据集管理见 docs/ships/v4/all.md其中name、full_name、details三个字段在源码 models/landpads.js 中被联合建成了text 文本索引const index { name: text, full_name: text, details: text, }; landpadSchema.index(index);这意味着可以通过 MongoDB 的$text操作符对这三类字段做全文搜索例如搜索包含 Florida 或 Cape Canaveral 字样的着陆场详情。3.2 状态枚举statusstatus是本 Schema 中唯一一个required: true必填且带枚举约束的字段取值空间由 models/landpads.js 严格限定为六种active— 当前可用/在役inactive— 当前停用但保留unknown— 状态未知retired— 已退役lost— 已丢失/不可用under construction— 建设中含扩建如 LZ-2 从无到有枚举约束保证了数据可枚举、可过滤、可建立一致的统计口径。任何不符合该枚举的写入请求都会被 routes/landpads/v4/index.js 中update路由使用的{ runValidators: true }选项拦截并返回400。3.3 地理位置字段字段类型说明localityString城市/区域级地名如Cape CanaveralregionString州/省级行政区如FloridalatitudeNumber纬度十进制度数北纬为正longitudeNumber经度十进制度数西经为负经纬度字段可配合地图可视化工具直接用于落点绘制例如 LZ-2 的坐标28.485833, -80.544444位于佛罗里达卡纳维拉尔角附近。3.4 回收统计字段字段类型默认值语义landing_attemptsNumber0该着陆场累计的着陆尝试次数landing_successesNumber0该着陆场累计的成功着陆次数这两个字段不是由用户手工维护的而是由定时作业自动统计生成。在 jobs/landpads.js 中作业对每个 landpad 分别发起两次launches/query查询尝试次数统计upcoming: false, success: true且cores中landpad等于当前着陆场 ID、landing_attempt: true的已发射任务成功次数在上述条件基础上追加landing_success: true。随后通过PATCH /landpads/:id将landing_attempts与landing_successes写回。该作业在 jobs/worker.js 中以*/10 * * * *的 Cron 表达式每 10 分钟执行一次。因此调用方可以放心地把这两个字段当作权威统计值使用而无需自行对 Launch 数据做聚合。3.5 描述与资料字段字段类型说明wikipediaString维基百科词条 URL用于进一步查阅场地历史detailsString场地详细描述通常包含历史沿革例如 LZ-1 曾于 2015 年 12 月完成 Falcon 9 首次历史性陆地回收其原址 LC-13 曾用于发射早期 Atlas 导弹/火箭后扩建出 LZ-2 用于 Falcon Heavy 侧助推器 RTLS 任务3.6 关联发射字段launcheslaunches: [ { type: UUID } ]在 API 文档层launches是存放 Launch 文档 IDUUID 形态的 24 位十六进制字符串的数组。在存储层models/landpads.js 将其实现为launches: [{ type: mongoose.ObjectId, ref: Launch, }]即一个mongoose.ObjectId数组外键指向Launch集合。这意味着你可以把launches里的每个 ID 用于GET /v4/launches/:id单独取回发射详情也可以借助查询接口的populate选项一次性把这些 ID 展开为完整的 Launch 文档详见本文第四节。3.7 Schema 文档未列出、但源码中存在的字段从源码结构看models/landpads.js 还定义了images字段images.large为字符串数组用于存放着陆场的大图 URLdocs/landpads/v4/schema.md 未将其列入属于官方文档对字段集的轻微精简。在实际GET响应中该字段是否返回以线上 API 返回体为准——本文第五节给出的示例响应中未包含该字段。四、关联字段的填充populate实战由于launches数组存放的是 Launch 文档 ID想要一次拿全着陆场与对应发射的完整信息可以利用 docs/queries.md 中描述的populate机制。向POST /v4/landpads/query发送{ query: {}, options: { populate: [ launches ] } }即可把launches数组中的每个 UUID 替换为对应的完整 Launch 文档。更精细的做法是只提取感兴趣的字段{ query: {}, options: { populate: [ { path: launches, select: { name: 1, flight_number: 1, date_utc: 1 } } ] } }此时每个发射对象将只返回name、flight_number、date_utc与id显著压缩响应体积。populate还支持嵌套填充例如在发射文档内部继续展开rocket可满足多层联查场景。五、基于 Schema 的 API 调用方式围绕 docs/landpads/v4/schema.md 定义的字段结构/v4/landpads提供了三类读接口均无需鉴权完整路由实现见 routes/landpads/v4/index.js5.1 获取全部着陆场GET /v4/landpads返回所有 Landing Pad 文档组成的数组每个元素遵循本 Schema。参考 docs/landpads/v4/all.md 中的真实响应示例[ { name: LZ-2, full_name: Landing Zone 2, status: active, type: RTLS, locality: Cape Canaveral, region: Florida, latitude: 28.485833, longitude: -80.544444, landing_attempts: 3, landing_successes: 3, wikipedia: https://en.wikipedia.org/wiki/Landing_Zones_1_and_2, details: SpaceXs first east coast landing pad is Landing Zone 1, ..., launches: [ 5eb87d13ffd86e000604b360, 5eb87d2dffd86e000604b376, 5eb87d35ffd86e000604b37a ], id: 5e9e3032383ecb90a834e7c8 } ]注意该示例中字段为id而非_id这是 models/landpads.js 中mongoose-id插件的效果——它在序列化时把 MongoDB 的_id映射为对外友好的id字段。5.2 获取单个着陆场GET /v4/landpads/:idURL 参数id为 Landing Pad 的 24 位十六进制 ID如5e9e3032383ecb90a834e7c8。响应体结构与上文示例完全一致若 ID 不存在返回404 NOT FOUND响应体为Not Found见 docs/landpads/v4/one.md。对应路由实现在 routes/landpads/v4/index.jsrouter.get(/:id, cache(300), async (ctx) { const result await Landpad.findById(ctx.params.id); if (!result) { ctx.throw(404); } ctx.status 200; ctx.body result; });5.3 自定义查询POST /v4/landpads/query请求体为{ query: {}, options: {} }其中query接受任何合法的 MongoDBfind()查询options支持select、sort、offset、page、limit、pagination、populate等分页与输出控制参数详见 docs/queries.md。路由在 routes/landpads/v4/index.js 中通过Landpad.paginate(query, options)执行mongoose-paginate-v2插件为 models/landpads.js 所挂载。响应为分页包装结构参考 docs/landpads/v4/query.md 的示例totalDocs: 7表明当前数据集共有 7 个着陆场记录{ docs: [ { name: LZ-1, full_name: Landing Zone 1, status: active, type: RTLS, locality: Cape Canaveral, region: Florida, latitude: 28.485833, longitude: -80.544444, landing_attempts: 15, landing_successes: 14, wikipedia: https://en.wikipedia.org/wiki/Landing_Zones_1_and_2, details: ..., launches: [ 5eb87cefffd86e000604b342, 5eb87cf9ffd86e000604b349, 5eb87cfefffd86e000604b34d ], id: 5e9e3032383ecb267a34e7c7 } ], totalDocs: 7, offset: 0, limit: 10, totalPages: 1, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: false, prevPage: null, nextPage: null }查询请求若包含非法字段或非法查询语法接口返回400 Bad Request响应体为 Mongoose 报错信息并附带修正建议。六、常用查询场景示例结合本 Schema 的字段设计以下查询在实战中最常用1. 只看当前在役的陆地回收场{ query: { status: active, type: RTLS }, options: { sort: { name: asc } } }2. 按区域过滤并按回收成功率排序可先用 populate 展开发射以做关联分析{ query: { region: Florida }, options: { sort: { landing_successes: desc }, limit: 5 } }3. 全文搜索场地描述利用 text 索引{ query: { $text: { $search: Cape Canaveral } } }4. 只返回坐标与统计字段用于地图绘制压缩带宽{ query: {}, options: { select: { name: 1, latitude: 1, longitude: 1, landing_attempts: 1, landing_successes: 1 } } }5. 关闭分页一次取回全部记录适用于totalDocs数量小的集合{ query: {}, options: { pagination: false } }其中第 5 种方式正是 jobs/landpads.js 内部抓取全量着陆场数据的做法可作为大数据集之外小规模同步场景的参考范本。七、写入与维护Schema 约束如何生效虽然对外公开的读接口无需鉴权但所有写操作创建、更新、删除都必须通过spacex-key请求头携带 API Key 完成鉴权并经过 middleware/authz.js 的角色权限校验landpad:create/landpad:update/landpad:delete。相关路由完整实现了 CRUD见 routes/landpads/v4/index.jsPOST /v4/landpads— 按请求体创建新文档成功后返回201PATCH /v4/landpads/:id— 部分更新指定文档runValidators: true会触发status枚举等 Schema 校验非法值返回400DELETE /v4/landpads/:id— 删除指定文档。写请求若违反 Schema 约束如status传入枚举之外的字符串、缺少必填的status、latitude传入非数值Mongoose 校验器会拒绝写入并抛出错误由路由捕获后以400 Bad Request返回错误消息。这一机制保证了线上数据的字段类型与枚举一致性。八、总结Landing Pad 的 v4 Schema 是一份精简而完整的领域数据模型status的六值枚举提供了状态机式的可枚举语义latitude/longitude支撑地理可视化landing_attempts/landing_successes由 jobs/landpads.js 每 10 分钟自动重算launches数组则通过外键与 populate 机制打通了与 Launch 数据的关联分析。无论是消费GET /v4/landpads、GET /v4/landpads/:id做展示还是利用POST /v4/landpads/query做过滤、排序、全文检索与分页本文所整理的字段语义与查询示例均可直接复制使用。深入阅读 models/landpads.js 与 routes/landpads/v4/index.js 源码还能进一步掌握文本索引、外键引用、分页插件与权限控制等实现细节为自建同类数据服务提供参考。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考