企业官网建设流程全解析

• 后端
• API设计

本篇技术指南围绕 SpaceX-API 开源项目（项目主页，仓库结构详见 docs 目录）中的GET /v4/launchpads端点展开，系统讲解如何一次性获取全部发射场（Launchpad）数据、响应字段的完整含义与类型约束，并结合仓库源码（Mongoose 模型、Koa 路由、Redis 缓存中间件、定时任务）深入剖析该接口的底层实现与数据维护机制。读完本文，你将能够熟练调用该端点、正确解析其 JSON 结构，并掌握launch_attempts/launch_successes等统计字段的来源，同时可顺藤摸瓜学会配套的单条查询与分页查询接口用法。

接口总览：Get all launchpads

/v4/launchpads是 SpaceX-API v4 中用于获取全部发射场数据的公开只读接口。该端点不需要任何形式的身份认证，返回的是一份按发射场聚合的完整 JSON 数组。

请求示例：

curl https://api.spacexdata.com/v4/launchpads

从路由实现看，该端点在 routes/launchpads/v4/index.js 中注册，路由前缀为/(v4|latest)/launchpads，即 v4 与 latest 版本共享同一实现：

// Get all launchpads router.get('/', cache(300), async (ctx) => { try { const result = await Launchpad.find({}); ctx.status = 200; ctx.body = result; } catch (error) { ctx.throw(400, error.message); } });

可以看到该路由背后直接调用的是 Mongoose 模型的Launchpad.find({})（空查询条件即返回集合全部文档），并由cache(300)中间件提供 300 秒的 Redis 缓存。若数据库查询异常，会以400 Bad Request返回错误信息。

响应字段详解：一次读懂全部发射场数据

成功响应体是一个 JSON 数组，数组中的每个元素代表一个发射场。以文档示例中的 VAFB SLC 4E（范登堡空军基地 4E 号发射台）为例：

{ "name": "VAFB SLC 4E", "full_name": "Vandenberg Air Force Base Space Launch Complex 4E", "locality": "Vandenberg Air Force Base", "region": "California", "timezone": "America/Los_Angeles", "latitude": 34.632093, "longitude": -120.610829, "launch_attempts": 15, "launch_successes": 15, "rockets": [ "5e9d0d95eda69973a809d1ec" ], "launches": [ "5eb87ce1ffd86e000604b334", "5eb87cf0ffd86e000604b343", "5eb87cfdffd86e000604b34c", "5eb87d05ffd86e000604b354", "5eb87d08ffd86e000604b357", "5eb87d0affd86e000604b359", "5eb87d0fffd86e000604b35d", "5eb87d14ffd86e000604b361", "5eb87d16ffd86e000604b363", "5eb87d1affd86e000604b367", "5eb87d1fffd86e000604b36b", "5eb87d23ffd86e000604b36e", "5eb87d25ffd86e000604b370", "5eb87d28ffd86e000604b373", "5eb87d31ffd86e000604b379" ], "status": "active", "id": "5e9e4502f509092b78566f87" }

数组尾部以...表示后续还有其他发射场元素，实际返回数量取决于当前数据集中收录的发射场总数。接口不会自动分页，而是返回全部记录。

数据模型：字段类型、默认值与取值约束

/v4/launchpads返回的每个字段都对应 models/launchpads.js 中的 Mongoose Schema 定义，其完整类型、默认值与约束如下（与官方 schema 文档 一致）：

{ "name": { "type": "String", "default": null }, "full_name": { "type": "String", "default": null }, "status": { "type": "String", "enum": [ "active", "inactive", "unknown", "retired", "lost", "under construction" ], "required": true }, "locality": { "type": "String", "default": null }, "region": { "type": "String", "default": null }, "timezone": { "type": "String", "default": null }, "latitude": { "type": "Number", "default": null }, "longitude": { "type": "Number", "default": null }, "launch_attempts": { "type": "Number", "default": 0 }, "launch_successes": { "type": "Number", "default": 0 }, "rockets": [ "UUID" ], "launches": [ "UUID" ] }

各字段要点：

• name / full_name：发射场简称与全称，均为可空字符串，默认null。
• status：发射场状态，是唯一必填字段，且只能取枚举中的六个值之一：active（在用）、inactive（停用）、unknown（未知）、retired（退役）、lost（丢失）、under construction（在建）。写入时会触发 Mongoose 枚举校验。
• locality / region / timezone：发射场所在地、所属区域与时区（IANA 时区名，如America/Los_Angeles）。
• latitude / longitude：经纬度，Number类型，默认null。
• launch_attempts / launch_successes：累计发射尝试次数与成功次数，Number类型，默认0。这两个字段并非手动维护，而是由定时任务根据发射数据自动统计（详见下文“统计字段的自动维护”一节）。
• rockets / launches：关联数据的UUID 引用数组。rockets引用 rockets 集合中的火箭；launches引用 launches 集合中的发射记录。默认只返回 UUID，如需替换为完整对象可使用 query 接口的populate选项（见下文）。
• id：该发射场的唯一标识（mongoose-id插件自动生成），后续可用它调用单条查询接口。

在源码层面，模型还做了两处值得注意的增强（见 models/launchpads.js）：

1. 文本索引：对name、full_name、details三个字段建立了text文本索引，支持全文检索查询；
2. 分页插件：挂载了mongoosePaginate，为 query 端点提供分页能力；同时挂载idPlugin自动生成id字段。

此外，模型还包含文档示例中未展示的details（描述文本）与images.large（大图 URL 数组）字段，它们同样会出现在实际响应中。

配套端点：单条查询与分页查询

all端点（GET /v4/launchpads）返回全部数据；当需要定位单个发射场或按条件筛选时，还有两个配套端点（同样定义在 routes/launchpads/v4/index.js 中）。

获取单个发射场：GET /v4/launchpads/:id

curl https://api.spacexdata.com/v4/launchpads/5e9e4502f509092b78566f87

其路由实现通过Launchpad.findById(ctx.params.id)查询（routes/launchpads/v4/index.js），查不到记录时由 Koa 抛出 404。

分页与筛选查询：POST /v4/launchpads/query

当需要按region、status等条件筛选，或控制返回条数时，使用 query 端点：

curl -X POST https://api.spacexdata.com/v4/launchpads/query \ -H "Content-Type: application/json" \ -d '{"query": {}, "options": {}}'

默认响应结构如下：

{ "docs": [ ... ], "totalDocs": 6, "offset": 0, "limit": 10, "totalPages": 1, "page": 1, "pagingCounter": 1, "hasPrevPage": false, "hasNextPage": false, "prevPage": null, "nextPage": null }

query接受任意合法的 MongoDBfind()查询语句，options支持select、sort、page、limit、populate、pagination等参数（pagination: false时返回全部文档而不加 limit）。完整的查询与分页指南见 docs/queries.md，其中还包含日期区间查询、$text全文检索、嵌套populate等进阶用法。

例如，按状态筛选加利福尼亚州在用的发射场并仅返回关键字段：

{ "query": { "region": "California", "status": "active" }, "options": { "select": { "name": 1, "full_name": 1, "latitude": 1, "longitude": 1 } } }

又如使用populate将launches中的 UUID 替换为完整的发射记录对象（可与select嵌套以限制返回字段）：

{ "query": {}, "options": { "populate": [ { "path": "launches", "select": { "name": 1, "date_utc": 1 } } ] } }

其实现位于 routes/launchpads/v4/index.js，核心是Launchpad.paginate(query, options)，由mongoose-paginate-v2插件负责执行查询与组装分页元数据。

统计字段的自动维护：launch_attempts 与 launch_successes

launch_attempts与launch_successes会随发射活动的推进而变化。在仓库中，这两个字段由后台定时任务 jobs/launchpads.js 自动重算，工作流程如下：

1. 通过POST /launchpads/query（pagination: false）拉取全部发射场；
2. 对每个发射场，并发地向POST /launches/query发起两次统计查询：
   • 条件{ launchpad: <id>, upcoming: false }统计已执行发射次数，写入launch_attempts；
   • 条件{ launchpad: <id>, upcoming: false, success: true }统计成功发射次数，写入launch_successes；
3. 通过PATCH /launchpads/:id（携带spacex-key请求头）回写统计结果；
4. 任务完成后触发健康检查 URL（若配置了LAUNCHPADS_HEALTHCHECK环境变量）。

因此，调用GET /v4/launchpads时看到的统计数字本质上是最近一次该任务运行时的快照，与 launches 接口中的历史发射记录相互印证。

缓存与生产环境行为

从 middleware/cache.js 的实现可以看出，GET /v4/launchpads的cache(300)中间件为响应提供了以下行为：

• 仅在NODE_ENV=production且 Redis 可用时启用缓存，缓存键由BLAKE3对方法 + URL + 请求体哈希生成；
• 缓存命中时响应头携带spacex-api-cache: HIT，未命中时为MISS，并会回写缓存 300 秒（Cache-Control: max-age=300）；
• 若 Redis 不可用，响应头会设置spacex-api-cache-online: false并直接透传请求，不影响接口可用性。

这意味着在短时间内多次调用该端点时，实际打到数据库的查询会被大幅削减，接口响应速度与稳定性均有保障。

从文档到实践：本地启动与验证

如需在本地环境复现上述接口行为，可参考 README.md 与 app.js、server.js 的入口实现。项目为 ESM 模块（"type": "module"，见 package.json），技术栈为 Koa + Mongoose + Redis（详见 package.json 的依赖清单），Node.js 版本要求>=14.16。

本地启动后，即可通过GET http://localhost:3000/v4/launchpads验证全量发射场接口，并通过 docs/launchpads/v4/all.md、docs/launchpads/v4/one.md、docs/launchpads/v4/query.md 三份文档逐一对照返回结果，完成从"拿全部数据"到"精确取单条"再到"条件分页筛选"的完整调用链路。

• 后端
• API设计