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），仅供参考