SpaceX-API 历史事件查询指南:使用 POST /v4/history/query 构建灵活的历史数据检索
后端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 仓库中的docs/history/v4/query.md为核心系统讲解如何通过POST https://api.spacexdata.com/v4/history/query端点查询 SpaceX 历史事件数据。你将掌握该端点的请求格式、分页参数、全文检索与日期范围筛选等实战技巧并深入理解其背后的 Mongoose 数据模型与 Koa 路由实现从而能够在自己的应用中构建准确、高效的历史事件数据查询方案。一、端点概览/v4/history/query是 SpaceX-API v4 中历史事件History模块的查询入口与返回全部数据的GET /v4/history见 all.md和返回单条数据的GET /v4/history/:id见 one.md不同它通过POST请求体传入 MongoDB 查询条件与分页选项实现精确筛选、排序和分页读取。属性值MethodPOSTURLhttps://api.spacexdata.com/v4/history/queryAuth requiredFalseContent-Typeapplication/json请求体默认结构{ query: {}, options: {} }其中query接受任意合法的 MongoDBfind()查询语句用于条件过滤options接受 mongoose-paginate-v2 支持的分页与字段控制选项用于排序、分页、字段裁剪等。完整的分页与查询语法说明见仓库根目录的 queries.md 指南本节所有示例均遵循该指南约定。二、底层实现从路由到数据模型在深入请求参数之前先看该端点在仓库中的真实实现这有助于理解各个选项是如何生效的。路由定义位于 routes/history/v4/index.js核心代码为router.post(/query, cache(300), async (ctx) { const { query {}, options {} } ctx.request.body; try { const result await History.paginate(query, options); ctx.status 200; ctx.body result; } catch (error) { ctx.throw(400, error.message); } });从源码可以确认以下实现事实请求体被解构为query和options两个对象未提供时默认为空对象查询经由History.paginate(query, options)执行该方法来自 mongoose-paginate-v2 插件查询失败时抛出400 Bad Request响应体为 Mongoose 错误信息及修正建议与原文档中 Error Responses 一节描述一致该路由还挂载了cache(300)中间件即 300 秒 Redis 缓存详见 middleware/cache.js。数据模型位于 models/history.js其 Schema 定义了可查询的字段结构const historySchema new mongoose.Schema({ title: { type: String, default: null }, event_date_utc: { type: String, default: null }, event_date_unix: { type: Number, default: null }, details: { type: String, default: null }, links: { article: { type: String, default: null } }, }, { autoCreate: true }); const index { title: text, details: text, }; historySchema.index(index); historySchema.plugin(mongoosePaginate); historySchema.plugin(idPlugin); const History mongoose.model(History, historySchema);关键点title与details被声明为text 索引这正是$text全文检索能够工作的前提见下文示例模型通过mongoosePaginate插件获得paginate()能力通过idPlugin暴露id字段该模型经由 models/index.js 统一导出供路由层引用。三、成功响应结构当查询成功时接口返回200 OK响应体是标准的分页结构每页默认limit为 10{ docs: [ { title: SpaceX successfully launches humans to ISS, event_date_utc: 2020-05-30T19:22:00Z, event_date_unix: 1590866520, details: This mission was the first crewed flight to launch from the United States since the end of the Space Shuttle program in 2011. It carried NASA astronauts Doug Hurley and Bob Behnken to the ISS., links: { article: https://spaceflightnow.com/2020/05/30/nasa-astronauts-launch-from-us-soil-for-first-time-in-nine-years/ } } ... ], totalDocs: 7, offset: 0, limit: 10, totalPages: 1, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: false, prevPage: null, nextPage: null }各字段含义如下字段含义docs当前页命中的历史事件数组元素结构与 schema.md 中定义的一致totalDocs满足查询条件的文档总数offset当前页跳过的文档数limit每页返回的最大条数totalPages总页数page当前页码从 1 开始pagingCounter当前页第一条记录的全局序号hasPrevPage/hasNextPage是否存在上一页 / 下一页prevPage/nextPage上一页 / 下一页页码不存在时为null四、options 常用参数详解options支持 mongoose-paginate-v2 的全部选项原文档 queries.md 中归纳了最常用的几个select{ Object | String }—— 指定要返回的字段默认返回全部字段sort{ Object | String }—— 排序方式如{ event_date_unix: desc }offset{ Number }—— 跳过的文档数量与page二选一即可设定起始位置page{ Number }—— 页码limit{ Number }—— 每页条数pagination{ Boolean }—— 设为false时返回全部匹配文档而不施加limit默认truepopulate{ Array | Object | String }—— 需要填充为完整文档的关联路径。4.1 分页与排序按事件时间倒序取第二页每页 5 条{ query: {}, options: { page: 2, limit: 5, sort: { event_date_unix: desc } } }4.2 字段裁剪只返回标题与事件时间减少响应体积{ query: {}, options: { select: { title: 1, event_date_utc: 1 } } }4.3 关闭分页获取全量{ query: {}, options: { pagination: false } }五、query 过滤实战示例query接受任意合法的 MongoDB 查询语法。以下示例均针对 History 集合的字段设计可直接复制到请求体中验证。5.1 按时间范围筛选历史事件的event_date_utc为 ISO 8601 格式字符串配合$gte、$lte可实现区间筛选。日期需符合 ISO 8601 才能正确比较{ query: { event_date_utc: { $gte: 2017-06-22T00:00:00.000Z, $lte: 2017-06-25T00:00:00.000Z } } }也可以直接基于 Unix 时间戳字段event_date_unix进行数值区间查询同样使用$gte/$lte。5.2 全文检索对title和details做关键词搜索。由于这两个字段已建立 text 索引可直接使用$text{ query: { $text: { $search: ISS } } }说明$text会检索集合中的所有 text 索引字段。MongoDB 还支持$text的其他操作符如$language、$caseSensitive、$diacriticSensitive如需更多细节可查阅 MongoDB 官方$text参考文档。5.3 组合条件将范围筛选与精确匹配结合例如查询 2020 年之后、且标题包含 launch 的事件{ query: { event_date_unix: { $gte: 1577836800 }, $text: { $search: launch } }, options: { sort: { event_date_unix: asc }, limit: 20 } }六、错误响应当查询条件非法例如字段名拼写错误、操作符使用不当时接口返回Code:400 Bad RequestContent: Mongoose 错误信息其中包含修正查询的建议。这一行为与路由实现中ctx.throw(400, error.message)的处理逻辑一致Mongoose 在解析查询失败时会抛出带描述信息的异常异常信息会直接作为响应体返回便于开发者定位问题。七、与其他 History 端点的配合使用/v4/history/query并非孤立的端点它可与同模块的其他端点组合成完整的数据消费方案端点用途GET /v4/history获取全部历史事件无分页见 all.mdGET /v4/history/:id按 ID 获取单条历史事件见 one.mdPOST /v4/history/query按条件筛选 分页查询本文主题典型场景是先用 query 端点按关键词或时间范围筛选出符合条件的id列表再对关键事件调用单条端点获取完整详情或者直接利用select裁剪字段在一次请求中完成数据抽取。八、补充说明缓存行为query 端点带有 300 秒 TTL 的 Redis 缓存实现见 middleware/cache.js且仅在NODE_ENVproduction且 Redis 可用时生效可通过响应头spacex-api-cacheHIT/MISS和Cache-Control: max-age300判断缓存命中情况。无需鉴权该端点Auth required: False与创建POST /v4/history需要history:create权限、更新PATCH /v4/history/:id、删除DELETE /v4/history/:id等写操作不同查询数据是公开能力。版本兼容路由前缀为/(v4|latest)/history见 routes/history/v4/index.js即v4与latest指向同一套实现文档中的请求同样适用于latest版本。九、小结POST /v4/history/query是访问 SpaceX 历史事件数据的核心查询接口。通过组合 MongoDB 查询语法$text、$gte/$lte、$or等与 mongoose-paginate-v2 分页选项sort、limit、page、select、pagination你可以精确检索特定时间段或主题的历史事件并灵活控制返回结构与数据量。结合 models/history.js 中的 text 索引与 routes/history/v4/index.js 的实现细节即可完整理解并可靠使用该端点。赞分享后端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点击查看免费下载相关推荐如何把 Qwen Code 打成白标桌面版Tauri 品牌化构建实战指南如何把 Qwen Code 打成白标桌面版Tauri 品牌化构建实战指南 需求摆在台面上给 Qwen Code 做一个 Acme AI 的白标whit人工智能AI Agent代码智能体工具调用交互助手CLIQwenSpaceX-API Launchpad 查询接口实战指南基于 POST /v4/launchpads/query 构建灵活查询与分页SpaceX API Launchpad 查询接口实战指南基于 POST /v4/launchpads/query 构建灵活查询与分页 本指南围绕 Space后端API设计SpaceX-API 历史事件接口全解析从 GET /v4/history 到查询、分页与源码实现SpaceX API 历史事件接口全解析从 GET /v4/history 到查询、分页与源码实现 本文以 docs/history/v4/all.md 定义后端API设计创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

图书馆座位预约管理系统:从抢座乱象到扫码落座的完整落地路径

图书馆座位预约管理系统:从抢座乱象到扫码落座的完整落地路径

简介:这份资源是《图书馆座位预约管理系统》的完整Java项目源码包,面向学习Java Web开发的学生与初级开发者,用于掌握从需求分析到系统落地的全过程。系统围绕座位状态查看、预约、取消及超时自动释放等核心功能展开,采用表现层、…

2026/11/22 14:30:23 阅读更多 →
PostGraphile 枚举(Enum)完整指南:PostgreSQL 枚举、Enum 表与 extendSchema 的三种实践方案

PostGraphile 枚举(Enum)完整指南:PostgreSQL 枚举、Enum 表与 extendSchema 的三种实践方案

后端API网关 【免费下载链接】crystal 🔮 Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more! 项目地址: https://gitcode.com/gh_mirrors/cry/crystal 点击查看 免费下载 导读 本指南聚焦 PostGr…

2026/11/22 14:30:23 阅读更多 →
极简命令行工具cua:用Shell脚本打造高效开发助手

极简命令行工具cua:用Shell脚本打造高效开发助手

1. 从一个代号说起:cua 到底是什么先交代背景。我第一次在内部工具仓库里看到cua这个命名时,第一反应是某个缩写。翻完文档才发现,它就是一次敲键盘时手指惯性打出来的三个字母,没有任何高深含义。后来用顺手了,反而觉…

2026/11/16 14:50:26 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/21 23:27:35 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/21 23:27:35 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/21 23:27:35 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/21 23:27:35 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/21 23:27:36 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/21 23:27:37 阅读更多 →

日新闻

周新闻

月新闻