后端API設(shè)計【免費下載鏈接】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點擊查看免費下載本篇技術(shù)指南圍繞 SpaceX-API 開源倉庫rSpaceX-API中v4/landpads資源下的核心端點GET /v4/landpads展開講解如何一次性獲取 SpaceX 全部著陸坪Landing Pad的完整數(shù)據(jù)。文中不僅給出可立即復(fù)制的請求方式與字段含義表還會深入倉庫源碼路由實現(xiàn)、Mongoose 模型、定時任務(wù)揭示該端點的數(shù)據(jù)模型、Redis 緩存與統(tǒng)計字段的維護機制讀完即可將該接口用于發(fā)射信息展示、著陸統(tǒng)計等實戰(zhàn)場景。接口概覽端點、方法與認證GET /v4/landpads是 v4 版本 API 中用于獲取全部著陸坪數(shù)據(jù)列表的端點。它的調(diào)用信息非常簡潔項目值MethodGETURLhttps://api.spacexdata.com/v4/landpadsAuth requiredFalse公開只讀接口無需攜帶spacex-key請求頭Success Code200 OK該端點返回一個 JSON數(shù)組數(shù)組中的每個元素對應(yīng)一個著陸坪的完整對象默認按數(shù)據(jù)庫存儲順序返回全量數(shù)據(jù)。在倉庫源碼中該路由定義于 routes/landpads/v4/index.js其核心實現(xiàn)只有寥寥數(shù)行// Get all landpads router.get(/, cache(300), async (ctx) { try { const result await Landpad.find({}); ctx.status 200; ctx.body result; } catch (error) { ctx.throw(400, error.message); } });可以看到路由通過 Mongoose 模型的find({})查詢?nèi)沓晒笠?00狀態(tài)碼直接返回文檔數(shù)組若查詢過程拋錯則返回400 Bad Request及錯誤信息。同時該路由掛在cache(300)中間件之下表示響應(yīng)會被 Redis 緩存 300 秒詳見下文“緩存機制”小節(jié)。另外從路由前綴/(v4|latest)/landpads可以看出該資源同時支持/v4與/latest兩種版本別名。響應(yīng)示例一個真實的著陸坪對象請求成功后200 OK接口返回的數(shù)組元素如下所示節(jié)選自 docs/landpads/v4/all.md 中的官方示例[ { name: LZ-2, full_name: Landing Zone 2, status: active, type: RTLS, locality: Cape Canaveral, region: Florida, latitude: 28.485833, longitude: -80.544444, landing_attempts: 3, landing_successes: 3, wikipedia: https://en.wikipedia.org/wiki/Landing_Zones_1_and_2, details: SpaceXs first east coast landing pad is Landing Zone 1, where the historic first Falcon 9 landing occurred in December 2015. LC-13 was originally used as a launch pad for early Atlas missiles and rockets from Lockheed Martin. LC-1 was later expanded to include Landing Zone 2 for side booster RTLS Falcon Heavy missions, and it was first used in February 2018 for that purpose., launches: [ 5eb87d13ffd86e000604b360, 5eb87d2dffd86e000604b376, 5eb87d35ffd86e000604b37a ], id: 5e9e3032383ecb90a834e7c8 }, ... ]響應(yīng)體是一個數(shù)組數(shù)組中每個對象代表一個著陸坪如示例中的 LZ-2 / Landing Zone 2末尾的...表示還有其他著陸坪對象。該接口無鑒權(quán)要求可被瀏覽器地址欄直接訪問是最簡單的快速體驗方式。響應(yīng)字段完整解析為準確理解每個字段的含義、類型與取值范圍可對照同目錄下的 Landing Pad Schema 文檔。其底層定義可在 models/landpads.js 中看到兩者完全一致唯一差異是模型中還額外包含images.large字段見下文。逐字段說明如下字段類型說明nameString著陸坪短名稱如LZ-2默認nullfull_nameString著陸坪全稱如Landing Zone 2默認nullstatusString著陸坪狀態(tài)必填枚舉值為active、inactive、unknown、retired、lost、under constructiontypeString著陸類型如示例中的RTLSReturn To Launch Site返回發(fā)射場回收默認nulllocalityString所在地點城市/地區(qū)名如Cape CanaveralregionString所在大區(qū)/州如FloridalatitudeNumber緯度WGS-84如28.485833longitudeNumber經(jīng)度WGS-84如-80.544444landing_attemptsNumber該著陸坪累計著陸嘗試次數(shù)默認0landing_successesNumber該著陸坪累計成功著陸次數(shù)默認0wikipediaString維基百科詞條鏈接可進一步了解歷史detailsString著陸坪詳細歷史描述launchesArrayUUID關(guān)聯(lián)的發(fā)射 ID 列表每個 ID 對應(yīng)launches資源中的一次發(fā)射idString著陸坪唯一標識MongoDB ObjectId 字符串形式源碼中的補充字段images在 models/landpads.js 中模型還定義了一個文檔中未出現(xiàn)的字段images.large字符串數(shù)組用于存放著陸坪大圖 URL。這說明在線文檔描述的字段是數(shù)據(jù)主集而實際模型允許的字段范圍更寬若在后續(xù)查詢中使用select明確指定該字段仍可能取到圖片數(shù)據(jù)。字段約束的源碼級驗證status枚舉校驗?zāi)Ｐ屯ㄟ^ Mongoose 的enum約束限定取值寫入非法值如closed會被拒絕。該約束同樣作用于管理端創(chuàng)建/更新接口見下文。launches引用關(guān)系模型中以mongoose.ObjectId數(shù)組存儲并ref: Launch指向發(fā)射集合因此可以通過/query接口的populate選項把 UUID 直接替換為完整的發(fā)射對象詳見 查詢與分頁指南。文本索引模型在name、full_name、details三個字段上建立了 text 索引models/landpads.js意味著/query接口支持 MongoDB 的$text全文檢索如$search: cape對所有已索引的字符串字段進行搜索。源碼級實現(xiàn)從請求到響應(yīng)的完整鏈路結(jié)合倉庫代碼一次GET /v4/landpads請求的處理鏈路為路由匹配請求進入 routes/landpads/v4/index.js 的 Koa Router前綴/(v4|latest)/landpads命中/路徑緩存判斷cache(300)中間件先檢查 Redis 中是否已有相同請求的緩存鍵由方法、URL、請求體經(jīng) BLAKE3 哈希生成命中則直接返回200與緩存體并打上spacex-api-cache: HIT響應(yīng)頭未命中則繼續(xù)向下執(zhí)行middleware/cache.js數(shù)據(jù)查詢Landpad.find({})從 MongoDB 中取出全部著陸坪文檔響應(yīng)回寫ctx.body result序列化為 JSON 數(shù)組返回狀態(tài)碼200Redis 在響應(yīng)后寫入緩存并設(shè)置 300 秒過期同時通過Cache-Control: max-age300響應(yīng)頭告知客戶端可復(fù)用緩存僅在生產(chǎn)環(huán)境NODE_ENVproduction時啟用 Redis 緩存見 middleware/cache.js。模型層的完整定義見 models/landpads.js它額外掛載了mongoosePaginate分頁支持與mongoose-id返回id字段兩個插件這也是GET /v4/landpads返回的每個對象都帶id而非_id的原因。緩存機制與響應(yīng)頭cache(300)意味著接口響應(yīng)默認被緩存300 秒5 分鐘。從 middleware/cache.js 可以看出成功響應(yīng)會附帶以下響應(yīng)頭spacex-api-cache取值為HIT命中緩存或MISS未命中本次回源spacex-api-cache-online表示 Redis 緩存服務(wù)是否在線Cache-Control: max-age300指示下游客戶端/代理可緩存 5 分鐘。因此在實際調(diào)用中即使高頻輪詢該端點也可以獲得穩(wěn)定的響應(yīng)速度同時應(yīng)注意數(shù)據(jù)最長可能有 5 分鐘的延遲——需要實時數(shù)據(jù)的場景建議使用下文/query接口并配合pagination: false。著陸坪資源族的其他端點GET /v4/landpads只是該資源族的一個端點倉庫同目錄下還提供了另外三種能力便于精確獲取數(shù)據(jù)獲取單個著陸坪MethodGETURLhttps://api.spacexdata.com/v4/landpads/:idURL 參數(shù)id[string]著陸坪的 ID如5e9e3032383ecb90a834e7c8Success200 OK返回單個著陸坪對象結(jié)構(gòu)與數(shù)組元素一致Error404 NOT FOUNDID 不存在時返回Not Found詳見 one.md該路由在源碼中的實現(xiàn)為Landpad.findById(ctx.params.id)查不到時ctx.throw(404)routes/landpads/v4/index.js。自定義查詢與分頁MethodPOSTURLhttps://api.spacexdata.com/v4/landpads/queryBody{ query: {}, options: {} }其中query接受任意合法的 MongoDBfind()查詢options支持select、sort、offset、page、limit、pagination、populate等分頁與投影選項docs/landpads/v4/query.md例如只取東海岸Florida地區(qū)、狀態(tài)為 active 的著陸坪{ query: { region: Florida, status: active }, options: { select: { name: 1, full_name: 1, latitude: 1, longitude: 1 }, sort: { name: asc }, limit: 10 } }完整的查詢語法、分頁參數(shù)與populate用法可參考 docs/queries.md若需將launches數(shù)組中的 UUID 展開為發(fā)射對象可在options.populate中指定[launches]。查詢失敗如字段名拼寫錯誤時返回400 Bad Request響應(yīng)體中會攜帶 Mongoose 錯誤信息與修正建議。數(shù)據(jù)從哪來統(tǒng)計字段的定時維護機制landing_attempts與landing_successes兩個統(tǒng)計字段并非寫死在文檔里而是由倉庫中的定時任務(wù)維護。在 jobs/worker.js 中l(wèi)andpads任務(wù)以 Cron 表達式*/10 * * * *配置即每 10 分鐘運行一次。該任務(wù)的核心邏輯位于 jobs/landpads.js通過POST /v4/landpads/queryoptions.pagination: false拉取全部著陸坪對每個著陸坪分別向POST /v4/launches/query發(fā)起兩次查詢統(tǒng)計嘗試次數(shù)查詢cores數(shù)組中存在landpad等于當前著陸坪 ID 且landing_attempt: true的未發(fā)射記錄數(shù)統(tǒng)計成功次數(shù)在上述條件基礎(chǔ)上額外要求landing_success: true并同時限定upcoming: false、success: true用兩次查詢返回的totalDocs通過PATCH /v4/landpads/:id攜帶spacex-key認證頭回寫landing_attempts與landing_successes全部更新完成后輸出日志Landpads updated若配置了LANDPADS_HEALTHCHECK環(huán)境變量還會上報健康檢查探活。這解釋了為什么GET /v4/landpads返回的統(tǒng)計數(shù)據(jù)會自動保持更新——上游任務(wù)每 10 分鐘基于發(fā)射數(shù)據(jù)重新聚合一次著陸記錄。實戰(zhàn)演練快速調(diào)用與結(jié)果驗證使用 curl 獲取全部著陸坪curl -s https://api.spacexdata.com/v4/landpads | jq .使用 curl 獲取單個著陸坪curl -s https://api.spacexdata.com/v4/landpads/5e9e3032383ecb90a834e7c8 | jq { name, full_name, status, landing_attempts, landing_successes }使用 Python 請求庫獲取并統(tǒng)計import requests resp requests.get(https://api.spacexdata.com/v4/landpads) landpads resp.json() print(f共返回 {len(landpads)} 個著陸坪) for pad in landpads: print(f{pad[name]} | {pad[status]} | 嘗試 {pad[landing_attempts]} / 成功 {pad[landing_successes]})驗證要點無鑒權(quán)時即可訪問status_code應(yīng)為200響應(yīng)頭中可觀察Cache-Control: max-age300數(shù)組長度與/query返回的totalDocs一致在 query.md 的示例中為7個著陸坪可作為交叉校驗。相關(guān)文檔與進一步閱讀Get all landing pads本文檔Get one landing padQuery landing padsLanding Pad SchemaQuery Pagination Guide源碼模型 models/landpads.js、路由 routes/landpads/v4/index.js、定時任務(wù) jobs/landpads.js 與任務(wù)調(diào)度 jobs/worker.js贊分享后端API設(shè)計【免費下載鏈接】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點擊查看免費下載相關(guān)推薦SpaceX-API 陸上著陸場查詢接口詳解/v4/landpads/query 的查詢語法、分頁與數(shù)據(jù)關(guān)聯(lián)SpaceX API 陸上著陸場查詢接口詳解/v4/landpads/query 的查詢語法、分頁與數(shù)據(jù)關(guān)聯(lián) 本篇文章圍繞開源項目 SpaceX API 中后端API設(shè)計SpaceX-API v4 單個著陸場查詢接口實戰(zhàn)GET /v4/landpads/:id 返回結(jié)構(gòu)、字段語義與源碼實現(xiàn)解析SpaceX API v4 單個著陸場查詢接口實戰(zhàn)GET /v4/landpads/:id 返回結(jié)構(gòu)、字段語義與源碼實現(xiàn)解析 本文以 SpaceX API 開后端API設(shè)計SpaceX-API v4 Rockets 接口完整指南獲取全部火箭數(shù)據(jù)GET /v4/rocketsSpaceX API v4 Rockets 接口完整指南獲取全部火箭數(shù)據(jù)GET /v4/rockets 本文基于 SpaceX API https://l后端API設(shè)計創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考