后端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 开源项目Open Source REST API for SpaceX launch, rocket, core, capsule, starlink, launchpad 与 landing pad 数据中的POST /v4/cores/query接口展开讲解如何通过请求体内的query与options字段组合 MongoDB 查询条件、排序、分页与 populate 关联填充。读完本文你将掌握 cores 数据集的完整查询姿势、分页响应结构解析、字段选择与关联展开技巧并能从仓库源码层面理解该接口的底层实现原理。接口概览/v4/cores/query是 SpaceX-API v4 中针对核心级回收助推器Core数据集合的通用查询端点与传统的GET /v4/cores全量拉取和GET /v4/cores/:id按 ID 获取单个不同它允许你像操作 MongoDB 一样构造任意过滤条件并自带分页能力是批量获取与条件筛选的核心入口。项目说明MethodPOSTURLhttps://api.spacexdata.com/v4/cores/queryAuth requiredFalse无需鉴权请求头Content-Type: application/json请求体{ query: {}, options: {} }请求体结构query 与 options 双字段默认请求体非常简单两个字段均可为空对象{ query: {}, options: {} }query接受任何合法的 MongoDBfind()查询语句支持$gte、$lte、$in、$or、$elemMatch、$text等全部 MongoDB 查询运算符options接受 mongoose-paginate-v2 分页插件的全部选项用于控制返回字段、排序、分页与关联填充。在源码层面路由处理器直接将这两个字段透传给 Mongoose 的paginate方法见 routes/cores/v4/index.js#L31-L40router.post(/query, cache(300), async (ctx) { const { query {}, options {} } ctx.request.body; try { const result await Core.paginate(query, options); ctx.status 200; ctx.body result; } catch (error) { ctx.throw(400, error.message); } });从源码可见两点关键事实其一请求体缺省字段会被安全地默认成空对象不会因缺少字段而报错其二所有分页与查询逻辑由 models/cores.js 中挂载的mongoose-paginate-v2插件完成。Core 数据模型查询的前提认知要写出有效的查询条件先要了解 Core 文档的字段结构。仓库中的实际 Schema 定义见 models/cores.js与文档 docs/cores/v4/schema.md 保持一致字段类型约束与默认值说明serialStringunique,required芯级序列号如B1056blockNumberdefault: null芯级生产批次Block 版本statusStringenum: [active, inactive, unknown, expended, lost, retired],required芯级当前状态reuse_countNumberdefault: 0复用次数rtls_attemptsNumberdefault: 0返场回收RTLS尝试次数rtls_landingsNumberdefault: 0返场回收成功次数asds_attemptsNumberdefault: 0海上平台ASDS尝试次数asds_landingsNumberdefault: 0海上平台成功次数last_updateStringdefault: null最新状态更新说明文本launchesUUID[]关联Launch集合该芯级参与的发射记录 ID 数组值得注意的实现细节模型源码为serial和last_update两个字段建立了全文索引text indexconst index { serial: text, last_update: text, }; coreSchema.index(index);这意味着你可以直接使用$text运算符对这两个字段做全文检索详见后文示例这正是官方查询指南中所有字符串字段都被索引说法的落地实现。options 分页与输出选项详解options字段控制返回结果的形状以下参数均直接来自 docs/queries.md 官方查询指南并由 mongoose-paginate-v2 原生支持参数类型说明selectObject | String指定返回哪些字段默认返回全部字段sortObject | String排序规则如{ serial: asc }offsetNumber跳过位置与page二选一pageNumber页码从 1 开始limitNumber每页条数paginationBoolean设为false时不分页、直接返回全部文档默认truepopulateArray | Object | String需要关联填充的路径将 UUID 替换为关联文档例如跳过前 5 条、每页取 10 条、按序列号降序排列并按launches填充关联发射文档{ query: {}, options: { offset: 5, limit: 10, sort: { serial: desc }, populate: [launches] } }关闭分页pagination: false当只需要全量结果、不关心分页元数据时设置pagination: false即可绕过 limit 限制返回所有文档。这一用法并非空谈——仓库内部的 jobs/cores.js 数据同步任务在拉取全部芯级时就采用了这种方式const cores await got.post(${API}/cores/query, { json: { options: { pagination: false, }, }, resolveBodyOnly: true, responseType: json, });这也说明该选项在真实生产场景中是官方自己就在使用的标准操作。成功响应分页结构逐字段解析200 OK响应体是一个标准的 mongoose-paginate-v2 分页结果docs数组携带 Core 文档其余字段描述分页状态。官方文档示例已截断部分数组元素{ docs: [ { block: 5, reuse_count: 3, rtls_attempts: 1, rtls_landings: 1, asds_attempts: 2, asds_landings: 2, last_update: Missed the droneship and made successful water landing; apparently scuttled at sea afterward. , launches: [ 5eb87d2effd86e000604b377, 5eb87d36ffd86e000604b37b, 5eb87d3bfffd86e000604b37f, 5eb87d41ffd86e000604b383 ], serial: B1056, status: lost, id: 5e9e28a7f3591809313b2660 } ], totalDocs: 65, offset: 0, limit: 10, totalPages: 7, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: true, prevPage: null, nextPage: 2 }各分页元数据字段含义如下字段含义docs当前页的文档数组totalDocs符合查询条件的文档总数offset本次查询跳过的条数limit每页条数totalPages总页数page当前页码pagingCounter当前页首条文档的全局序号从 1 开始hasPrevPage是否有上一页hasNextPage是否有下一页prevPage上一页页码无则为nullnextPage下一页页码无则为null以该示例为例65 个文档按每页 10 条分成 7 页当前在第 1 页因此hasPrevPage为false、nextPage为2。客户端可以据此实现上一页/下一页式的前后端分页导航也可以直接用totalDocs做总数统计。查询实战query 条件组合示例以下示例均来自 docs/queries.md 官方指南并针对 Core 数据集的字段做了适配说明。按状态筛选芯级最常见的场景是只取某种状态的芯级{ query: { status: active }, options: { limit: 10 } }由于status字段的枚举值固定为active、inactive、unknown、expended、lost、retired传入合法枚举值即可精确匹配。按序列号精确匹配serial在 Schema 中带有unique约束可直接等值查询{ query: { serial: B1056 }, options: {} }日期/数值区间查询对block批次等数值字段使用$gte、$lte运算符{ query: { block: { $gte: 5 } } }全文检索$text由于serial与last_update建立了文本索引可以直接对状态描述做全文搜索例如查找描述中包含 landing 的芯级{ query: { $text: { $search: landing } } }这是 Core 数据集的特色能力——在 models/cores.js 中通过coreSchema.index({ serial: text, last_update: text })显式声明因而无需额外配置即可使用。组合复杂查询将多个条件与逻辑运算符自由组合例如筛选「block 批次大于等于 5」且「状态不是 active」的芯级{ query: { block: { $gte: 5 }, status: { $ne: active } }, options: { sort: { block: desc }, limit: 20 } }统计某条件下文档总数将options中的limit设为1并读取响应的totalDocs字段即可用最小数据量获得符合条件的文档总数{ query: { status: lost }, options: { limit: 1 } }关联填充将 launches 的 UUID 展开为发射文档Core 文档中的launches字段存储的是指向Launch集合的 UUID 数组。默认情况下接口返回的是原始 ID通过options.populate可以将其替换为完整的发射文档这在构建发射历史、芯级履历页面时非常实用。基本用法——直接填充{ query: {}, options: { populate: [launches] } }返回结果中每个 UUID 会被替换为对应的发射对象{ launches: [ { flight_number: 50, name: CRS-10, date_utc: 2017-02-19T14:39:00.000Z, id: 5eb87d2effd86e000604b377 } ] }仅选择填充文档的特定字段更省流量{ query: {}, options: { populate: [ { path: launches, select: { name: 1 } } ] } }该用法在官方指南 docs/queries.md 中有完整演示原示例以 payloads 演示populate 机制对 launches 同样适用。从实现上看launches在 models/cores.js 中声明为type: mongoose.ObjectId, ref: Launch正是这个ref让 Mongoose 知道填充时该去哪个集合查找。需要提醒populate属于服务端关联查询填充的文档同样计入查询开销若只是展示 ID 列表建议省略 populate 以获得更好的响应性能。错误响应状态码触发条件响应内容400 Bad Requestquery或options语法非法如查询了不存在的字段、运算符拼写错误、类型不匹配Mongoose 错误信息并附带修正建议404 Not Found使用GET /v4/cores/:id查询不存在的 ID查询端点本身不会触发Not Found400 错误在源码中的对应逻辑位于 routes/cores/v4/index.js#L37-L39当Core.paginate(query, options)抛出异常时中间件将异常信息原样透出。因此调试时应仔细阅读响应体中的 Mongoose 提示通常它会明确指出是字段名不存在、运算符不支持还是类型不匹配。相关端点与配套资源Core 查询端点与以下资源共同构成完整的 cores 使用体系获取全部芯级GET /v4/cores适合小批量全量拉取获取单个芯级GET /v4/cores/:id按 ID 获取单条记录Core 数据 Schema所有可查询字段的类型与约束查询与分页通用指南docs/queries.md所有/query端点共用的 MongoDB 查询、分页与 populate 教程包含更多高级运算符示例发射查询端点POST /v4/launches/query当需要通过发射记录反向关联芯级时的入口。源码级实现原理小结最后把整条链路的实现证据串起来路由层routes/cores/v4/index.js#L31-L40 中router.post(/query, cache(300), ...)接收{ query, options }并调用Core.paginate()同时被cache(300)中间件包裹——该中间件见 middleware/cache.js在生产环境下以 BLAKE3 哈希请求方法、URL 与 body 作为 Redis key对相同查询做 300 秒 TTL 缓存命中时返回spacex-api-cache: HIT响应头模型层models/cores.js 中 Schema 声明了字段约束、serial/last_update文本索引、launches到Launch的引用并挂载了mongoose-paginate-v2与mongoose-id插件前者提供分页能力后者将_id暴露为id数据消费层jobs/cores.js 本身就以options: { pagination: false }调用本接口拉取全量芯级并用launches/query的$elemMatch统计 RTLS/ASDS 数据后回写PATCH /v4/cores/:id——这为外部开发者示范了「查询 → 统计 → 回写」的完整自动化用法。综上POST /v4/cores/query是一个覆盖「过滤 排序 分页 关联填充 全文检索」全能力的通用查询端点。只要遵循 MongoDB 查询语法与本文列出的 options 参数即可轻松构建从简单筛选到复杂多维统计的各种业务查询。赞分享后端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点击查看免费下载相关推荐Ruffle 测试工程实践EmptyFunctionName 验收测试的 source.tar.xz 归档机制与 Windows 大小写敏感文件系统问题Ruffle 测试工程实践EmptyFunctionName 验收测试的 source.tar.xz 归档机制与 Windows 大小写敏感文件系统问题 导读后端API设计Hermes WebUI Workspace Git 控制默认只读、可安全开启的浏览器端 Git 操作设计Hermes WebUI Workspace Git 控制默认只读、可安全开启的浏览器端 Git 操作设计 Workspace Git 控制Workspac后端API设计SpaceX-API Capsules Query 接口实战指南基于 Mongo 查询语法与分页机制的数据检索SpaceX API Capsules Query 接口实战指南基于 Mongo 查询语法与分页机制的数据检索 导读 本文围绕 SpaceX API 开源项目后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SpaceX-API v4 Cores Query 接口实战：MongoDB 查询与分页参数完全指南
后端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 开源项目Open Source REST API for SpaceX launch, rocket, core, capsule, starlink, launchpad 与 landing pad 数据中的POST /v4/cores/query接口展开讲解如何通过请求体内的query与options字段组合 MongoDB 查询条件、排序、分页与 populate 关联填充。读完本文你将掌握 cores 数据集的完整查询姿势、分页响应结构解析、字段选择与关联展开技巧并能从仓库源码层面理解该接口的底层实现原理。接口概览/v4/cores/query是 SpaceX-API v4 中针对核心级回收助推器Core数据集合的通用查询端点与传统的GET /v4/cores全量拉取和GET /v4/cores/:id按 ID 获取单个不同它允许你像操作 MongoDB 一样构造任意过滤条件并自带分页能力是批量获取与条件筛选的核心入口。项目说明MethodPOSTURLhttps://api.spacexdata.com/v4/cores/queryAuth requiredFalse无需鉴权请求头Content-Type: application/json请求体{ query: {}, options: {} }请求体结构query 与 options 双字段默认请求体非常简单两个字段均可为空对象{ query: {}, options: {} }query接受任何合法的 MongoDBfind()查询语句支持$gte、$lte、$in、$or、$elemMatch、$text等全部 MongoDB 查询运算符options接受 mongoose-paginate-v2 分页插件的全部选项用于控制返回字段、排序、分页与关联填充。在源码层面路由处理器直接将这两个字段透传给 Mongoose 的paginate方法见 routes/cores/v4/index.js#L31-L40router.post(/query, cache(300), async (ctx) { const { query {}, options {} } ctx.request.body; try { const result await Core.paginate(query, options); ctx.status 200; ctx.body result; } catch (error) { ctx.throw(400, error.message); } });从源码可见两点关键事实其一请求体缺省字段会被安全地默认成空对象不会因缺少字段而报错其二所有分页与查询逻辑由 models/cores.js 中挂载的mongoose-paginate-v2插件完成。Core 数据模型查询的前提认知要写出有效的查询条件先要了解 Core 文档的字段结构。仓库中的实际 Schema 定义见 models/cores.js与文档 docs/cores/v4/schema.md 保持一致字段类型约束与默认值说明serialStringunique,required芯级序列号如B1056blockNumberdefault: null芯级生产批次Block 版本statusStringenum: [active, inactive, unknown, expended, lost, retired],required芯级当前状态reuse_countNumberdefault: 0复用次数rtls_attemptsNumberdefault: 0返场回收RTLS尝试次数rtls_landingsNumberdefault: 0返场回收成功次数asds_attemptsNumberdefault: 0海上平台ASDS尝试次数asds_landingsNumberdefault: 0海上平台成功次数last_updateStringdefault: null最新状态更新说明文本launchesUUID[]关联Launch集合该芯级参与的发射记录 ID 数组值得注意的实现细节模型源码为serial和last_update两个字段建立了全文索引text indexconst index { serial: text, last_update: text, }; coreSchema.index(index);这意味着你可以直接使用$text运算符对这两个字段做全文检索详见后文示例这正是官方查询指南中所有字符串字段都被索引说法的落地实现。options 分页与输出选项详解options字段控制返回结果的形状以下参数均直接来自 docs/queries.md 官方查询指南并由 mongoose-paginate-v2 原生支持参数类型说明selectObject | String指定返回哪些字段默认返回全部字段sortObject | String排序规则如{ serial: asc }offsetNumber跳过位置与page二选一pageNumber页码从 1 开始limitNumber每页条数paginationBoolean设为false时不分页、直接返回全部文档默认truepopulateArray | Object | String需要关联填充的路径将 UUID 替换为关联文档例如跳过前 5 条、每页取 10 条、按序列号降序排列并按launches填充关联发射文档{ query: {}, options: { offset: 5, limit: 10, sort: { serial: desc }, populate: [launches] } }关闭分页pagination: false当只需要全量结果、不关心分页元数据时设置pagination: false即可绕过 limit 限制返回所有文档。这一用法并非空谈——仓库内部的 jobs/cores.js 数据同步任务在拉取全部芯级时就采用了这种方式const cores await got.post(${API}/cores/query, { json: { options: { pagination: false, }, }, resolveBodyOnly: true, responseType: json, });这也说明该选项在真实生产场景中是官方自己就在使用的标准操作。成功响应分页结构逐字段解析200 OK响应体是一个标准的 mongoose-paginate-v2 分页结果docs数组携带 Core 文档其余字段描述分页状态。官方文档示例已截断部分数组元素{ docs: [ { block: 5, reuse_count: 3, rtls_attempts: 1, rtls_landings: 1, asds_attempts: 2, asds_landings: 2, last_update: Missed the droneship and made successful water landing; apparently scuttled at sea afterward. , launches: [ 5eb87d2effd86e000604b377, 5eb87d36ffd86e000604b37b, 5eb87d3bfffd86e000604b37f, 5eb87d41ffd86e000604b383 ], serial: B1056, status: lost, id: 5e9e28a7f3591809313b2660 } ], totalDocs: 65, offset: 0, limit: 10, totalPages: 7, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: true, prevPage: null, nextPage: 2 }各分页元数据字段含义如下字段含义docs当前页的文档数组totalDocs符合查询条件的文档总数offset本次查询跳过的条数limit每页条数totalPages总页数page当前页码pagingCounter当前页首条文档的全局序号从 1 开始hasPrevPage是否有上一页hasNextPage是否有下一页prevPage上一页页码无则为nullnextPage下一页页码无则为null以该示例为例65 个文档按每页 10 条分成 7 页当前在第 1 页因此hasPrevPage为false、nextPage为2。客户端可以据此实现上一页/下一页式的前后端分页导航也可以直接用totalDocs做总数统计。查询实战query 条件组合示例以下示例均来自 docs/queries.md 官方指南并针对 Core 数据集的字段做了适配说明。按状态筛选芯级最常见的场景是只取某种状态的芯级{ query: { status: active }, options: { limit: 10 } }由于status字段的枚举值固定为active、inactive、unknown、expended、lost、retired传入合法枚举值即可精确匹配。按序列号精确匹配serial在 Schema 中带有unique约束可直接等值查询{ query: { serial: B1056 }, options: {} }日期/数值区间查询对block批次等数值字段使用$gte、$lte运算符{ query: { block: { $gte: 5 } } }全文检索$text由于serial与last_update建立了文本索引可以直接对状态描述做全文搜索例如查找描述中包含 landing 的芯级{ query: { $text: { $search: landing } } }这是 Core 数据集的特色能力——在 models/cores.js 中通过coreSchema.index({ serial: text, last_update: text })显式声明因而无需额外配置即可使用。组合复杂查询将多个条件与逻辑运算符自由组合例如筛选「block 批次大于等于 5」且「状态不是 active」的芯级{ query: { block: { $gte: 5 }, status: { $ne: active } }, options: { sort: { block: desc }, limit: 20 } }统计某条件下文档总数将options中的limit设为1并读取响应的totalDocs字段即可用最小数据量获得符合条件的文档总数{ query: { status: lost }, options: { limit: 1 } }关联填充将 launches 的 UUID 展开为发射文档Core 文档中的launches字段存储的是指向Launch集合的 UUID 数组。默认情况下接口返回的是原始 ID通过options.populate可以将其替换为完整的发射文档这在构建发射历史、芯级履历页面时非常实用。基本用法——直接填充{ query: {}, options: { populate: [launches] } }返回结果中每个 UUID 会被替换为对应的发射对象{ launches: [ { flight_number: 50, name: CRS-10, date_utc: 2017-02-19T14:39:00.000Z, id: 5eb87d2effd86e000604b377 } ] }仅选择填充文档的特定字段更省流量{ query: {}, options: { populate: [ { path: launches, select: { name: 1 } } ] } }该用法在官方指南 docs/queries.md 中有完整演示原示例以 payloads 演示populate 机制对 launches 同样适用。从实现上看launches在 models/cores.js 中声明为type: mongoose.ObjectId, ref: Launch正是这个ref让 Mongoose 知道填充时该去哪个集合查找。需要提醒populate属于服务端关联查询填充的文档同样计入查询开销若只是展示 ID 列表建议省略 populate 以获得更好的响应性能。错误响应状态码触发条件响应内容400 Bad Requestquery或options语法非法如查询了不存在的字段、运算符拼写错误、类型不匹配Mongoose 错误信息并附带修正建议404 Not Found使用GET /v4/cores/:id查询不存在的 ID查询端点本身不会触发Not Found400 错误在源码中的对应逻辑位于 routes/cores/v4/index.js#L37-L39当Core.paginate(query, options)抛出异常时中间件将异常信息原样透出。因此调试时应仔细阅读响应体中的 Mongoose 提示通常它会明确指出是字段名不存在、运算符不支持还是类型不匹配。相关端点与配套资源Core 查询端点与以下资源共同构成完整的 cores 使用体系获取全部芯级GET /v4/cores适合小批量全量拉取获取单个芯级GET /v4/cores/:id按 ID 获取单条记录Core 数据 Schema所有可查询字段的类型与约束查询与分页通用指南docs/queries.md所有/query端点共用的 MongoDB 查询、分页与 populate 教程包含更多高级运算符示例发射查询端点POST /v4/launches/query当需要通过发射记录反向关联芯级时的入口。源码级实现原理小结最后把整条链路的实现证据串起来路由层routes/cores/v4/index.js#L31-L40 中router.post(/query, cache(300), ...)接收{ query, options }并调用Core.paginate()同时被cache(300)中间件包裹——该中间件见 middleware/cache.js在生产环境下以 BLAKE3 哈希请求方法、URL 与 body 作为 Redis key对相同查询做 300 秒 TTL 缓存命中时返回spacex-api-cache: HIT响应头模型层models/cores.js 中 Schema 声明了字段约束、serial/last_update文本索引、launches到Launch的引用并挂载了mongoose-paginate-v2与mongoose-id插件前者提供分页能力后者将_id暴露为id数据消费层jobs/cores.js 本身就以options: { pagination: false }调用本接口拉取全量芯级并用launches/query的$elemMatch统计 RTLS/ASDS 数据后回写PATCH /v4/cores/:id——这为外部开发者示范了「查询 → 统计 → 回写」的完整自动化用法。综上POST /v4/cores/query是一个覆盖「过滤 排序 分页 关联填充 全文检索」全能力的通用查询端点。只要遵循 MongoDB 查询语法与本文列出的 options 参数即可轻松构建从简单筛选到复杂多维统计的各种业务查询。赞分享后端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点击查看免费下载相关推荐Ruffle 测试工程实践EmptyFunctionName 验收测试的 source.tar.xz 归档机制与 Windows 大小写敏感文件系统问题Ruffle 测试工程实践EmptyFunctionName 验收测试的 source.tar.xz 归档机制与 Windows 大小写敏感文件系统问题 导读后端API设计Hermes WebUI Workspace Git 控制默认只读、可安全开启的浏览器端 Git 操作设计Hermes WebUI Workspace Git 控制默认只读、可安全开启的浏览器端 Git 操作设计 Workspace Git 控制Workspac后端API设计SpaceX-API Capsules Query 接口实战指南基于 Mongo 查询语法与分页机制的数据检索SpaceX API Capsules Query 接口实战指南基于 Mongo 查询语法与分页机制的数据检索 导读 本文围绕 SpaceX API 开源项目后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考