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 的ObjectId（mongoose.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: true

serial是核心的型号序列号，如B1051、B1056。它既被 Schema 强制唯一，也是 API 使用方定位核心的最直观标识。jobs/cores.js中抓取 Reddit r/SpaceX Wiki 数据时，正是通过cores.docs.find((core) => core.serial === row.coreSerial)用序列号匹配已有记录（jobs/cores.js），可见其在数据维护链路中的索引价值。

block：核心生产批次

• 类型：Number
• 默认值：null

block表示核心所属的 Block 版本批次（如 Block 5），用于区分生产改进代际。由于不是每枚核心都能明确归类，Schema 允许为null。示例数据中 B1051 与 B1056 均为block: 5。

status：核心当前状态（枚举约束）

• 类型：String
• 枚举：["active", "inactive", "unknown", "expended", "lost", "retired"]
• 约束：required: true

status是枚举字段，合法取值只有六种，Mongoose 会在写入时校验，非法值将导致验证失败：

取值	含义
active	核心仍在役，可继续执行发射任务
inactive	核心已停用（例如状态信息过期或不再计划飞行）
unknown	状态未知
expended	核心一次性使用后耗尽（例如 Block 4 的消耗式飞行）
lost	核心回收失败丢失（如坠海未回收）
retired	核心正式退役

从jobs/cores.js的维护逻辑可以印证这些取值的实际使用：脚本抓取 Wiki 中"Active Cores"表并将对应核心置为active，"Inactive"表置为inactive，"Lost"表中凡状态文本匹配expended的置为expended，其余置为lost（jobs/cores.js）。

reuse_count：复用次数

• 类型：Number
• 默认值：0

reuse_count表示该核心的复用次数。其计算规则可从 jobs/cores.js 中推断：reuse_count = core.launches.length - 1（当launches.length > 0时），即"总飞行次数减一"——首次发射不算复用。一个全新核心默认值为 0。

rtls_attempts/rtls_landings：陆上回收统计

• 类型：Number

• 默认值：0

• rtls_attempts：RTLS（Return To Launch Site，返回发射场进行陆上垂直着陆）的尝试次数；

• rtls_landings：RTLS 成功着陆次数。

asds_attempts/asds_landings：海上回收统计

• 类型：Number

• 默认值：0

• asds_attempts：ASDS（Autonomous Spaceport Drone Ship，自主无人驳船，即海上回收平台）的尝试次数；

• asds_landings：ASDS 成功着陆次数。

这两组字段区分了猎鹰九号两大回收方式。jobs/cores.js通过向/launches/query发送四次条件查询来精确统计：分别统计landing_type: 'RTLS'与landing_type: 'ASDS'下landing_attempt: true的总数（尝试次数）以及再叠加landing_success: true的总数（成功次数），并将totalDocs写回对应字段（jobs/cores.js）。

last_update：状态更新说明

• 类型：String
• 默认值：null

last_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.js）

launches数组记录了该核心参与过的所有发射任务的 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 严格一一对应。除了字段本身，模型还包含三处值得关注的实现细节：

1. 文本索引：coreSchema.index({ serial: 'text', last_update: 'text' })（models/cores.js）为serial与last_update创建全文索引，使/query接口支持 MongoDB 的$text全文搜索。
2. 分页能力：coreSchema.plugin(mongoosePaginate)（models/cores.js）注入paginate()方法，/query路由正是调用该方法实现分页查询（routes/cores/v4/index.js）。
3. 自动建集：{ 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": {} }

示例 4：populate关联发射记录

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 OK
GET	/v4/cores/:id	无	获取单个核心，不存在时404 Not Found（docs/cores/v4/one.md）
POST	/v4/cores/query	无	分页条件查询，200 OK，参数错误返回400
POST	/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）。写接口则通过auth+authz('core:xxx')双重保护，未授权返回403（见 middleware/authz.js）。

六、数据从何而来：Schema 字段的自动化维护

从源码看，Core 集合的数据主要由 jobs/cores.js 定时任务维护，这也反向印证了 Schema 各字段的设计动机：

1. 抓取状态数据：从 Reddit r/SpaceX Wiki 的 cores 页面抓取 Active / Inactive / Lost 三张表格，通过serial匹配已有记录，用PATCH /cores/:id更新status与last_update字段（jobs/cores.js）；
2. 统计回收数据：向/launches/query发起四次条件查询，分别统计 RTLS / ASDS 的尝试与成功次数，写回rtls_attempts、rtls_landings、asds_attempts、asds_landings；
3. 计算复用次数：按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