后端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），仅供参考