企业官网建设流程全解析

• 后端
• API设计

本篇技术指南聚焦开源项目 SpaceX-API 中获取单个 Dragon 航天器（Dragon capsule）详情的 REST 端点GET /v4/dragons/:id，涵盖请求方法、URL 参数、认证要求、完整响应字段逐项解析、404 错误处理，并结合仓库源码（路由实现、Mongoose 模型、Redis 缓存中间件）讲解其底层工作方式。读完本文，你将能够独立调用该端点完成 Dragon 数据检索、按字段理解每一个返回指标，并在此基础上扩展使用查询与分页能力。

端点速览：方法与 URL

Dragon 单条记录查询是 v4 API 中最常用的端点之一，定义在 docs/dragons/v4/one.md 中，其核心契约如下：

该端点属于公开只读路由，无需携带任何认证头即可访问。与之对应的完整端点族还包括：

• GET /v4/dragons—— 获取全部 Dragon，见 docs/dragons/v4/all.md；
• POST /v4/dragons/query—— 自定义查询与分页，见 docs/dragons/v4/query.md；
• GET /v4/dragons/:id—— 本文主角，按 ID 取单条记录。

获取 Dragon 的 ID

id是 MongoDB 生成的 24 位十六进制字符串 ObjectId，例如示例中的5e9d058759b1ff74a7ad5f8f。获取 id 的常见方式：

1. 调用GET /v4/dragons获取全部记录，从返回数组的id字段中挑选目标；
2. 或使用POST /v4/dragons/query按name等字段筛选后读取docs[].id。

实测：一行命令发起请求

由于端点无需认证，你可以直接使用curl或任意 HTTP 客户端调用。以文档示例中的 Dragon 1 为例：

curl https://api.spacexdata.com/v4/dragons/5e9d058759b1ff74a7ad5f8f

若记录存在，服务端返回200 OK与一个完整的 Dragon JSON 对象（字段详解见下一节）；若该 id 在集合中不存在，则返回404 NOT FOUND，响应体为纯文本Not Found。这是该端点仅有的两种响应结果，契约非常简洁。

成功响应200 OK：返回字段逐项解析

文档给出了完整的成功响应示例，对应航天器 "Dragon 1"（id: 5e9d058759b1ff74a7ad5f8f）。以下结合 docs/dragons/v4/schema.md 与 models/dragons.js 中的类型定义，逐层拆解每个字段的含义与数据类型。

顶层字段

嵌套子对象

在数据模型中，thrusters字段被声明为type: mongoose.Mixed（见 models/dragons.js 第 59-61 行），即不限制内部结构，允许如上所示的任意嵌套对象数组；而其余嵌套对象（如heat_shield、trunk）则定义了严格的子字段类型。id字段由mongoose-id插件自动生成（models/dragons.js 第 157 行），响应中同时保留_id与id两种形式。

源码视角：这个端点在后端是如何实现的

路由定义

GET /v4/dragons/:id的路由实现在 routes/dragons/v4/index.js 第 21-28 行：

router.get('/:id', cache(86400), async (ctx) => { const result = await Dragon.findById(ctx.params.id); if (!result) { ctx.throw(404); } ctx.status = 200; ctx.body = result; });

从源码结构可以看到三条关键链路：

1. 路由前缀：路由注册在prefix: '/(v4|latest)/dragons'下，因此/v4/dragons/:id与/latest/dragons/:id均指向同一处理器；
2. 数据库查询：通过 Mongoose 模型的findById(ctx.params.id)按 ObjectId 精确查找（模型定义见 models/dragons.js）；
3. 404 处理：当查询结果为空时调用ctx.throw(404)，Koa 会将其转换为标准的404 Not Found响应——这正是文档 Error Responses 一节所述行为的实现来源。

缓存机制：Dragon 数据缓存 24 小时

注意路由上的cache(86400)中间件。SpaceX-API 使用 Redis 做响应缓存，中间件实现在 middleware/cache.js。对 Dragon 端点而言：

• 缓存 TTL 为 86400 秒，即24 小时（docs/README.md 的 Caching 一节明确列出 dragons 的缓存时间为 24 小时，与 rockets 同级；而 launches 仅 20 秒）；
• 缓存 key 由method + url + body经 BLAKE3 哈希生成，命中时响应头携带spacex-api-cache: HIT，未命中时携带MISS，并回写缓存；
• 仅GET与POST请求参与缓存，且只在NODE_ENV=production下生效。

因此对调用方来说，短时间内的重复请求会直接命中 Redis，延迟更低，且可观测到上述响应头。

认证与写操作对照

GET /:id无需认证，但同一路由文件中的写操作（POST、PATCH、DELETE，见 routes/dragons/v4/index.js 第 43-71 行）均挂载了auth与authz('dragon:create'/'update'/'delete')中间件，需要在请求头携带spacex-keyAPI Key，否则返回401。这也印证了只读检索端点的公开性定位。

错误处理：何时收到404 NOT FOUND

该端点的错误契约非常单一（见 docs/dragons/v4/one.md）：

• 状态码：404 NOT FOUND
• 响应体：纯文本Not Found

触发条件为：传入的id在 Dragon 集合中不存在。常见错误姿势包括：

# id 不存在（记录已删除或 id 拼写错误） curl https://api.spacexdata.com/v4/dragons/5e9d058759b1ff74a7ad5f8f0 # => 404 Not Found # 注意：若 id 格式非法（非 ObjectId），可能由 Mongoose 抛错， # 但按路由实现 findById 对合法格式的查询返回 null 时统一走 404

从实现看，findById在查无记录时返回null，路由随即ctx.throw(404)；而一旦命中，ctx.body = result会直接序列化 Mongoose 文档为 JSON 输出。

从单条查询到批量与自定义检索

单条查询返回的完整字段结构，同样适用于 Dragon 端点族的其他能力：

• 获取全部：GET /v4/dragons返回所有 Dragon 的数组，按name升序排列（排序逻辑见 routes/dragons/v4/index.js 第 12 行sort: { name: 'asc' }）；
• 自定义查询 + 分页：POST /v4/dragons/query支持 MongoDB 查询语法与select、sort、limit、page、populate等分页选项，返回totalDocs、hasNextPage等分页元数据，详见 docs/dragons/v4/query.md 与通用指南 docs/queries.md。

例如，若你想在返回结果中只挑选指定字段，可以使用/query端点并在options.select中声明字段投影，从而复用在本文中解析过的字段名：

curl -X POST https://api.spacexdata.com/v4/dragons/query \ -H "Content-Type: application/json" \ -d '{ "query": { "name": "Dragon 1" }, "options": { "select": { "name": 1, "active": 1, "dry_mass_kg": 1 } } }'

小结

GET /v4/dragons/:id是 SpaceX-API 中结构清晰、契约简单的只读端点：无需认证、一条 URL 即返回完整 Dragon 档案，字段覆盖热防护、载荷能力、推进器、结构尺寸等全部维度。理解其背后的 Mongoose 模型 与 路由实现，能帮助你准确解释每一个返回指标；而 24 小时 Redis 缓存的机制（middleware/cache.js）则解释了该端点出色的响应稳定性。需要进阶检索时，可无缝切换到 批量查询 端点，实现对 Dragon 数据的全量、筛选与分页访问。

• 后端
• API设计