Cal.diy API v2完全参考手册用NestJS构建的RESTful接口详解【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diyCal.diyCal.com 开源版API v2 是一套用NestJS构建的现代化 RESTful 接口提供预约Bookings、日程类型Event Types、日历Calendars、空闲时段Slots等核心功能的完整 API 能力。本手册帮你快速理解它的架构分层、核心端点、版本策略与本地运行方法是新手上手 Cal.diy API v2 的一站式指南。Cal.diy API v2 是什么为什么选择 NestJSAPI v2 是 Cal.diy 的新一代平台 API独立于 Web 应用部署代码位于 apps/api/v2/ 目录。它选用 NestJS 框架带来了三大优势模块化架构每个业务域预约、日历、认证都是独立模块职责清晰内建 Swagger开发环境自动生成 OpenAPI 文档接口即文档生态成熟限流、中间件、全局拦截器都有现成方案服务入口见 main.ts它同时支持本地常驻进程和Vercel Serverless 模式双形态运行。项目结构速览RESTful 端点藏在哪里打开 app.module.ts 就能看懂整体分层——这是 NestJS 的根模块负责装配全局能力组件作用EndpointsModule聚合所有业务端点模块AuthModule/JwtModule认证与令牌签发PrismaModule/RedisModule数据库与缓存访问ThrottlerModule基于 Redis 的接口限流端点模块又分为两层业务端点endpoints.module.ts 挂载 Webhooks、OAuth2、用户、Stripe 计费、时区等模块平台端点platform-endpoints-module.ts 挂载 Bookings、Event Types、Calendars、Schedules、Slots、Me 等对外核心 API核心 RESTful 端点清单以下按业务域整理了最常用的端点以 2024-08-13 版本的 Bookings 为例业务域典型端点方法预约 Bookings/bookings创建/查询预约POST / GET预约 Bookings/:bookingUid/cancel取消预约POST预约 Bookings/:bookingUid/reschedule改期POST预约 Bookings/:bookingUid/reassign重新分配POST参与者 Attendees/bookings/attendees管理参与者GET / POST / DELETE日程类型/event-types增删改查POST / PATCH / DELETE日历/calendars/busy-times查询忙碌时段GET日历/:calendar/connect连接外部日历GET空闲时段/slots查询可约时段GET当前用户/me获取自身信息GET预约端点源码bookings.controller.ts日程类型端点event-types.controller.ts日历端点calendars.controller.ts版本策略用日期命名的接口版本Cal.diy API v2 采用了日期化版本管理——同一个业务域可以有多个并列版本互不干扰bookings/2024-04-15与bookings/2024-08-13新版新增了录像、转写、改派等端点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服务端到服务端的简单集成在请求头携带密钥即可OAuth2面向第三方应用的完整授权流程令牌端点为POST /v2/auth/oauth2/token支持标准表单编码请求体见 app.module.ts 中的路由配置守卫Guard设计有明确约定拒绝时必须抛出带说明的异常且只缓存通过的结果避免用户修复权限后仍被拦截——约定全文见 README.md。Swagger 文档接口自带在线手册开发模式下Cal.diy API v2 会自动生成 Swagger UI文档生成逻辑generate-swagger.ts访问http://localhost:4000/docs即可打开交互式文档端点会按标签智能排序Platform平台接口在前、Orgs组织接口在后同时导出静态 OpenAPI 规范openapi.json对新手来说这就是最好的活文档——可以直接在页面上试调接口。限流与请求追踪生产级细节根模块中全局装配了两个实用组件CustomThrottlerGuard基于 Redis 的全局限流器防止接口被滥用app.module.tsRequestIdMiddleware为每个请求注入唯一 ID方便日志追踪与问题定位本地快速上手5步跑通 Cal.diy API v2按照 apps/api/v2/README.md 的步骤操作安装依赖项目根目录执行yarn install启动 Docker确保数据库等依赖容器运行启动 mailhogcd packages/emails yarn dx用于本地收邮件配置环境变量复制.env.example为.env并保证NEXTAUTH_SECRET在根目录与 API v2 中一致启动服务yarn dev然后访问/docs查看 Swagger如需不依赖 Docker 运行可使用yarn dev:no-docker跑测试则用yarn test单测或yarn test:e2e端到端。总结Cal.diy API v2 用 NestJS 的模块化能力把预约系统的核心能力封装为一套版本化、带文档、有限流的 RESTful 接口。无论你是想接入第三方工具、构建企业排班系统还是学习后端 API 架构设计从 apps/api/v2/src/platform/ 入手都是最佳路径。【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考