Apache DolphinScheduler RESTful API 设计规范与实践指南【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinschedulerApache DolphinScheduler 将统一、规范的 API 设计视为项目设计的基石其对外接口全面遵循 RESTful 标准。本文以 DolphinScheduler 的 API 实现为例系统讲解其 URI 资源设计、HTTP 方法语义、参数规范与 base URL 约定并结合 dolphinscheduler-api 模块的真实控制器源码帮助读者掌握如何依据该规范设计、实现与评审一套可扩展的 RESTful 接口。读完本文你将能直接套用这套标准编写符合项目规范的新 API并理解 DolphinScheduler 现有接口背后的设计意图。一、规范定位为什么 DolphinScheduler 选择 RESTfulDolphinScheduler 的设计文档docs/docs/en/contribute/api-standard.md明确表述标准化且统一的 API 是项目设计的基石。DolphinScheduler 的 API 遵循 RESTful 标准——这是当前最流行的互联网软件架构风格具有结构清晰、符合标准、易于理解和易于扩展的特点。REST 即 Representational State Transfer表述性状态转移其 URI 设计建立在**资源Resource**的概念之上资源对应网络上的一个实体一段文本、一张图片、一项服务每个资源对应一个 URI。DolphinScheduler 的所有对外接口正是围绕告警组、项目、工作流定义、任务实例等资源展开。二、URI 设计规范URI 设计是 RESTful 接口的第一步。DolphinScheduler 规范将资源分为三类通过名词的复数/单数形式与ID 占位符来精确表达资源层级资源类型表示方式示例一类资源集合使用复数形式task-instances、groups单个资源使用单数形式或通过 ID 表示group、groups/{groupId}子资源集合某资源下的资源/instances/{instanceId}/tasks单个子资源子资源下的具体资源/instances/{instanceId}/tasks/{taskId}这一设计在源码中有着清晰映射。以告警组资源为例AlertGroupController.java 通过类级注解RequestMapping(/alert-groups)声明了复数形式的资源路径符合一类资源用复数的约定RestController RequestMapping(/alert-groups) public class AlertGroupController extends BaseController {而项目级资源则以项目编码 子资源的多级 URI 呈现例如 ProcessInstanceController.java 中的RequestMapping(/projects/{projectCode}/process-instances)以及 ExecutorController.java 中的RequestMapping(projects/{projectCode}/executors)都是子资源设计的直接落地——先定位项目{projectCode}再定位该项目下的流程实例或执行器。三、Method 设计规范通过 URI 定位资源后需要用 **HTTP 方法Method**或在路径后缀中声明动作来表达对资源的具体操作。DolphinScheduler 规范给出如下五类方法语义与若干动作后缀约定。① 查询 —— GET使用 URI 定位资源用 GET 表示查询操作查询一类资源分页URI 为集合形式表示分页查询该类资源。例如分页查询告警组Method: GET /dolphinscheduler/alert-groups源码中对应 AlertGroupController.java 的GetMapping()方法listPaging它接收searchVal、pageNo、pageSize参数并返回ResultPageInfoAlertGroup。查询单个资源URI 为单资源形式表示查询指定资源。例如查询指定告警组Method: GET /dolphinscheduler/alter-groups/{id}查询子资源基于 URI 表达子资源查询Method: GET /dolphinscheduler/projects/{projectId}/tasks源码中 ProcessInstanceController.java 的GetMapping(value /{id}/tasks)即为流程实例下的任务这一子资源查询。关键约定上述示例均为分页查询。若需查询全部数据必须在 URI 后追加/list以区分严禁将同一 API 同时混用为分页查询与全量查询。例如Method: GET /dolphinscheduler/alert-groups/list这一约定在源码中得到严格执行AlertGroupController的GetMapping(value /list)第 107 行返回ListAlertGroup全量列表而GetMapping()第 131 行返回PageInfoAlertGroup分页结果两个接口路径明确区分。全仓库范围内AlertPluginInstanceController.java、DataSourceController.java、ProjectController.java 等控制器均遵循/list后缀约定。② 创建 —— POST使用 URI 定位资源用 POST 表示创建并在响应中向调用方返回创建的 id。例如创建告警组Method: POST /dolphinscheduler/alter-groups创建子资源方式相同Method: POST /dolphinscheduler/alter-groups/{alterGroupId}/tasks源码中AlertGroupController.createAlertGroup第 88-98 行使用PostMapping()接收groupName、description、alertInstanceIds参数返回ResultAlertGroup其中包含新建的告警组实体含其 id符合创建后返回 id的规范。同时ResponseStatus(HttpStatus.CREATED)表明创建类接口使用 201 状态码。③ 修改 —— PUT使用 URI 定位资源用 PUT 表示整体修改。例如修改一个告警组Method: PUT /dolphinscheduler/alter-groups/{alterGroupId}源码中 AlertGroupController.java 的updateAlertGroupById使用PutMapping(value /{id})通过PathVariable(id)定位资源并携带完整的新值groupName、description、alertInstanceIds执行更新。④ 删除 —— DELETE使用 URI 定位资源用 DELETE 表示删除。例如删除一个告警组Method: DELETE /dolphinscheduler/alter-groups/{alterGroupId}源码中AlertGroupController.deleteAlertGroupById第 207-215 行使用DeleteMapping(value /{id})实现单条删除。批量删除有专门约定批量删除 id 数组必须使用 POST而非 DELETE。规范给出的理由是DELETE 请求的 body 没有语义含义且部分网关、代理和防火墙收到 DELETE 请求后可能直接剥离请求体导致批量数据丢失。因此批量删除使用如下形式Method: POST /dolphinscheduler/alter-groups/batch-delete这一约定在源码中多次落地例如 ProcessDefinitionController.java 的PostMapping(value /batch-delete)批量删除工作流定义通过codes参数传入 id 列表、ProcessInstanceController.java 与 ProjectParameterController.java 的批量删除接口均采用 POST /batch-delete后缀。⑤ 部分修改 —— PATCH使用 URI 定位资源用 PATCH 表示部分修改Method: PATCH /dolphinscheduler/alter-groups/{alterGroupId}规范将 PATCH 定义为对资源的局部字段更新与 PUT 的整体替换语义相区分。需要说明的是从当前仓库 dolphinscheduler-api 控制器目录 的源码看现有接口以 PUT 承担更新职责未发现PatchMapping的实际落地实现开发者可在确有仅更新部分字段需求时按此约定新增 PATCH 接口。⑥ 其他操作动作除增删改查外对于动作型操作规范要求通过 URL 定位资源后在路径末尾追加动作来表达例如/dolphinscheduler/alert-groups/verify-name /dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt这类资源 动作后缀的模式在源码中非常普遍名称校验AlertGroupController.java 的GetMapping(value /verify-name)校验告警组名是否已存在ProcessDefinitionController.java 同样提供/verify-name用于校验工作流定义名称。视图型动作ProcessInstanceController.java 的GetMapping(value /{id}/view-gantt)查看甘特图、/{id}/view-variables第 345 行查看变量。执行型动作ExecutorController.java 中大量使用动作后缀如start-process-instance第 136 行、batch-start-process-instance第 232 行、/execute第 320 行、/execute-task第 487 行等用于表达启动工作流执行任务这类非 CRUD 操作。四、参数设计规范DolphinScheduler 规范明确了两类参数——请求参数request parameter与路径参数path parameter且参数命名必须使用小驼峰small camelCase。路径参数通过PathVariable注入如{id}、{projectCode}请求参数通过RequestParam接收如groupName、alertInstanceIds、searchVal、pageNo、pageSize。分页参数有两条明确的容错规则前端侧当用户输入的参数小于 1 时前端应自动将其转为 1表示请求第一页后端侧当后端发现用户输入的参数大于总页数时应直接返回最后一页而不是报错或返回空集。后端的参数校验逻辑集中在 BaseController.java 的checkPageParams方法中当pageNo 0或pageSize 0时抛出ServiceException对应REQUEST_PARAMS_NOT_VALID_ERROR状态码以此保证分页参数合法public void checkPageParams(int pageNo, int pageSize) throws ServiceException { if (pageNo 0) { throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.PAGE_NUMBER); } if (pageSize 0) { throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.PAGE_SIZE); } }listPaging等方法在进入业务逻辑前均会调用checkPageParams(pageNo, pageSize)做前置校验这为小于 1 自动归一的前端约定提供了后端兜底。此外规范中的分页参数也统一命名为pageNo/pageSize见 AlertGroupController.java 的 OpenAPI 注解示例example 1、example 20并支持searchVal作为可选的关键字过滤参数。五、base URL 约定所有 API 的 URI 必须以/project_name作为基础路径base path用于标识这些 API 归属于该项目即统一前缀/dolphinscheduler该前缀在服务端配置中落地于 dolphinscheduler-api/src/main/resources/application.yaml服务监听12345端口并通过server.servlet.context-path: /dolphinscheduler/为所有接口统一挂载 base path。因此前端实际访问地址形如http://host:12345/dolphinscheduler/alert-groups控制器中的RequestMapping只需声明/alert-groups等资源路径二者拼接即得到完整 URI。配置中同时启用了响应压缩server.compression.enabled: true与 1024MB 的上传大小限制spring.servlet.multipart为 API 的传输效率与文件类接口提供了运行环境保障。六、统一响应结构与审计设计虽然规范文档未展开响应格式细节但从源码可以观察到与规范配套的工程化约定这里作为补充说明统一响应体Result.java 定义了code / msg / data三段式响应结构ResultT所有接口通过Result.success(...)或Result.error(...)返回统一格式便于前端与 SDK 统一解析状态码枚举api/enums/Status 中以枚举集中管理业务状态码与文案如CREATE_ALERT_GROUP_ERROR、ALERT_GROUP_EXIST并通过ApiException(...)注解声明接口的异常映射审计日志创建、更新、删除等写操作通过OperatorLog(auditType AuditType.XXX)注解如ALARM_GROUP_CREATE、PROCESS_BATCH_DELETE记录操作审计与dolphinscheduler-api中的审计模块配套方便追踪 API 的变更历史OpenAPI 文档所有接口使用Operation、Parameter、Schema等注解见 AlertGroupController.java描述接口语义、必填项与示例值可直接生成 OpenAPI 文档保证规范可查、接口可文档化。七、给接口开发者的落地清单综合规范文档与源码实践在 DolphinScheduler 中新增一个资源模块的 RESTful API 时建议按以下清单自检URI集合资源用复数如alert-groups单资源追加/{id}子资源遵循/{parentId}/children层级方法语义查询用 GET、创建用 POST返回 id、整体修改用 PUT、删除用 DELETE、部分修改用 PATCH动作型操作追加路径后缀如verify-name、start-process-instance分页与全量分页查询不写后缀全量查询统一追加/list二者不可混用批量删除一律使用POST /xxx/batch-delete禁止用 DELETE 携带请求体参数路径参数与请求参数均使用小驼峰命名分页参数统一为pageNo/pageSize并调用BaseController.checkPageParams校验合法性base URL无需在控制器中重复声明/dolphinscheduler前缀该前缀由application.yaml中的context-path统一提供响应与文档返回ResultT统一结构声明Operation/Parameter注解写操作添加OperatorLog审计注解。遵循上述规范新接口将与 DolphinScheduler 现有数百个 API 保持风格一致既利于前端统一调用也便于后续扩展与社区协作维护。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
相关推荐
数字1.27的技术解析与应用场景
1. 项目概述"1.27"这个看似简单的数字组合，实际上在多个专业领域都具有特殊含义。作为从业多年的技术博主，我发现在不同场景下遇到这个数字时，往往意味着需要处理一些特定的技术问题或业务需求。今天我们就来全面剖析这个数字背后可… · 2026/9/23 22:22:05
FaceNet人脸考勤系统：从特征提取到SQLite落库的完整实现
简介：本资源是一套面向计算机专业本科生的深度学习实战项目，聚焦人脸识别考勤系统开发，适用于毕业设计、课程设计及期末大作业场景。项目基于FaceNet深度学习算法实现人脸特征提取与比对，完整覆盖人脸录入、实时识别、考勤统计、班… · 2026/9/23 22:22:04
Dopamine 强化学习框架实验指南：从智能体训练、gin 配置到检查点与自定义扩展
机器学习深度学习 【免费下载链接】dopamine Dopamine is a research framework for fast prototyping of reinforcement learning algorithms. 项目地址： https://gitcode.com/gh_mirrors/do/dopamine 点击查看 免费下载 Dopamine 是面向强化学习（RL&… · 2026/9/23 22:21:58
25岁转行学AI来得及吗？长沙本地转行路径与参考
摘要本文针对 25 岁左右职场人群转行 AI 的普遍困惑，明确给出转行可行性结论，分析该年龄段转行的核心优势，结合长沙马栏山视频文创园、麓谷科技园等本地产业场景，梳理内容创作、技术开发两类适配的 AI 方向，给出阶段式… · 2026/9/23 22:59:59
uv工具：Python开发者的效率革命与实战指南
1. 初识uv：Python开发者的效率革命第一次听说uv这个工具时，我正在为一个跨平台Python项目焦头烂额。当时需要同时管理多个虚拟环境，处理不同版本的依赖冲突，还要确保团队成员的开发环境一致。传统的venvpip组合虽然能用࿰… · 2026/9/23 22:59:53
IPFS+以太坊+属性基加密：构建可审计的安全数据共享方案
简介：基于星际文件系统、以太坊与属性加密技术的区块链安全数据共享系统设计源码，是一套面向区块链研发人员与高安全数据管理场景的完整工程实现。该项目将去中心化存储、以太坊智能合约与细粒度访问控制相结合，解决数据共享中的安全与权限管… · 2026/9/23 22:59:46
插件系统架构设计与开发实践指南
1. 插件开发架构的本质思考插件系统的核心价值在于扩展性。一个优秀的插件架构应该像乐高积木一样，允许第三方开发者在不修改主程序代码的前提下，为系统添加新功能。我在参与多个大型软件系统的插件开发时，发现成熟的插件架构通常包含以下关键… · 2026/9/23 22:59:46
大圆航线与测地线：Haversine和Vincenty公式详解
打开航旅App看北京飞洛杉矶的航班，航线不是一条穿过太平洋的直线，而是向北绕一圈，经过俄罗斯远东、白令海，最后再沿北美西海岸南下。第一次看到的人多半以为飞机在绕远，其实这才是真正的近路。地球是圆的，地… · 2026/9/23 22:59:40
小波分解原理与电机振动去噪实战指南
简介：本资源是一份面向信号处理初学者与工程实践者的MATLAB小波分解入门脚本，聚焦含噪信号的多尺度分析与去噪实现。内容涵盖小波基选择（如Daubechies系列）、小波系数计算、阈值去噪策略及逆变换信号重构等核心流程，适… · 2026/9/23 22:59:28
3招搞定手机怎么下载微信面试难题实战项目解析
3招搞定手机怎么下载微信面试难题实战项目解析 面试被问“手机怎么下载微信”背后的原理，90%的人答不上来。别笑，这看似弱智的问题，实则是考察你对移动应用分发机制、安全校验及网络协议理解的试金石。我带过不少校招新人，他们背了八股文，却连一个A… · 2026/9/23 0:00:03
你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型
你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 面试被问“高并发下如何保证消息不丢失”，你张口就是“用Redis”，结果面试官追问“如果Redis宕机了怎么办”，你瞬间卡壳。这种场景太常见了，很多新手在背八股文时，只记住了技术名词… · 2026/9/23 0:00:29
Win7无线热点配置工具源码解析：解决API失效的3个实战技巧
Win7无线热点配置工具源码解析：解决API失效的3个实战技巧 Win7无线热点配置工具在Win10/11上跑不动？不是你的问题，是版本升级后 API 全变了。很多老项目里的 netsh wlan… · 2026/9/23 0:00:36