Cal.diy API v2完全參考手冊用NestJS構(gòu)建的RESTful接口詳解【免費下載鏈接】cal.diyScheduling infrastructure for absolutely everyone.項目地址: https://gitcode.com/GitHub_Trending/ca/cal.diyCal.diyCal.com 開源版API v2 是一套用NestJS構(gòu)建的現(xiàn)代化 RESTful 接口提供預(yù)約Bookings、日程類型Event Types、日歷Calendars、空閑時段Slots等核心功能的完整 API 能力。本手冊幫你快速理解它的架構(gòu)分層、核心端點、版本策略與本地運行方法是新手上手 Cal.diy API v2 的一站式指南。Cal.diy API v2 是什么為什么選擇 NestJSAPI v2 是 Cal.diy 的新一代平臺 API獨立于 Web 應(yīng)用部署代碼位于 apps/api/v2/ 目錄。它選用 NestJS 框架帶來了三大優(yōu)勢模塊化架構(gòu)每個業(yè)務(wù)域預(yù)約、日歷、認證都是獨立模塊職責(zé)清晰內(nèi)建 Swagger開發(fā)環(huán)境自動生成 OpenAPI 文檔接口即文檔生態(tài)成熟限流、中間件、全局攔截器都有現(xiàn)成方案服務(wù)入口見 main.ts它同時支持本地常駐進程和Vercel Serverless 模式雙形態(tài)運行。項目結(jié)構(gòu)速覽RESTful 端點藏在哪里打開 app.module.ts 就能看懂整體分層——這是 NestJS 的根模塊負責(zé)裝配全局能力組件作用EndpointsModule聚合所有業(yè)務(wù)端點模塊AuthModule/JwtModule認證與令牌簽發(fā)PrismaModule/RedisModule數(shù)據(jù)庫與緩存訪問ThrottlerModule基于 Redis 的接口限流端點模塊又分為兩層業(yè)務(wù)端點endpoints.module.ts 掛載 Webhooks、OAuth2、用戶、Stripe 計費、時區(qū)等模塊平臺端點platform-endpoints-module.ts 掛載 Bookings、Event Types、Calendars、Schedules、Slots、Me 等對外核心 API核心 RESTful 端點清單以下按業(yè)務(wù)域整理了最常用的端點以 2024-08-13 版本的 Bookings 為例業(yè)務(wù)域典型端點方法預(yù)約 Bookings/bookings創(chuàng)建/查詢預(yù)約POST / GET預(yù)約 Bookings/:bookingUid/cancel取消預(yù)約POST預(yù)約 Bookings/:bookingUid/reschedule改期POST預(yù)約 Bookings/:bookingUid/reassign重新分配POST參與者 Attendees/bookings/attendees管理參與者GET / POST / DELETE日程類型/event-types增刪改查POST / PATCH / DELETE日歷/calendars/busy-times查詢忙碌時段GET日歷/:calendar/connect連接外部日歷GET空閑時段/slots查詢可約時段GET當(dāng)前用戶/me獲取自身信息GET預(yù)約端點源碼bookings.controller.ts日程類型端點event-types.controller.ts日歷端點calendars.controller.ts版本策略用日期命名的接口版本Cal.diy API v2 采用了日期化版本管理——同一個業(yè)務(wù)域可以有多個并列版本互不干擾bookings/2024-04-15與bookings/2024-08-13新版新增了錄像、轉(zhuǎn)寫、改派等端點event-types/2024_04_15與event-types_2024_06_14slots/2024-04-15與slots/2024-09-04schedules/2024_04_15與schedules/2024_06_11這種策略保證舊客戶端永遠不會被破壞性變更影響升級時只需切換到新版本路由。認證方式API Key 與 OAuth2認證模塊位于 apps/api/v2/src/modules/auth/ 與 apps/api/v2/src/modules/tokens/支持兩種主流方式API Key服務(wù)端到服務(wù)端的簡單集成在請求頭攜帶密鑰即可OAuth2面向第三方應(yīng)用的完整授權(quán)流程令牌端點為POST /v2/auth/oauth2/token支持標(biāo)準表單編碼請求體見 app.module.ts 中的路由配置守衛(wèi)Guard設(shè)計有明確約定拒絕時必須拋出帶說明的異常且只緩存通過的結(jié)果避免用戶修復(fù)權(quán)限后仍被攔截——約定全文見 README.md。Swagger 文檔接口自帶在線手冊開發(fā)模式下Cal.diy API v2 會自動生成 Swagger UI文檔生成邏輯generate-swagger.ts訪問http://localhost:4000/docs即可打開交互式文檔端點會按標(biāo)簽智能排序Platform平臺接口在前、Orgs組織接口在后同時導(dǎo)出靜態(tài) OpenAPI 規(guī)范openapi.json對新手來說這就是最好的活文檔——可以直接在頁面上試調(diào)接口。限流與請求追蹤生產(chǎn)級細節(jié)根模塊中全局裝配了兩個實用組件CustomThrottlerGuard基于 Redis 的全局限流器防止接口被濫用app.module.tsRequestIdMiddleware為每個請求注入唯一 ID方便日志追蹤與問題定位本地快速上手5步跑通 Cal.diy API v2按照 apps/api/v2/README.md 的步驟操作安裝依賴項目根目錄執(zhí)行yarn install啟動 Docker確保數(shù)據(jù)庫等依賴容器運行啟動 mailhogcd packages/emails yarn dx用于本地收郵件配置環(huán)境變量復(fù)制.env.example為.env并保證NEXTAUTH_SECRET在根目錄與 API v2 中一致啟動服務(wù)yarn dev然后訪問/docs查看 Swagger如需不依賴 Docker 運行可使用yarn dev:no-docker跑測試則用yarn test單測或yarn test:e2e端到端?？偨Y(jié)Cal.diy API v2 用 NestJS 的模塊化能力把預(yù)約系統(tǒng)的核心能力封裝為一套版本化、帶文檔、有限流的 RESTful 接口。無論你是想接入第三方工具、構(gòu)建企業(yè)排班系統(tǒng)還是學(xué)習(xí)后端 API 架構(gòu)設(shè)計從 apps/api/v2/src/platform/ 入手都是最佳路徑。【免費下載鏈接】cal.diyScheduling infrastructure for absolutely everyone.項目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考