企业官网建设流程全解析

• 后端
• API设计

本篇技术指南围绕 SpaceX-API 开源仓库（gh_mirrors/spa/SpaceX-API）中 docs/launches/v4/all.md 文档，系统讲解 v4 版本“获取全部发射记录（Get all launches）”接口的请求方式、响应结构、字段语义与底层实现。读完本文，你将掌握如何调用该接口拉取全量发射数据、理解每个返回字段的含义与数据类型、了解其与/past、/upcoming、/latest、/next、/query等关联端点的关系，并能结合源码理解接口的排序、缓存与数据转换机制。

接口速览

Get all launches是 v4 版本中最基础的只读端点之一，一次请求即可返回当前数据库中全部发射记录，每条记录对应一次 SpaceX 发射任务（例如 CRS-20 货运补给任务），并按任务编号（flight_number）升序排列。

一个最简单的调用示例（使用curl）：

curl -X GET "https://api.spacexdata.com/v4/launches"

响应是一个以[开头的 JSON 数组，数组中的每个元素是一条完整的发射记录对象，示例以CRS-20任务（flight_number: 91）为样例。

响应结构详解

成功响应状态码为200 OK，响应体为 JSON 数组。文档中给出的完整示例（CRS-20，Dragon 1 胶囊的最后一班 CRS 任务）如下：

[ { "fairings": null, "links": { "patch": { "small": "https://images2.imgbox.com/53/22/dh0XSLXO_o.png", "large": "https://images2.imgbox.com/15/2b/NAcsTEB6_o.png" }, "reddit": { "campaign": "https://www.reddit.com/r/spacex/comments/ezn6n0/crs20_launch_campaign_thread", "launch": "https://www.reddit.com/r/spacex/comments/fe8pcj/rspacex_crs20_official_launch_discussion_updates/", "media": "https://www.reddit.com/r/spacex/comments/fes64p/rspacex_crs20_media_thread_videos_images_gifs/", "recovery": null }, "flickr": { "small": [], "original": [ "https://live.staticflickr.com/65535/49635401403_96f9c322dc_o.jpg", "https://live.staticflickr.com/65535/49636202657_e81210a3ca_o.jpg", "https://live.staticflickr.com/65535/49636202572_8831c5a917_o.jpg", "https://live.staticflickr.com/65535/49635401423_e0bef3e82f_o.jpg", "https://live.staticflickr.com/65535/49635985086_660be7062f_o.jpg" ] }, "presskit": "https://www.spacex.com/sites/spacex/files/crs-20_mission_press_kit.pdf", "webcast": "https://youtu.be/1MkcWK2PnsU", "youtube_id": "1MkcWK2PnsU", "article": "https://spaceflightnow.com/2020/03/07/late-night-launch-of-spacex-cargo-ship-marks-end-of-an-era/", "wikipedia": "https://en.wikipedia.org/wiki/SpaceX_CRS-20" }, "static_fire_date_utc": "2020-03-01T10:20:00.000Z", "static_fire_date_unix": 1583058000, "tdb": false, "net": false, "window": 0, "rocket": "5e9d0d95eda69973a809d1ec", "success": true, "failures": [], "details": "SpaceX's 20th and final Crew Resupply Mission under the original NASA CRS contract, this mission brings essential supplies to the International Space Station using SpaceX's reusable Dragon spacecraft. It is the last scheduled flight of a Dragon 1 capsule. (CRS-21 and up under the new Commercial Resupply Services 2 contract will use Dragon 2.) The external payload for this mission is the Bartolomeo ISS external payload hosting platform. Falcon 9 and Dragon will launch from SLC-40, Cape Canaveral Air Force Station and the booster will land at LZ-1. The mission will be complete with return and recovery of the Dragon capsule and down cargo.", "crew": [], "ships": [], "capsules": [ "5e9e2c5cf359185d753b266f" ], "payloads": [ "5eb0e4d0b6c3bb0006eeb253" ], "launchpad": "5e9e4501f509094ba4566f84", "auto_update": true, "flight_number": 91, "name": "CRS-20", "date_utc": "2020-03-07T04:50:31.000Z", "date_unix": 1583556631, "date_local": "2020-03-06T23:50:31-05:00", "date_precision": "hour", "upcoming": false, "cores": [ { "core": "5e9e28a7f359187afd3b2662", "flight": 2, "gridfins": true, "legs": true, "reused": true, "landing_attempt": true, "landing_success": true, "landing_type": "RTLS", "landpad": "5e9e3032383ecb267a34e7c7" } ], "id": "5eb87d42ffd86e000604b384" }, ... ]

该数组未做分页限制，会一次性返回全部历史与已计划发射记录；对于需要按条件筛选、分页或聚合的场景，请改用POST /v4/launches/query（详见后文“关联端点”一节）。

字段语义与数据类型

对照仓库中 models/launches.js 的 Mongoose Schema（其完整 JSON 化描述见 docs/launches/v4/schema.md），逐字段说明如下：

标识与编号

日期与时间

提示：date_unix单位为秒而非毫秒，在 JavaScript 中需* 1000后再传入new Date()。

状态标志

任务信息与结果

关联引用（UUID 风格 ID）

这些字段存储的是指向其他集合文档的 ID 引用，属于典型的“外键”式设计：

cores为内嵌数组，每个元素包含：

媒体链接

links对象包含该次任务的全部媒体资源，均默认为null或空数组：

底层实现：路由、排序与响应转换

该端点在仓库中的实际路由定义位于 routes/launches/v4/index.js，核心处理逻辑为：

// Get all launches router.get('/', cache(20), async (ctx) => { try { const result = await Launch.find({}, null, { sort: { flight_number: 'asc', }, }); ctx.status = 200; ctx.body = await transformResponse(result); } catch (error) { ctx.throw(400, error.message); } });

从源码结构可以梳理出三条关键事实：

1. 默认排序：查询不带任何过滤条件（{}），但显式指定sort: { flight_number: 'asc' }，因此全量接口的返回顺序始终按任务编号从小到大排列。
2. 响应转换：结果会先经过transformResponse（实现在 routes/launches/v4/_transform-response.js）处理。该函数对数组、分页对象、单文档三种形态分别处理，核心作用是把内嵌的crew子文档中的crew引用对象解包为直接的 crew 引用（对应 v5 的crew.crew结构调整），使 v4 响应中的crew字段保持为 ID 数组形态。
3. 错误处理：任何查询异常都会以400 Bad Request返回，并携带 Mongoose 的错误信息。

路由前缀通过new Router({ prefix: '/v4/launches' })声明，因此GET /v4/launches正是上述处理器；所有 v4 launches 路由（含/past、/upcoming、/latest、/next、/:id、/query）统一在该文件内注册，并在 routes/launches/index.js 中与 v5 路由一并导出挂载。

缓存机制

全量接口使用了 20 秒的 Redis 缓存中间件（cache(20)）。缓存实现在 middleware/cache.js，要点如下：

• 仅在生产环境（NODE_ENV === 'production'）且 Redis 可用时启用缓存；
• 缓存键由method + url + body经 BLAKE3 哈希生成（如spacex-cache:<hash>）；
• 命中缓存时响应头带spacex-api-cache: HIT，未命中为MISS，同时设置Cache-Control: max-age=20与spacex-api-cache-online状态头；
• 仅GET与POST方法可被缓存，TTL 由中间件参数（此处为 20 秒）决定。

因此，同一秒内的重复请求会直接由 Redis 返回缓存结果，这是公共公开接口控制负载的主要手段。

关联端点速查

/v4/launches全量接口是整个 launches 模块的入口，仓库在 routes/launches/v4/index.js 中还提供了若干“便捷端点”（Convenience Endpoints）与标准端点：

用 Query 端点替代全量拉取

当全量接口返回数据过大时，应改用POST /v4/launches/query。该端点基于mongoose-paginate-v2实现（见 docs/queries.md），请求体为：

{ "query": {}, "options": {} }

其中query接受任意合法的 MongoDB find() 查询条件，options常用参数包括select（选择返回字段）、sort（排序）、page/offset（分页）、limit（每页条数）、pagination（设为false时返回全部文档）、populate（联表填充）。

例如按日期区间查询：

{ "query": { "date_utc": { "$gte": "2017-06-22T00:00:00.000Z", "$lte": "2017-06-25T00:00:00.000Z" } } }

由于launchSchema在 models/launches.js 中为name、details建立了text全文索引，还可以直接使用$text进行全文搜索：

{ "query": { "$text": { "$search": "crs" } } }

查询端点返回分页结构，包含docs、totalDocs、totalPages、hasPrevPage、hasNextPage等元数据字段，便于前端分页渲染。

引用填充（populate）

响应中的rocket、payloads、capsules等字段均为 ID 引用。若需要直接在响应中嵌入被引用的完整文档，可在 query 端点中使用populate：

{ "query": {}, "options": { "populate": ["payloads"] } }

也可以嵌套填充并选择性返回字段（如仅取载荷的name），具体示例可参阅 docs/queries.md 的 Populate 章节。注意：v4 路由在查询时还会经过 routes/launches/v4/_transform-query.js，将populate中的crew路径重写为crew.crew，以适配内部 schema 结构，这是 v4 兼容 v5 数据模型的关键转换。

v4 与 v5 的差异

如需了解该接口在 v5 版本中的演进，可参考 docs/launches/v5/README.md：v4 到 v5 的主要变化是crew字段由“ID 数组”演变为“包含角色信息的对象数组”，以便为每次发射中的每位乘员携带更多数据。v5 各端点文档位于 docs/launches/v5/ 目录（all.md、one.md、query.md等），两者在响应转换与查询转换层分别做了兼容处理。

小结与建议

GET /v4/launches是获取 SpaceX 全量发射数据最直接的入口，返回按flight_number升序排列的完整发射记录数组，无需认证即可调用。实际开发中的使用建议：

• 全量数据同步：适合定时任务、数据仓库初始化等低频场景，配合date_unix与flight_number做增量更新；
• 按需筛选：优先使用POST /v4/launches/query，配合query条件、select裁剪字段与populate联表填充，减少传输体积；
• 关注缓存头：生产环境响应带Cache-Control: max-age=20与spacex-api-cache头，可据此设计客户端缓存策略；
• 区分版本：v4 的crew为 ID 数组，v5 为对象数组，消费端需按版本解析。

相关源码与文档索引：路由实现 routes/launches/v4/index.js、数据模型 models/launches.js、Schema 文档 docs/launches/v4/schema.md、查询指南 docs/queries.md、缓存中间件 middleware/cache.js。

• 后端
• API设计