SpaceX-API v4 Crew 接口详解：数据模型、查询分页与缓存实现

后端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 开源仓库的 Crew 接口文档 为核心系统讲解 v4 版本/v4/crew端点的完整用法如何获取全部与单个宇航员成员、如何通过/query端点做条件筛选与分页、Crew 数据模型的字段约束以及底层路由与 Redis 缓存机制的真实实现。读完本文你将能够直接使用curl或任意 HTTP 客户端消费该接口并理解如何用populate将成员关联的发射 ID 展开为完整发射文档。一、Crew 资源概述与数据模型Crew 端点提供 SpaceX 载人龙飞船Dragon任务中宇航员成员的详细信息属于该项目 v4 版本 16 类核心资源之一与 capsules、cores、launches、starlink 等资源并列见 docs/README.md。数据模型的权威定义在 schema 文档 中共有 6 个字段{ name: { type: String, default: null }, status: { type: String, required: true, enum: [active, inactive, retired, unknown] }, agency: { type: String, default: null }, image: { type: String, default: null }, wikipedia: { type: String, default: null }, launches: [{ type: UUID }] }字段说明字段类型是否必填说明nameString否默认null成员姓名如Robert BehnkenstatusString是成员状态枚举值限定为active、inactive、retired、unknownagencyString否默认null所属机构如NASAimageString否默认null头像图片 URLwikipediaString否默认null维基百科词条 URLlaunchesUUID 数组否该成员参与的发射文档 ID 列表从源码看这套模型在 models/crew.js 中有完全对应的 Mongoose Schema 实现status字段同样声明了required: true与[active, inactive, retired, unknown]枚举校验launches字段在文档层面标为 UUID源码实现为mongoose.ObjectId并ref: Launch即指向 launches 集合的外键引用。此外模型上还建立了name字段的 text 文本索引并挂载了mongoose-paginate-v2与mongoose-id两个插件——前者为/query端点提供分页能力后者负责在序列化输出时把_id暴露为id字段。二、获取全部成员GET /v4/crew这是 all.md 的核心端点用于拉取所有宇航员成员。属性值MethodGETURLhttps://api.spacexdata.com/v4/crewAuth requiredFalse公开只读成功响应200 OK响应类型JSON 数组成功响应示例数组中的每个元素即一名成员[ { name: Robert Behnken, agency: NASA, image: https://imgur.com/0smMgMH.png, wikipedia: https://en.wikipedia.org/wiki/Robert_L._Behnken, launches: [ 5eb87d46ffd86e000604b388 ], status: active, id: 5ebf1a6e23a9a60006e03a7a }, ... ]使用curl调用curl https://api.spacexdata.com/v4/crew底层实现路由与缓存该端点在 routes/crew/v4/index.js 中实现路由前缀为/(v4|latest)/crew意味着 v4 与latest两个版本共享同一套实现router.get(/, cache(300), async (ctx) { const result await Crew.find({}); ctx.status 200; ctx.body result; });两个值得注意的细节响应缓存路由挂载了cache(300)中间件300秒即 5 分钟 TTL与 docs/README.md 中 crew - 5 minutes 的缓存说明一致。缓存基于 Redis 实现见 middleware/cache.js只在NODE_ENV production时生效命中和未命中分别通过响应头spacex-api-cache: HIT/spacex-api-cache: MISS暴露缓存键由BLAKE3(method url body)生成。非生产环境下所有缓存逻辑会被跳过便于本地开发调试。空结果处理Crew.find({})即使没有数据也返回200和空数组不会抛出异常。三、获取单个成员GET /v4/crew/:id对应文档 one.md用于按 ID 获取指定成员。属性值MethodGETURLhttps://api.spacexdata.com/v4/crew/:idURL 参数id[string]成员 IDAuth requiredFalse成功响应200 OK单个 JSON 对象错误响应404 NOT FOUND响应体为Not Found成功响应示例{ name: Douglas Hurley, agency: NASA, image: https://i.imgur.com/ooaayWf.png, wikipedia: https://en.wikipedia.org/wiki/Douglas_G._Hurley, launches: [ 5eb87d46ffd86e000604b388 ], status: active, id: 5ebf1b7323a9a60006e03a7b }调用方式curl https://api.spacexdata.com/v4/crew/5ebf1b7323a9a60006e03a7b源码中的对应实现会先执行Crew.findById(ctx.params.id)查不到记录时主动抛出404router.get(/:id, cache(300), async (ctx) { const result await Crew.findById(ctx.params.id); if (!result) { ctx.throw(404); } ctx.status 200; ctx.body result; });注意id必须是与 schema 匹配的合法 MongoDB ObjectId 格式字符串若传入非法格式Mongoose 会抛出校验错误并返回400。四、查询与分页POST /v4/crew/query对应文档 query.md是 Crew 接口中功能最强大的端点支持任意 MongoDB 查询条件、字段筛选、排序与分页。属性值MethodPOSTURLhttps://api.spacexdata.com/v4/crew/queryAuth requiredFalseBodyJSON含query与options两个对象成功响应200 OK分页包装结构错误响应400 Bad RequestMongoose 错误信息附修复建议请求体骨架{ query: {}, options: {} }成功响应示例{ docs: [ { name: Robert Behnken, agency: NASA, image: https://imgur.com/0smMgMH.png, wikipedia: https://en.wikipedia.org/wiki/Robert_L._Behnken, launches: [ 5eb87d46ffd86e000604b388 ], status: active, id: 5ebf1a6e23a9a60006e03a7a } ], totalDocs: 2, offset: 0, limit: 10, totalPages: 1, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: false, prevPage: null, nextPage: null }查询参数详解query接受任意合法的 MongoDBfind()查询详见项目文档 docs/queries.md。例如只筛选状态为active的成员{ query: { status: active }, options: {} }由于模型为name字段建立了文本索引还可以直接使用$text做全文搜索见 models/crew.js 中crewSchema.index({ name: text }){ query: { $text: { $search: Behnken } } }options支持以下常用分页与输出控制参数同样来自 docs/queries.md 的通用约定参数类型说明selectObject / String指定返回字段默认返回全部字段sortObject / String排序规则如{ name: asc }offsetNumber跳过条数与page二选一pageNumber页码从 1 开始limitNumber每页条数示例响应中默认10paginationBoolean设为false时返回全部文档、不加 limit默认truepopulateArray / Object / String将外键 ID 展开为关联文档例如只获取成员姓名并按名称排序{ query: {}, options: { select: { name: 1, status: 1 }, sort: { name: asc }, limit: 20 } }用 populate 展开关联发射Crew 文档中的launches数组保存的是 Launch 集合的引用 IDmodels/crew.js 中ref: Launch。要一次性把 ID 替换为完整的发射文档只需在options.populate中声明该路径{ query: {}, options: { populate: [launches] } }若只关心发射的部分字段可配合select精简返回{ options: { populate: [ { path: launches, select: { name: 1, date_utc: 1 } } ] } }populate 还支持嵌套例如在发射文档内部继续展开其rocket关联具体嵌套写法与更多示例可参考 docs/queries.md 的 Populate 章节——该指南对所有/query端点通用。底层实现查询端点基于mongoose-paginate-v2插件的paginate方法实现routes/crew/v4/index.jsrouter.post(/query, cache(300), async (ctx) { const { query {}, options {} } ctx.request.body; const result await Crew.paginate(query, options); ctx.status 200; ctx.body result; });从中可以确认三个实现事实请求体可省略缺省时自动使用空查询{}与空选项{}查询异常时捕获错误并抛出400错误信息即 Mongoose 的报错提示/query同样走cache(300)缓存中间件且缓存键包含请求体BLAKE3(method url body)因此相同条件的查询会命中同一份缓存这是 middleware/cache.js 中 GET/POST 双方法缓存白名单设计的关键价值。五、写操作与权限控制/v4/crew端点除只读接口外还提供了受保护的管理操作源码见 routes/crew/v4/index.js方法路径权限说明POST/v4/crewcrew:create新增成员PATCH/v4/crew/:idcrew:update局部更新成员DELETE/v4/crew/:idcrew:delete删除成员这些写操作依次经过auth校验spacex-key请求头中的 API Key与authz(crew:xxx)校验角色权限两道中间件。根据 docs/README.md 的说明所有 destructive 路由create / update / delete都必须携带 API Key 认证未带有效 Key 返回401角色权限不足返回403见 middleware/authz.js 中ctx.status 403的实现。更新操作使用findByIdAndUpdate(..., { runValidators: true })会触发 schema 校验如status的枚举限制非法取值同样返回400。由于这套写接口面向的是 API 管理方而非普通消费者日常数据消费场景只需关注前文三个只读端点。六、实际调用小结围绕 Crew 接口最常见的四个实战场景汇总如下# 1. 获取全部成员 curl https://api.spacexdata.com/v4/crew # 2. 获取单个成员 curl https://api.spacexdata.com/v4/crew/5ebf1b7323a9a60006e03a7b # 3. 按状态筛选 分页 排序 curl -X POST https://api.spacexdata.com/v4/crew/query \ -H Content-Type: application/json \ -d { query: { status: active }, options: { limit: 5, sort: { name: asc } } } # 4. 查询并展开关联发射文档 curl -X POST https://api.spacexdata.com/v4/crew/query \ -H Content-Type: application/json \ -d { query: {}, options: { populate: [launches] } }以上四个场景对应的响应结构、错误码与字段含义均已在前文结合 all.md、one.md、query.md、schema.md 及 routes/crew/v4/index.js、models/crew.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点击查看免费下载相关推荐SpaceX-API Crew 数据查询实战指南掌握 /v4/crew/query 端点与 MongoDB 分页检索SpaceX API Crew 数据查询实战指南掌握 /v4/crew/query 端点与 MongoDB 分页检索 导读 本文围绕 SpaceX API 开后端API设计SpaceX-API 陆上着陆场查询接口详解/v4/landpads/query 的查询语法、分页与数据关联SpaceX API 陆上着陆场查询接口详解/v4/landpads/query 的查询语法、分页与数据关联 本篇文章围绕开源项目 SpaceX API 中后端API设计SpaceX-API v4 Capsules 全量查询接口详解GET /v4/capsules 的字段语义、缓存机制与源码实现SpaceX API v4 Capsules 全量查询接口详解GET /v4/capsules 的字段语义、缓存机制与源码实现 本指南围绕 SpaceX AP后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考