SpaceX-API v4 Core 数据模型完全解析：字段语义、落地记录与查询实战

SpaceX-API v4 Core 数据模型完全解析字段语义、落地记录与查询实战【免费下载链接】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 开源仓库的 docs/cores/v4/schema.md 为骨架完整拆解 Falcon 9 一级助推器Core在 v4 接口中的数据模型包括每个字段的类型、约束、默认值与业务含义并结合 models/cores.js、routes/cores/v4/index.js 与 jobs/cores.js 等源码说明这些字段如何被定义、读写与自动化维护。读完本文你将能精确理解serial、status、reuse_count、rtls_attempts、asds_attempts等字段的取值逻辑并能基于/v4/cores与/v4/cores/query接口高效查询和聚合助推器数据。一、Core 数据模型总览docs/cores/v4/schema.md是 v4 接口中 Core 集合的字段定义文档原文以 JSON 形式给出完整 Schema。将其与仓库源码 models/cores.js 中基于 Mongoose 的实际定义对照二者完全一致。该 Schema 描述的是 SpaceX 猎鹰系列可重复使用的一级助推器即常说的芯级每个文档代表一枚实体核心例如 B1051、B1056。完整字段定义如下{ serial: { type: String, unique: true, required: true }, block: { type: Number, default: null }, status: { type: String, enum: [active, inactive, unknown, expended, lost, retired], required: true }, reuse_count: { type: Number, default: 0 }, rtls_attempts: { type: Number, default: 0 }, rtls_landings: { type: Number, default: 0 }, asds_attempts: { type: Number, default: 0 }, asds_landings: { type: Number, default: 0 }, last_update: { type: String, default: null }, launches: [ { type: UUID } ] }说明文档中的launches字段标注为UUID在源码中实际对应 Mongoose 的ObjectIdmongoose.ObjectId并带ref: Launch引用见 models/cores.js。在 v4 数据中跨集合引用统一以 24 位十六进制 ObjectId 字符串形式暴露这一点与 docs/queries.md 中关于 UUID 引用机制的说明一致。一个真实的 Core 文档示例all.md 与 one.md 中给出了 B1051 的实际返回数据可作为理解 Schema 的直观参考{ block: 5, reuse_count: 3, rtls_attempts: 1, rtls_landings: 1, asds_attempts: 3, asds_landings: 3, last_update: Landed on OCISLY as of Jan 29, 2020. , launches: [ 5eb87d2bffd86e000604b375, 5eb87d31ffd86e000604b379, 5eb87d3fffd86e000604b382, 5eb87d44ffd86e000604b386 ], serial: B1051, status: active, id: 5e9e28a6f35918c0803b265c }可见该核心已飞行 4 次launches有 4 条引用reuse_count为 3即复用过 3 次ASDS海上无人船尝试并成功 3 次RTLS陆上回收尝试并成功 1 次。二、字段逐个拆解类型、约束与业务含义serial核心序列号唯一标识类型String约束unique: true、required: trueserial是核心的型号序列号如B1051、B1056。它既被 Schema 强制唯一也是 API 使用方定位核心的最直观标识。jobs/cores.js中抓取 Reddit r/SpaceX Wiki 数据时正是通过cores.docs.find((core) core.serial row.coreSerial)用序列号匹配已有记录jobs/cores.js可见其在数据维护链路中的索引价值。block核心生产批次类型Number默认值nullblock表示核心所属的 Block 版本批次如 Block 5用于区分生产改进代际。由于不是每枚核心都能明确归类Schema 允许为null。示例数据中 B1051 与 B1056 均为block: 5。status核心当前状态枚举约束类型String枚举[active, inactive, unknown, expended, lost, retired]约束required: truestatus是枚举字段合法取值只有六种Mongoose 会在写入时校验非法值将导致验证失败取值含义active核心仍在役可继续执行发射任务inactive核心已停用例如状态信息过期或不再计划飞行unknown状态未知expended核心一次性使用后耗尽例如 Block 4 的消耗式飞行lost核心回收失败丢失如坠海未回收retired核心正式退役从jobs/cores.js的维护逻辑可以印证这些取值的实际使用脚本抓取 Wiki 中Active Cores表并将对应核心置为activeInactive表置为inactiveLost表中凡状态文本匹配expended的置为expended其余置为lostjobs/cores.js。reuse_count复用次数类型Number默认值0reuse_count表示该核心的复用次数。其计算规则可从 jobs/cores.js 中推断reuse_count core.launches.length - 1当launches.length 0时即总飞行次数减一——首次发射不算复用。一个全新核心默认值为 0。rtls_attempts/rtls_landings陆上回收统计类型Number默认值0rtls_attemptsRTLSReturn To Launch Site返回发射场进行陆上垂直着陆的尝试次数rtls_landingsRTLS 成功着陆次数。asds_attempts/asds_landings海上回收统计类型Number默认值0asds_attemptsASDSAutonomous Spaceport Drone Ship自主无人驳船即海上回收平台的尝试次数asds_landingsASDS 成功着陆次数。这两组字段区分了猎鹰九号两大回收方式。jobs/cores.js通过向/launches/query发送四次条件查询来精确统计分别统计landing_type: RTLS与landing_type: ASDS下landing_attempt: true的总数尝试次数以及再叠加landing_success: true的总数成功次数并将totalDocs写回对应字段jobs/cores.js。last_update状态更新说明类型String默认值nulllast_update是一段人类可读的文本说明记录核心最近一次状态更新的原因或事件。例如Landed on OCISLY as of Jan 29, 2020. 表示该核心于 2020 年 1 月 29 日在无人船 OCISLY 上着陆。它由数据维护脚本从 Reddit Wiki 抓取的表格单元格内容填充jobs/cores.js。launches关联发射记录类型Array元素类型为引用文档中写为UUID源码实现[{ type: mongoose.ObjectId, ref: Launch }]models/cores.jslaunches数组记录了该核心参与过的所有发射任务的 ObjectId。这些 id 指向 Launch 集合中的文档。使用/query接口时可通过populate选项将 id 替换为完整的发射文档详见后文。id文档主键id不在 Schema 定义中显式出现而是由mongoose-id插件自动生成coreSchema.plugin(idPlugin)见 models/cores.js以字符串形式暴露_id例如5e9e28a6f35918c0803b265c。查询单个核心时使用的:id参数即该值。三、Schema 在源码中的落地实现文档中的 JSON Schema 并非独立于代码的纸上蓝图它与 models/cores.js 中定义的 Mongoose Schema 严格一一对应。除了字段本身模型还包含三处值得关注的实现细节文本索引coreSchema.index({ serial: text, last_update: text })models/cores.js为serial与last_update创建全文索引使/query接口支持 MongoDB 的$text全文搜索。分页能力coreSchema.plugin(mongoosePaginate)models/cores.js注入paginate()方法/query路由正是调用该方法实现分页查询routes/cores/v4/index.js。自动建集{ autoCreate: true }使模型在运行时自动创建对应的 MongoDB 集合。四、基于 Schema 的查询实战了解了字段定义后结合 docs/cores/v4/query.md 与 docs/queries.md可以构建各种实用查询。/v4/cores/query为POST接口请求体为{ query: {}, options: {} }其中query接受任意合法的 MongoDB find() 条件options支持select、sort、offset、page、limit、pagination、populate等参数。示例 1查询所有已丢失的核心{ query: { status: lost }, options: {} }示例 2按复用次数排序取前 10{ query: {}, options: { sort: { reuse_count: desc }, limit: 10 } }示例 3全文搜索核心序列号或更新说明利用serial与last_update的文本索引见 models/cores.js{ query: { $text: { $search: B1051 } }, options: {} }示例 4populate关联发射记录launches数组存储的是引用 id可通过populate展开为完整发射文档机制说明见 docs/queries.md{ query: { serial: B1051 }, options: { populate: [ { path: launches, select: { name: 1, date_utc: 1, flight_number: 1 } } ] } }分页返回结构/query接口默认返回分页结构docs/queries.md/v4/cores/query的响应示例见 docs/cores/v4/query.md{ docs: [ ... ], totalDocs: 65, offset: 0, limit: 10, totalPages: 7, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: true, prevPage: null, nextPage: 2 }注意query接口的响应中字段顺序为docs、totalDocs、offset、limit、totalPages、page、pagingCounter、hasPrevPage、hasNextPage、prevPage、nextPage。当查询条件不合法时如枚举值非法、字段类型不匹配接口返回400 Bad Request响应体为 Mongoose 报错信息及修正建议。五、REST 端点与读写权限一览Schema 对应的核心数据通过 routes/cores/v4/index.js 暴露路由前缀为/(v4|latest)/cores即/v4/cores与/latest/cores均可访问方法路径鉴权说明GET/v4/cores无获取全部核心200 OKGET/v4/cores/:id无获取单个核心不存在时404 Not Founddocs/cores/v4/one.mdPOST/v4/cores/query无分页条件查询200 OK参数错误返回400POST/v4/cores是创建核心core:create权限PATCH/v4/cores/:id是更新核心core:update权限开启runValidators校验枚举与必填字段DELETE/v4/cores/:id是删除核心core:delete权限所有公开读接口GET、POST /query都挂载了cache(300)中间件routes/cores/v4/index.js即 300 秒 Redis 缓存生产环境下命中缓存时响应头会带spacex-api-cache: HIT缓存实现见 middleware/cache.js。写接口则通过authauthz(core:xxx)双重保护未授权返回403见 middleware/authz.js。六、数据从何而来Schema 字段的自动化维护从源码看Core 集合的数据主要由 jobs/cores.js 定时任务维护这也反向印证了 Schema 各字段的设计动机抓取状态数据从 Reddit r/SpaceX Wiki 的 cores 页面抓取 Active / Inactive / Lost 三张表格通过serial匹配已有记录用PATCH /cores/:id更新status与last_update字段jobs/cores.js统计回收数据向/launches/query发起四次条件查询分别统计 RTLS / ASDS 的尝试与成功次数写回rtls_attempts、rtls_landings、asds_attempts、asds_landings计算复用次数按launches.length - 1更新reuse_count。也就是说status、last_update以及四组回收统计字段并非人工手填而是由脚本依据发射历史与社区 Wiki 自动推导并回写。理解了这条维护链路就能更准确地解读每个字段的语义与可信度。结语docs/cores/v4/schema.md虽只有短短数十行 JSON却是理解整个 v4 Core 接口的钥匙。它以严格的字段约束unique、enum、required刻画了猎鹰助推器数据模型的骨架而仓库中的模型、路由与定时任务源码则完整呈现了这些字段从定义、校验到自动维护的全生命周期。结合本文的字段对照表与查询示例你便可以基于GET /v4/cores、GET /v4/cores/:id与POST /v4/cores/query三个端点构建属于自己的核心复用与回收分析应用。【免费下载链接】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），仅供参考