后端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点击查看免费下载导读本文以docs/crew/v4/schema.md中定义的 Crew 数据模型为核心系统讲解 SpaceX-API 开源仓库中宇航员Dragon Crew数据集合的字段结构、类型约束与取值枚举并结合 models/crew.js 的 Mongoose 实现与 routes/crew/v4/index.js 的路由代码说明该 Schema 如何被GET /v4/crew、GET /v4/crew/:id、POST /v4/crew/query等接口实际使用。读完本文你将能准确理解每个字段的含义与校验规则掌握基于该 Schema 编写查询、排序与populate关联展开的完整方法并了解写操作创建/更新/删除在 Schema 层面的行为。Crew Schema 总览docs/crew/v4/schema.md给出了 Crew 集合的完整 JSON 结构定义字段包括name、status、agency、image、wikipedia与launches。其中status为唯一必填字段且取值被限定为枚举[active, inactive, retired, unknown]launches是一个引用 Launch 集合的 UUIDObjectId数组。完整定义如下{ 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 }] }字段逐个拆解类型、默认值与校验规则name姓名类型String默认值null语义宇航员的全名例如示例数据中的Robert Behnken、Douglas Hurley。该字段在 models/crew.js 中实现为type: String, default: null表示该字段在文档创建时如未提供则保存为null允许为空。status状态唯一必填字段类型String必填required: true枚举[active, inactive, retired, unknown]status是 Crew 文档中唯一强制要求存在的字段对应源码 models/crew.js。其取值含义取值含义示例场景active现役处于任务名单中的现役宇航员如 Robert Behnkeninactive非现役在编但未执行任务已入选但尚未执行龙飞船任务的宇航员retired已退役已从宇航员岗位退休unknown状态未知无法确认当前状态注意枚举校验由 Mongoose 在文档保存与更新校验阶段强制执行而非仅靠 API 层判断。这意味着通过POST /v4/crew创建或PATCH /v4/crew/:id更新时若传入枚举之外的值如suspendedMongoose 会抛校验错误并返回400。agency所属机构类型String默认值null语义宇航员所属的航天机构或任务运营商例如NASA。与name一样未提供时保存为null见 models/crew.js。image头像图片类型String默认值null语义宇航员头像图片的 URL例如https://imgur.com/0smMgMH.png。该字段存储的是完整的图片外链地址示例中为 Imgur 图床API 本身不托管图片文件。wikipedia维基百科链接类型String默认值null语义宇航员在维基百科上的条目链接例如https://en.wikipedia.org/wiki/Robert_L._Behnken供查阅其详细履历。launches参与任务类型UUID数组默认值数组为空语义该宇航员参与的发射任务 ID 列表。在 Schema 文档中其类型标注为UUID对应源码 models/crew.js 的实现launches: [{ type: mongoose.ObjectId, ref: Launch, }],即底层实际是mongoose.ObjectId数组并通过ref: Launch声明了与 Launch 集合models/launches.js的外键关系。这正是后续populate查询能够将 ID 展开为完整发射文档的关键。补充文档级扩展id字段与时间戳Schema 文档中没有列出的id字段在 API 响应中始终存在如5ebf1a6e23a9a60006e03a7a。它由 models/crew.js 中的插件提供crewSchema.plugin(mongoosePaginate); crewSchema.plugin(idPlugin);idPluginmongoose-id为文档生成对外暴露的id字段mongoosePaginate为集合启用paginate()分页能力支撑/query接口此外 models/crew.js 为name字段建立了text文本索引使/query接口支持 MongoDB 的全文搜索$text查询。从 Schema 到接口Crew 路由如何消费该模型Crew 数据模型被挂载在/(v4|latest)/crew前缀下路由实现见 routes/crew/v4/index.js。共有五个接口消费该 Schema查询类接口公开无鉴权方法路径对应 Schema 用法文档GET/v4/crewCrew.find({})返回全部文档docs/crew/v4/all.mdGET/v4/crew/:idCrew.findById(id)返回单条不存在时404docs/crew/v4/one.mdPOST/v4/crew/queryCrew.paginate(query, options)分页查询docs/crew/v4/query.md以查询单个成员为例响应体中会包含 Schema 中全部六个业务字段加上id{ 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 }写操作类接口需鉴权方法路径Schema 行为POST/v4/crewnew Crew(body)创建校验失败返回400成功返回201PATCH/v4/crew/:idCrew.findByIdAndUpdate(id, body, { runValidators: true })更新DELETE/v4/crew/:idCrew.findByIdAndDelete(id)删除注意两点与 Schema 强相关的行为PATCH接口显式开启了runValidators: true因此更新操作同样会触发status枚举与必填校验而非只校验创建写操作全部通过auth与authz(crew:create)等中间件保护见 middleware/auth.js需要携带spacex-key请求头缺少有效密钥时返回401。根据 docs/README.md 的说明所有create/update/delete路由均为破坏性路由必须鉴权。缓存与性能Crew 响应的 TTL 策略所有查询类路由都包裹了cache(300)中间件见 routes/crew/v4/index.js即300 秒5 分钟的 Redis 响应缓存。这与 docs/README.md 中crew — 5 minutes的缓存说明一致。其底层实现见 middleware/cache.js仅在生产环境NODE_ENVproduction且 Redis 可用时启用缓存键由blake3对METHOD URL request body哈希生成因此POST /v4/crew/query的查询体也会参与缓存键计算不同查询体互不污染命中时响应头会带spacex-api-cache: HIT未命中回源后写入为MISS便于排查同时设置Cache-Control: max-age300供 CDN 与客户端使用。这意味着同一时刻大量针对 Crew 数据的读取请求会命中缓存有效降低 MongoDB 压力。查询实战基于 Schema 字段的组合查询与关联展开POST /v4/crew/query的请求体固定为{query: {}, options: {}}完整用法见 docs/queries.md。按状态过滤筛选所有现役宇航员{ query: { status: active }, options: { limit: 10 } }组合条件状态 机构同时命中status与agency两个字段{ query: { status: active, agency: NASA }, options: { sort: { name: asc } } }全文搜索由于name字段建立了文本索引models/crew.js可直接使用 MongoDB 的$text操作符搜索姓名{ query: { $text: { $search: Hurley } } }populate把任务 ID 展开为完整发射文档launches字段存储的是引用Launch集合的 ObjectId默认响应中仅返回 ID。通过options.populate可以将其展开为完整的发射对象{ query: {}, options: { populate: [launches] } }响应中launches数组的每一项将由 ID 替换为对应发射文档含name、date_utc、rocket等完整字段。也可以只挑选所需子字段{ query: {}, options: { populate: [ { path: launches, select: { name: 1, date_utc: 1 } } ] } }populate还支持嵌套展开例如在launches内继续展开其引用的rocket原理与 docs/queries.md 中 payloads 的示例一致其数据来源正是ref: Launch这一 Schema 关联声明。分页返回结构无论是否使用populate/query接口都会返回统一的分页结构totalDocs、limit、totalPages、page、hasPrevPage等例如{ docs: [ ... ], totalDocs: 2, offset: 0, limit: 10, totalPages: 1, page: 1, pagingCounter: 1, hasPrevPage: false, hasNextPage: false, prevPage: null, nextPage: null }分页由mongoosePaginate插件支撑options中可通过page/offset控制跳过位置pagination: false可关闭分页返回全量。从源码看 Schema 的完整闭环将本文内容串起来Crew 数据模型在仓库中的完整实现链路是定义Schema 结构在 models/crew.js 中定义业务文档 docs/crew/v4/schema.md 是其可读版本并通过 models/index.js 统一导出为Crew注册路由在 routes/crew/index.js 中按 v4 版本动态加载 routes/crew/v4/index.js挂载到/v4/crew前缀读写五个路由分别调用find/findById/paginate/save/findByIdAndUpdate/findByIdAndDeletestatus的枚举校验在写路径上被强制执行加速读路径由cache(300)中间件做 5 分钟 Redis 缓存关联launches通过ref: Launch与外键在查询时用populate展开。对于需要二次开发或本地调试的读者可直接基于该模型扩展字段如添加birth_date只需同步修改 models/crew.js 与 docs/crew/v4/schema.md 即可保持文档与实现一致运行时传入非法status值时接口会返回带 Mongoose 错误提示的400响应可直接作为字段约束的验证手段。赞分享后端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 v4 Crew 接口详解数据模型、查询分页与缓存实现SpaceX API v4 Crew 接口详解数据模型、查询分页与缓存实现 导读 本文以 SpaceX API 开源仓库的 Crew 接口文档 https:/后端API设计SpaceX-API Capsule Schema 全解析Dragon 胶囊数据模型的字段定义、约束与查询实践SpaceX API Capsule Schema 全解析Dragon 胶囊数据模型的字段定义、约束与查询实践 本文以 SpaceX API 仓库中 docs后端API设计SpaceX-API Crew 数据查询实战指南掌握 /v4/crew/query 端点与 MongoDB 分页检索SpaceX API Crew 数据查询实战指南掌握 /v4/crew/query 端点与 MongoDB 分页检索 导读 本文围绕 SpaceX API 开后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
