SpaceX-API 单条历史事件查询接口详解：GET /v4/history/:id 的请求、响应与源码实现

SpaceX-API 单条历史事件查询接口详解GET /v4/history/:id 的请求、响应与源码实现【免费下载链接】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导读GET /v4/history/:id是 SpaceX-API开源 REST API提供火箭、发射、核心舱、龙飞船、星链、发射场与着陆场等数据的接口中用于按 ID 获取单条历史事件记录的接口。本文以官方文档 docs/history/v4/one.md 为骨架结合仓库中 Koa 路由、Mongoose 模型与 Redis 缓存中间件的真实源码讲解该接口的请求方式、URL 参数、成功与错误响应、字段语义以及它背后的数据模型与缓存机制帮助读者直接复制使用或二次开发自建服务。接口总览该接口属于 History历史事件资源模块的 v4 版本与同模块的 获取全部历史事件 all.md、条件查询 query.md、数据模型 schema.md 共同构成完整的历史事件数据访问面。项目说明MethodGETURLhttps://api.spacexdata.com/v4/history/:idURL 参数id[string]即历史事件的 MongoDB ObjectIdAuth requiredFalse公开接口无需任何认证成功响应200 OK错误响应404 NOT FOUND响应体为Not Found路由前缀在源码中定义为/(v4|latest)/history因此v4与latest两个版本路径指向同一实现见 routes/history/v4/index.js。请求示例由于该接口不需要认证可以直接用curl发起请求curl https://api.spacexdata.com/v4/history/5eb87d9ffd86e000604b3649其中末尾的5eb87d9ffd86e000604b3649即为目标历史事件的id。若希望在本机环境中复现仓库为只读仅作查看与本地运行可先参考 README.md 配置 MongoDB 与 Redis 后启动服务再请求http://localhost:3000/v4/history/:id。说明id是 MongoDB 的 ObjectId 字符串24 位十六进制。如果传入的不是合法 ObjectId 格式错误处理中间件会将其归为 404 而非 500详见下文「错误响应与底层处理」一节。成功响应解析文档给出的200 OK响应示例{ 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/ } }这是一个 Crew Dragon Demo-2 任务的里程碑事件——自 2011 年航天飞机退役后美国首次从本土载人发射。响应体是一个扁平 JSON 对象各字段的语义与类型可对照 docs/history/v4/schema.md 的数据模型定义字段类型默认值语义titleStringnull事件标题event_date_utcStringnull事件发生时间的 UTC 表示ISO 8601 字符串event_date_unixNumbernull事件发生时间的 Unix 时间戳秒detailsStringnull事件详细描述文本linksObject—事件相关链接links.articleStringnull该事件的新闻报道 URL其中event_date_utc字符串与event_date_unix数字是同一时刻的两种表示二者可相互换算示例中2020-05-30T19:22:00Z对应1590866520秒。此外因为模型上挂载了idPlugin见 models/history.js响应中还包含id字段用于标识该记录。数据模型与字段约束源码视角接口返回的字段结构直接由 Mongoose 模型决定。历史事件模型定义在 models/history.jsconst 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 });值得注意的两点实现事实文本索引模型对title与details两个字符串字段建立了text索引models/history.js这意味着 docs/history/v4/query.md 的query接口可以直接使用 MongoDB 的$text全文检索在历史事件标题与详情中进行关键词搜索而单条查询接口本身则依赖_id主键进行 O(1) 级别的精确命中。空值语义所有字段默认值为null即未录入的事件字段会返回null而不是缺失键调用方在解析时无需做键存在性判断。路由实现从请求到响应的完整链路该接口的后端实现位于 routes/history/v4/index.js// Get one history event router.get(/:id, cache(300), async (ctx) { const result await History.findById(ctx.params.id); if (!result) { ctx.throw(404); } ctx.status 200; ctx.body result; });调用链可以拆解为三步Koa 路由匹配GET /v4/history/:id或GET /latest/history/:id命中该 handler:id参数通过ctx.params.id取出。Mongoose 查询History.findById(ctx.params.id)直接按主键查询单条文档。History模型在 models/index.js 中统一导出路由层通过import { History } from ../../../models/index.js引用。结果处理查不到记录时调用ctx.throw(404)抛出 Koa 错误由全局错误中间件转换为404状态码与Not Found文本响应查到则返回200与文档 JSON。整个模块的GET、POST、PATCH、DELETE等写操作均受auth与authz中间件保护只有查询类接口GET /、GET /:id、POST /query对外开放这也印证了文档中「Auth required: False」的说明。错误响应与底层处理文档明确记录的唯一错误场景为404 NOT FOUND Content: Not Found从源码结构看该错误被处理为 404 的路径有两条记录不存在History.findById返回null路由层显式ctx.throw(404)ID 格式非法传入非 ObjectId 的字符串时Mongoose 会抛出kind ObjectId的 CastError由 middleware/errors.js 统一拦截并改写为404if (err?.kind ObjectId) { err.status 404; }这一设计把「非法 ID」与「记录不存在」都收敛为 404避免将客户端参数问题暴露为 500 服务端错误。此外错误中间件对ctx.throw抛出的错误会透传其status对未知错误则回退到500。缓存行为Redis BLAKE3查询接口带有cache(300)中间件TTL 为 300 秒实现位于 middleware/cache.js。以下几个行为对调用方有直接影响仅生产环境生效当NODE_ENV ! production时缓存直接跳过本地调试不会产生缓存污染。响应头标识命中缓存时响应携带spacex-api-cache: HIT未命中回源后为spacex-api-cache: MISSRedis 在线与否通过spacex-api-cache-online头标明。同时接口会返回Cache-Control: max-age300。缓存键设计缓存键由BLAKE3对method url body哈希生成middleware/cache.js因此不同:id的请求互不影响相同 ID 的请求在 5 分钟内可直接命中 Redis减轻数据库压力。因此对于高频轮询同一历史事件的场景第一次请求后 300 秒内的重复请求将由 Redis 直接应答这也是该公开接口能够承受高并发访问的底层保障之一。与同模块其他接口的关联单条查询接口与历史事件模块的其他文档型接口配合使用构成完整的取数方案获取全部历史事件GET /v4/history返回全量历史事件数组适合首次拉取或数据量小的场景条件查询POST /v4/history/query支持 MongoDB 查询语法与分页是分页与聚合查询指南 docs/queries.md 中描述的通用/query模式的一部分——响应体包含docs、totalDocs、page、hasNextPage等分页元数据数据模型定义返回字段的类型与默认值是解析响应的权威参考。实际使用中推荐先用GET /v4/history或POST /v4/history/query获取事件列表拿到id再通过GET /v4/history/:id精确拉取单条事件的完整详情这样既能利用文本索引与分页缩小数据面又能借助单条接口的 Redis 缓存获得低延迟的重复访问体验。小结GET /v4/history/:id是一个零认证、语义清晰的单文档读取接口请求路径只携带一个id参数成功返回包含标题、事件时间UTC 与 Unix 双格式、详情与文章链接的 JSON 对象失败统一返回404 Not Found。从 routes/history/v4/index.js 的实现可以看到该接口由 Koa Router 匹配、Mongoose 主键查询与 Redis 缓存三层构成其字段结构由 models/history.js 的 Schema 直接驱动。无论是直接消费官方 API还是参考此实现自建 SpaceX 数据服务本文所述的请求方式、字段语义与错误处理规则均可直接复用。【免费下载链接】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），仅供参考