【开源之夏】DataSphereStudio 集成 GitLab 课题 Proposal(已中选)
6-27 更新:已中选,虽然最多可以申请两个课题,但很遗憾 GLCC 规定学生只能参与第一个课题。导师对我很好,会继续关注 WeDataSphere 社区的!
此项目托付给了我的同学杨朋睿。
项目申请书
课题名称
申请人:夏天
导师:张旗 | burdezhang@webank.com
社区简介
DataSphere Studio(简称 DSS)是微众银行自研的一站式数据应用开发管理框架。
在统一的 UI 下,DataSphere Studio 以工作流式的图形化拖拽开发体验,将满足从数据交换、脱敏清洗、分析挖掘、质量检测、可视化展现、定时调度到数据输出应用等,数据应用开发全流程场景需求。
DSS 通过插拔式的集成框架设计,让用户可以根据需要,简单快速替换 DSS 已集成的各种功能组件,或新增功能组件。
题目简介
本课题旨在将 Gitlab 集成到 DataSphereStudio 中,以便于更好地管理用户在 DataSphereStudio 中开发的代码。
- 接入 Gitlab:我们将实现 DataSphereStudio 中的脚本接入 Gitlab 的功能,以便使用 DataSphereStudio 的开发人员可以更好地查看、修改和管理代码。这将有助于提升协作效率和代码质量。
- 版本管理和协作:通过集成 Gitlab,我们将实现 DataSphereStudio 中的代码版本管理和团队协作功能。学生们将有机会学习到 DataSphereStudio 集成三方应用的框架能力,同时能够掌握 Git 的基本概念,如代码提交、分支管理和代码合并,以及通过 Gitlab 进行代码审查和讨论。
编码任务
- 开发 dss-gitlab-appconn 模块,通过 DSS 的 AppConn 对接规范,将 GitLab 作为第三方系统,以插件的形式接入 DSS
- dss-gitlab-appconn 模块需要提供初始化 (git init)、克隆 (git clone)、拉取 (git pull)、推送 (git push)、获取 (git fetch)、提交 (git commit)、合并 (git merge)、变基 (git rebase) 等常见 Git 版本管理操作的 API 接口,并以有效的数据格式返回给前端
- 采用 CheckStyle 代码风格,为 dss-gitlab-appconn 模块的接口编写 JavaDoc 注释
- 在官方 DataSphereStudio-Doc 文档仓库中编写 dss-gitlab-appconn 模块的接口文档
- 测试接口功能并完善优化
如果上述任务完成进度快于预期,可以在活动结束前和后续社区贡献中继续完成其它任务。
架构分析
Apache Linkis 解耦架构
Apache Linkis 可以在大数据领域将应用与基础设施解耦,其解耦原理与另一开源项目 Apache EventMesh 类似,后者可以将应用中的业务逻辑与事件存储的强绑定解耦,两者都使用了 sink connector 和 source connector,以插件形式提供对不同基础设施的支持能力。
Apache Linkis 主要可以分为三大服务板块:
- CGS:计算治理服务组,Computation Governance Services. 完成计算任务和请求的提交、准备、执行、返回结果等主要步骤。
- PES:公共增强服务组,Public Enhancement Services. 主要提供了统一数据源、物料库、上下文等能力。
- MGS:微服务治理服务组,Microservice Governance Services. 该组服务主要复用了 SpringCloud 的能力。
DataSphereStudio 解决连通集成问题
- 串联统一,基于 DSS 工程、权限管理规范,图形化工作流式数据应用开发统一 Ul,AppConn 设计灵活串联不同应用工具系统;
- 打通孤岛,基于 Linkis 上下文、物料等公共服务能力;
- 快速复用,数据开发工具微模块快速复用能力。
DataSphereStudio 主要拥有以下引擎支持和框架:
dss-gitlab-appconn 模块分析
本地初始化
当用户访问 DataSphereStudio 的 Scriptis 工作空间时,将会调用 Apache Linkis 的 /filesystem/getUserRootPath
接口,对应 org.apache.linkis.filesystem.restful.api.FsRestfulApi 方法,返回形如 file:///data/linkis/workspace/dss_test01
的 userLocalRootPath。这说明用户在线编写的脚本是储存在服务器本地的。
要实现以项目为单位的 Git 存储库,就需要在用户创建工作区后,或者首次提交脚本时,将工作区进行 Git 初始化。这可以通过 JGit 库的 FileRepositoryBuilder.create()
方法实现,并提供相应接口。
如果采用第一种方案,在用户创建工作区后初始化,可以由前端在创建时直接调用该接口,直接对空文件夹初始化,较为快速便捷,缺点在于需要跨模块获取创建的工作区目录;
如果采用第二种方案,在用户首次提交脚本时初始化,就需要判断用户是否是首次提交。可以检查工作区是否已经初始化为 Git 仓库。如果已经存在.git
文件夹,就无需再进行初始化。这可以通过编写一个私有静态方法实现,缺点在于每次提交时都需要额外的判断,会产生多余的性能开销:
1 | private static boolean isGitRepository(File folder) { |
远端初始化
在注册新 DSS 用户时,如果 GitLab 中没有此用户的账号,就自动创建一个,其用户名和密码与 DSS SSO 中保存的当前用户信息一致。
用户创建工作区时,在该用户的 GitLab 账号中创建与工作区同名的 Git 项目,以此来实现粒度合适的版本管理。
此外,如果需要允许用户登录 GitLab,以便于进行例如差异比较等更加细化的操作,就需要在 GitLab 侧配置与 DSS SSO 兼容的统一身份认证。
示例代码
1 | public class GitLabManager { |
功能整合
在最终的实现中,可以对 Git 操作作出一定整合。例如,在 Intellij IDEA 中,当项目存储库具有可连通的远端时,就只保留了 “推送” 按钮,提交操作将在推送前一并完成。
Git 操作接口
此小节给出了 dss-gitlab-appconn 模块中 “提交” 接口的示例代码及注释,配套接口文档可跳转至示例:提交到 GitLab
示例代码
1 |
|
实施规范
开发
AppConn 三级规范
一级规范
SSO 登录规范,如 DolphinScheduler,可以通过左侧菜单跳转到相应页面。
二级规范
组织结构框架规范,例如工作空间体系规范,包括角色权限体系框架、角色规范、工程规范等。
三级规范
应用开发流程规范。
组件间调用流程
以 DolphinScheduler 为例:
- 首先会将 DSS 里面的一些 workflow 参数转化成 DolphinScheduler 支持的内部参数
- 然后进行节点参数的转换
- 再进行功能流的转换
- 转换完成后,通过用 HTTP 请求调用 DolphinScheduler 的 update 接口的方式,将已经创建好的 DolphinScheduler 工作流进行更新
- 最终即可将 DSS 中的工作流发布到 DolphinScheduler 中
完成 conversion 工作流转换后,便需要使用 operation 模块,将 DSS 与 DolphinScheduler 的工作流和项目进行关联,并执行增删改查等操作。
AppConn 开发规范
将会参考:
可能的冲突问题
在用户创建工作区后初始化 Git 存储库时,需要从其它模块获取创建的工作区目录,有可能会导致与其它开发者在此包中的修改产生 Git 冲突。
为了避免冲突数量过多、过于复杂、难以解决,我将在开始此任务前使用 git rebase
同步主线进度,并尽快完成所有开发。
在开发阶段性完成时,我将再次使用变基合并。相比于全部整合完成后再使用 merge
合并,这种方式的好处在于单次合并冲突数量少、分支提交记录线性排列较为清晰、联系另一位开发者解决冲突的缓冲时间长、不容易影响工作进度。
接口可用性问题
接口在开发完成后可能会产生隐性的问题,尤其是与作用域相关的调用问题。为此,我将利用 IntelliJ IDEA 的 yFiles
图表功能,观察其它接口的各类注解、导入、抽象类和依赖包的引用关系截图,与我的接口的引用关系相比较,确保作用域无误。
对于接口本身功能是否正常的自测,将使用 Postman 和单元测试配合完成。
开发 TBD 和 TODO
在开发时,可能会遇到代码中的 TODO 标记。对此,我将在熟悉需求后,自行建立业务场景,针对场景中的细节开发每一项对应功能,并编写单元测试,确保接口功能正常、可靠。
注释
范围
dss-gitlab-appconn 模块,对象为所有的方法。
格式
对于任何一个项目而言,尤其是开源项目,在撰写 JavaDoc 注释时,都需要注意以下方面,以确保注释全面且易于理解:
- 摘要(Summary):提供一个简洁但清晰的摘要,概括该方法或接口的主要功能和作用。
- 参数(Parameters):列出方法或接口接受的所有参数,并为每个参数提供描述。包括参数的名称、类型、是否可为空以及对参数的期望值或用法的说明。
- 返回值(Return Value):描述方法或接口的返回值。指明返回值的类型、可能的返回结果、异常情况或特殊条件等。
- 抛出(Throws):列出方法或接口可能会抛出的异常,并提供每个异常的类型、触发条件和处理建议。
- 示例(Examples):提供一个或多个示例,展示如何使用该方法或接口。可以包括参数设置、方法调用和预期结果的演示。
- 注意事项(Notes):说明任何与方法或接口相关的重要注意事项或限制。
- 作者(Author):标明编写该方法或接口的作者。
- 参考(See Also):指向与该方法或接口相关的其他文档、资源或类。
- 版本(Version):指明该方法或接口首次出现的版本号,并注明修改历史和版本更新。
- 修饰符(Modifiers):指明方法或接口的访问修饰符(例如 public、private、protected)和其他修饰符(例如 static、final)。
- 参数范围(Parameter Ranges):为每个参数提供有效范围或允许的取值范围。
- 线程安全性(Thread Safety):指明该方法或接口的线程安全性信息。例如是否可以在多线程环境中安全地调用。
- 依赖关系(Dependencies):列出方法或接口依赖的其他类、接口或资源。
具体来说,我将使用 Checkstyle 工具来检查 Java 源代码是否符合代码标准的验证规则,默认情况下,此工具遵守 Google Java Style Guide 和 Sun Code Conventions,需要在 IntelliJ IDEA 中安装 CheckStyle-IDEA 插件配合使用,通过以下方式导入检查样式文件:
1 | Editor -> Code Style -> Java -> Scheme -> Import Scheme -> CheckStyle Configuration |
在这个代码样式文件中,规定了 Google Java Style Guide 所偏好的 JavaDoc 注释风格,需要:
对齐形参说明
对齐抛出异常说明
在描述后空行
保留无效标签
保留空 @param 标签
保留空 @return 标签
保留空 @throws 标签
在右页边距处换行
启用前导星号
用 @throws 而不是 @exception
在空行中生成
<p>
保留空行
不需要:
- 在形参描述后空行
- 在 return 后空行
- 一行注释不分行
- 保留换行
- 在新行描述形参
- 缩进连续线
示例如下:
1 | package sample; |
提交形式
以一个功能所包含的文件与类为单位,在 WeBankFinTech/DataSphereStudio 仓库新建一个 Issue,声明正在为哪个模块的哪个功能撰写注释,然后向 Pil0tXia/DataSphereStudio 仓库的 pil0txia_doc_{ISSUE ID} 分支提交 Git Commit。当一个主要功能的全部接口和方法的 JavaDoc 注释均已撰写完成时,从该分支向 WeBankFinTech/DataSphereStudio 仓库发起 Pull Request,并请求 Commiters 和 Maintainers 进行 Code Review,进行代码合并。
当拉取合并请求处于 Review 阶段时,我将从 WeBankFinTech/DataSphereStudio 仓库 master 分支最新的提交拉取一个新的分支,并继续按照上述工作流新建 Issue、撰写注释,形成一个 Contributor 与 Reviewer 异步的贡献形式。
文档
范围
对于课题预期任务而言,需要编写文档的范围 dss-gitlab-appconn 模块,对象为所有的接口。
格式
在正式创建 md 文件之前,需要先思考接口文档在侧边栏目录中的位置和组织形式,并且在仓库中新建属于接口文档的目录。
DataSphereStudio-Doc 支持英文与中文两种语言,这两种语言的 Markdown 文件是分开存放的,分别位于 en_US
和 zh_CN
目录。两者目录层级是一样的,是为了支持多语言的文档展示。
在编写文档时,需要注意以下方面,以确保 Markdown 语法可以被正确地解析,并支持多种 Markdown 渲染器的排版:
- 目录结构:根据接口的层级结构或逻辑关系,创建一个清晰的目录结构。使用标题和子标题来组织接口文档,且标题层级不超过四级。
- 接口概述:对每个接口提供一个简要概述,描述其用途、输入和输出等关键信息。指明接口的名称、路径和 HTTP 方法。
- 参数说明:列出每个接口所需的参数,并提供参数的名称、类型、是否必需、取值范围以及示例值等信息。对于复杂的参数结构,可以使用表格或嵌套列表来清晰展示参数的层级关系和说明。
- 响应示例:提供一个或多个示例,展示接口的调用和返回结果。示例可以包括请求和响应的数据结构、状态码和消息等信息。对于可选的响应字段,也可以提供示例值。
- 异常处理:描述可能的错误情况和异常,以及相应的错误码和错误消息。提供每个异常的名称、描述和处理建议。
- 接口详情:为每个接口提供更详细的说明,包括接口的功能、用法、限制、注意事项和最佳实践等。可以使用段落、列表和代码块来组织和展示信息。
- 参考资料:提供与该模块或接口相关的其他文档、资源或链接。
- 更新记录:在文档中提供更新记录和重要变更,指明版本号、修改内容和日期。
- 示例代码:为关键接口或复杂场景提供示例代码。
- 格式和排版:使用代码块和强调样式等来保持一致的格式和排版。
- 图表和图像:可以使用图表、图像或流程图等可视化工具来说明接口的工作流程或数据流动。
- 文档导航:在官网上发布时,需要在整个网站上提供简单且直观的目录导航,使访问者能够轻松找到和浏览 dss-gitlab-appconn 模块的接口文档。
在编写 Markdown 文档之前,我应该已经在接口的代码中撰写了注释,以便从代码中对照文档。
提交形式
以一个接口为单位,在 WeBankFinTech/DataSphereStudio-Doc 仓库新建一个 Issue,声明正在为哪个接口撰写注释,然后向 Pil0tXia/DataSphereStudio-Doc 仓库的 pil0txia_docs_{ISSUE ID} 分支提交 Git Commit。此处的分支名称与撰写注释任务的分支名称并不相同,发布于 Web 网站上的使用文档的英文通常使用 docs 表示,与承载撰写注释任务的 doc 分支作区分。
当一个主要功能的全部接口的 Markdown 文档均已撰写完成时,从该分支向 WeBankFinTech/DataSphereStudio-Doc 仓库发起 Pull Request,并请求 Commiters 和 Maintainers 进行 Code Review,进行代码合并。
当拉取合并请求处于 Review 阶段时,我将从 WeBankFinTech/DataSphereStudio-Doc 仓库 master 分支最新的提交拉取一个新的分支,并继续按照上述工作流新建 Issue、撰写注释,形成一个 Contributor 与 Reviewer 异步的贡献形式。
示例:提交到 GitLab
接口说明
提交功能的接口用于将指定的文件或所有文件添加到 GitLab 的暂存区,并创建一个新的提交。
请求地址
1 | POST https://dss-open.wedatasphere.com/api/rest_j/v1/gitlab/commit |
请求参数
参数名 | 类型 | 是否必需 | 描述 |
---|---|---|---|
authorName | 字符串 | 是 | 提交的作者姓名 |
authorEmail | 字符串 | 是 | 提交的作者邮箱 |
commitMessage | 字符串 | 是 | 提交的消息 |
filePaths | 字符串数组 | 否 | 要添加到暂存区的文件路径列表。如果不提供该参数,则默认添加所有文件到暂存区。 |
请求示例
1 | { |
返回参数
参数名 | 类型 | 描述 |
---|---|---|
commitHash | 字符串 | 提交的哈希值 |
返回结果示例
1 | { |
返回码说明
返回码 | 说明 |
---|---|
200 | 请求成功 |
400 | 请求参数缺失或格式错误 |
500 | 服务器内部错误 |
测试
范围
dss-gitlab-appconn 模块,对象为所有的方法。
要求
测试代码的编写可以参考现有的测试文件。在单元测试时,需要注意以下方面:
- 输入验证:确保测试覆盖了各种可能的输入情况,包括边界值、无效值、空值和有效值。
- 接口状态:测试应该涵盖接口的各种状态和路径。例如,在测试
testTopicCreateRequestSetName
时,应该包括设置名称为null
的情况以验证接口的响应。 - 异常情况:测试接口在异常情况下的行为。例如接口是否正确地处理了错误的输入或不正确的参数。
- 序列化和反序列化:对于涉及对象的序列化和反序列化的接口,应该编写测试来验证对象的正确序列化和反序列化。确保序列化后的数据包含所需的字段,并且在反序列化后可以正确还原为对象。
- 副作用和一致性:如果接口执行了一些副作用或对系统状态进行了更改,测试应该验证这些副作用是否按预期发生,并确保接口的行为一致。
- 测试覆盖率:尽量覆盖接口的各个路径和代码分支,以确保测试足够全面。使用代码覆盖工具(如 JaCoCo 和 Codecov 等)来评估测试的覆盖率,并尽量达到较高的覆盖率。
- 并发和性能:如果接口设计要求支持高并发或高性能,需要验证接口在高并发和高负载情况下的表现和性能。
- 引入依赖:在测试中正确模拟或提供依赖项。
- 可读性和可维护性:编写清晰、简洁、可读性强的测试代码,使用有意义的命名和注释,以便他人能够理解和维护测试。
- 持续集成和自动化:将测试集成到持续集成(CI)流程中,在每次代码提交时自动运行测试。
提交形式
以一个功能所包含的文件与类为单位,在 WeBankFinTech/DataSphereStudio 仓库新建一个 Issue,声明正在为哪个模块的哪个功能编写测试代码,然后向 Pil0tXia/DataSphereStudio 仓库的 pil0txia_test_{ISSUE ID} 分支提交 Git Commit。当一个主要功能的全部接口和方法的 JavaDoc 注释均已撰写完成时,从该分支向 WeBankFinTech/DataSphereStudio 仓库发起 Pull Request,并请求 Commiters 和 Maintainers 进行 Code Review,进行代码合并。
当拉取合并请求处于 Review 阶段时,我将从 WeBankFinTech/DataSphereStudio 仓库 master 分支最新的提交拉取一个新的分支,并继续按照上述工作流新建 Issue、撰写注释,形成 Contributor 与 Reviewer 异步的贡献形式。
时间规划
每周时间安排
每周约 32 小时:
- 周一至周五,每日 3 小时
- 周末,每日 8 小时
- 向导师汇报开发进度与安排,1 小时
项目进度
任务 | 时间 |
---|---|
熟悉项目 | 7.1 - 7.7 |
熟悉 AppConn 对接规范 | 7.8 - 7.14 |
开发 Git 基础操作 API | 7.15 - 7.21 |
配置 GitLab 第三方系统 | 7.21 - 8.4 |
撰写中期报告 | 8.5 - 8.11 |
将 GitLab 与 API 整合为插件 | 8.12 - 8.25 |
测试接口功能 | 8.25 - 8.31 |
编写 JavaDoc 注释 | 9.1 - 9.7 |
编写接口文档 | 9.8 - 9.14 |
开发 TBD 和 TODO | 9.15 - 9.21 |
撰写结题报告 | 9.22 - 10.5 |
弹性时间安排 | 10.5 - 10.11 |
个人简介
我是来自南京信息工程大学的夏天,大三,目前正在联想实习,承担 Spring Cloud + Kafka + Eureka 方面的后端开发工作。这是我的博客、文档和 Github,日均 PV 400 左右,有些文章的谷歌 / 必应排名也比较高。
每每使用开源工具和框架,都很感谢开发者的付出。在我注册 Github 账号的第五年,我意识到自己应该真正地去研究透彻一个框架、参与一个社区、进行贡献,我也非常希望自己能在时间还算充裕的学生时代,多尝试一些新技术,抓住这个契机。
衷心希望能参加张旗导师您指导的 GLCC 课题。
联系方式:admin@pil0txia.com
未来展望
在已规划的 DSS 1.2.0 中,包含以下新功能:
- 数仓规划:包含主题域、数仓分层、修饰词等
- 数据模型中心:包括指标、维度、度量和向导式建表等
- 数据资产中心:打通 Apache Altas,提供数据血缘能力
在后续的社区贡献中,我会深入理解产品定位,设想产品场景,主动发现增长点与增强点,并持之以恒地作出贡献。