6-27 更新：已中选，虽然最多可以申请两个课题，但很遗憾 GLCC 规定学生只能参与第一个课题。导师对我很好，会继续关注 WeDataSphere 社区的！

此项目托付给了我的同学杨朋睿。

项目申请书

课题名称

DataSphereStudio 集成 Gitlab

申请人：夏天

导师：张旗 | burdezhang@webank.com

社区简介

DataSphere Studio（简称 DSS）是微众银行自研的一站式数据应用开发管理框架。

​ 在统一的 UI 下，DataSphere Studio 以工作流式的图形化拖拽开发体验，将满足从数据交换、脱敏清洗、分析挖掘、质量检测、可视化展现、定时调度到数据输出应用等，数据应用开发全流程场景需求。

​ DSS 通过插拔式的集成框架设计，让用户可以根据需要，简单快速替换 DSS 已集成的各种功能组件，或新增功能组件。

题目简介

本课题旨在将 Gitlab 集成到 DataSphereStudio 中，以便于更好地管理用户在 DataSphereStudio 中开发的代码。

1. 接入 Gitlab：我们将实现 DataSphereStudio 中的脚本接入 Gitlab 的功能，以便使用 DataSphereStudio 的开发人员可以更好地查看、修改和管理代码。这将有助于提升协作效率和代码质量。
2. 版本管理和协作：通过集成 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
2
3
4

private static boolean isGitRepository(File folder) {
        File gitFolder = new File(folder, ".git");
        return gitFolder.exists() && gitFolder.isDirectory();
    }

远端初始化

在注册新 DSS 用户时，如果 GitLab 中没有此用户的账号，就自动创建一个，其用户名和密码与 DSS SSO 中保存的当前用户信息一致。

用户创建工作区时，在该用户的 GitLab 账号中创建与工作区同名的 Git 项目，以此来实现粒度合适的版本管理。

此外，如果需要允许用户登录 GitLab，以便于进行例如差异比较等更加细化的操作，就需要在 GitLab 侧配置与 DSS SSO 兼容的统一身份认证。

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

public class GitLabManager {

    private static final String GITLAB_API_URL = "https://gitlab.wedatasphere.com/api/v4";
    private static final String GITLAB_ADMIN_TOKEN = "MY_GITLAB_ADMIN_TOKEN";

    public static void createGitLabProject(String username, String password, String projectName) throws IOException {
        
        createUser(username, password);
        
        createProject(username, projectName);
        
        addProjectMember(username, projectName);
    }

    private static void createUser(String username, String password) throws IOException {
        
        String createUserUrl = GITLAB_API_URL + "/users";
        
        JSONObject userRequestBody = new JSONObject();
        userRequestBody.put("username", username);
        userRequestBody.put("password", password);
        
        sendPostRequest(createUserUrl, userRequestBody.toString(), GITLAB_ADMIN_TOKEN);
    }

    private static void createProject(String username, String projectName) throws IOException {
        
    }

    private static void addProjectMember(String username, String projectName) throws IOException {
        
        String userId = getUserId(username);
        
        String projectId = getProjectId(projectName);
        
        String addMemberUrl = GITLAB_API_URL + "/projects/" + projectId + "/members";
        
        JSONObject memberRequestBody = new JSONObject();
        memberRequestBody.put("user_id", userId);
        memberRequestBody.put("access_level", 30); 
        
        sendPostRequest(addMemberUrl, memberRequestBody.toString(), GITLAB_ADMIN_TOKEN);
    }

    private static String getUserId(String username) throws IOException {
        
        String getUserUrl = GITLAB_API_URL + "/users?username=" + username;
        
        String response = sendGetRequest(getUserUrl, GITLAB_ADMIN_TOKEN);
        
        JSONArray users = new JSONArray(response);
        if (users.length() > 0) {
            JSONObject user = users.getJSONObject(0);
            return user.getString("id");
        }
        return null;
    }

    private static String getProjectId(String projectName) throws IOException {
        
    }

        public static String sendPostRequest(String url, String requestBody, String accessToken) throws IOException {
        HttpClient httpClient = HttpClients.createDefault();
        HttpPost httpPost = new HttpPost(url);
        
        httpPost.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
        httpPost.setHeader(HttpHeaders.ACCEPT, "application/json");
        httpPost.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
        
        StringEntity stringEntity = new StringEntity(requestBody);
        httpPost.setEntity(stringEntity);
        
        HttpResponse response = httpClient.execute(httpPost);
        
        HttpEntity entity = response.getEntity();
        String responseString = EntityUtils.toString(entity);
        return responseString;
    }

    public static String sendGetRequest(String url, String accessToken) throws IOException {
  
    }
}

功能整合

在最终的实现中，可以对 Git 操作作出一定整合。例如，在 Intellij IDEA 中，当项目存储库具有可连通的远端时，就只保留了 “推送” 按钮，提交操作将在推送前一并完成。

Git 操作接口

此小节给出了 dss-gitlab-appconn 模块中 “提交” 接口的示例代码及注释，配套接口文档可跳转至示例：提交到 GitLab

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

@RestController
public class GitLabConnector {
    private Repository repository;
    private Git git;

    
    public void initialize(String localPath) throws InvalidRemoteException, GitAPIException {
        
        repository = Git.open(new File(localPath)).getRepository();
        git = new Git(repository);
    }

    
    @PostMapping("/api/commit")
    public String commit(@RequestBody CommitRequest commitRequest) throws GitAPIException {
        String authorName = commitRequest.getAuthorName();
        String authorEmail = commitRequest.getAuthorEmail();
        String commitMessage = commitRequest.getCommitMessage();
        String[] filePaths = commitRequest.getFilePaths();
        
        
        if (filePaths.length == 0) {
            git.add().addFilepattern(".").call();
        } else {
            AddCommand addCommand = git.add();
            for (String filePath : filePaths) {
                addCommand.addFilepattern(filePath);
            }
            addCommand.call();
        }

        
        CommitCommand commitCommand = git.commit();
        
        commitCommand.setAuthor(authorName, authorEmail);
        
        commitCommand.setMessage(commitMessage);
        
        RevCommit revCommit = commitCommand.call();
        
        return revCommit.getName();
    }
    
    
    @Data
    public static class CommitRequest {
        private String authorName;
        private String authorEmail;
        private String commitMessage;
        private String[] filePaths;
    }
}

实施规范

开发

AppConn 三级规范

一级规范

SSO 登录规范，如 DolphinScheduler，可以通过左侧菜单跳转到相应页面。

二级规范

组织结构框架规范，例如工作空间体系规范，包括角色权限体系框架、角色规范、工程规范等。

三级规范

应用开发流程规范。

组件间调用流程

以 DolphinScheduler 为例：

• 首先会将 DSS 里面的一些 workflow 参数转化成 DolphinScheduler 支持的内部参数
• 然后进行节点参数的转换
• 再进行功能流的转换
• 转换完成后，通过用 HTTP 请求调用 DolphinScheduler 的 update 接口的方式，将已经创建好的 DolphinScheduler 工作流进行更新
• 最终即可将 DSS 中的工作流发布到 DolphinScheduler 中

完成 conversion 工作流转换后，便需要使用 operation 模块，将 DSS 与 DolphinScheduler 的工作流和项目进行关联，并执行增删改查等操作。

AppConn 开发规范

将会参考：

第三方系统接入 DSS 开发指南

AppConn 开发指南

可能的冲突问题

在用户创建工作区后初始化 Git 存储库时，需要从其它模块获取创建的工作区目录，有可能会导致与其它开发者在此包中的修改产生 Git 冲突。

为了避免冲突数量过多、过于复杂、难以解决，我将在开始此任务前使用 git rebase 同步主线进度，并尽快完成所有开发。

在开发阶段性完成时，我将再次使用变基合并。相比于全部整合完成后再使用 merge 合并，这种方式的好处在于单次合并冲突数量少、分支提交记录线性排列较为清晰、联系另一位开发者解决冲突的缓冲时间长、不容易影响工作进度。

接口可用性问题

接口在开发完成后可能会产生隐性的问题，尤其是与作用域相关的调用问题。为此，我将利用 IntelliJ IDEA 的 yFiles 图表功能，观察其它接口的各类注解、导入、抽象类和依赖包的引用关系截图，与我的接口的引用关系相比较，确保作用域无误。

对于接口本身功能是否正常的自测，将使用 Postman 和单元测试配合完成。

开发 TBD 和 TODO

在开发时，可能会遇到代码中的 TODO 标记。对此，我将在熟悉需求后，自行建立业务场景，针对场景中的细节开发每一项对应功能，并编写单元测试，确保接口功能正常、可靠。

注释

范围

dss-gitlab-appconn 模块，对象为所有的方法。

格式

对于任何一个项目而言，尤其是开源项目，在撰写 JavaDoc 注释时，都需要注意以下方面，以确保注释全面且易于理解：

1. 摘要（Summary）：提供一个简洁但清晰的摘要，概括该方法或接口的主要功能和作用。
2. 参数（Parameters）：列出方法或接口接受的所有参数，并为每个参数提供描述。包括参数的名称、类型、是否可为空以及对参数的期望值或用法的说明。
3. 返回值（Return Value）：描述方法或接口的返回值。指明返回值的类型、可能的返回结果、异常情况或特殊条件等。
4. 抛出（Throws）：列出方法或接口可能会抛出的异常，并提供每个异常的类型、触发条件和处理建议。
5. 示例（Examples）：提供一个或多个示例，展示如何使用该方法或接口。可以包括参数设置、方法调用和预期结果的演示。
6. 注意事项（Notes）：说明任何与方法或接口相关的重要注意事项或限制。
7. 作者（Author）：标明编写该方法或接口的作者。
8. 参考（See Also）：指向与该方法或接口相关的其他文档、资源或类。
9. 版本（Version）：指明该方法或接口首次出现的版本号，并注明修改历史和版本更新。
10. 修饰符（Modifiers）：指明方法或接口的访问修饰符（例如 public、private、protected）和其他修饰符（例如 static、final）。
11. 参数范围（Parameter Ranges）：为每个参数提供有效范围或允许的取值范围。
12. 线程安全性（Thread Safety）：指明该方法或接口的线程安全性信息。例如是否可以在多线程环境中安全地调用。
13. 依赖关系（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 注释风格，需要：

1. 对齐形参说明

2. 对齐抛出异常说明

3. 在描述后空行

4. 保留无效标签

5. 保留空 @param 标签

6. 保留空 @return 标签

7. 保留空 @throws 标签

8. 在右页边距处换行

9. 启用前导星号

10. 用 @throws 而不是 @exception

11. 在空行中生成 <p>

12. 保留空行

不需要：

1. 在形参描述后空行
2. 在 return 后空行
3. 一行注释不分行
4. 保留换行
5. 在新行描述形参
6. 缩进连续线

示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

package sample;

public class Sample {
    















    public abstract String sampleMethod(int i,
                                        int longParameterName,
                                        int missingDescription)
            throws XXXException, YException, ZException;

    


    public abstract String sampleMethod2();

    




    public abstract String sampleMethod3();
}

提交形式

以一个功能所包含的文件与类为单位，在 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 渲染器的排版：

1. 目录结构：根据接口的层级结构或逻辑关系，创建一个清晰的目录结构。使用标题和子标题来组织接口文档，且标题层级不超过四级。
2. 接口概述：对每个接口提供一个简要概述，描述其用途、输入和输出等关键信息。指明接口的名称、路径和 HTTP 方法。
3. 参数说明：列出每个接口所需的参数，并提供参数的名称、类型、是否必需、取值范围以及示例值等信息。对于复杂的参数结构，可以使用表格或嵌套列表来清晰展示参数的层级关系和说明。
4. 响应示例：提供一个或多个示例，展示接口的调用和返回结果。示例可以包括请求和响应的数据结构、状态码和消息等信息。对于可选的响应字段，也可以提供示例值。
5. 异常处理：描述可能的错误情况和异常，以及相应的错误码和错误消息。提供每个异常的名称、描述和处理建议。
6. 接口详情：为每个接口提供更详细的说明，包括接口的功能、用法、限制、注意事项和最佳实践等。可以使用段落、列表和代码块来组织和展示信息。
7. 参考资料：提供与该模块或接口相关的其他文档、资源或链接。
8. 更新记录：在文档中提供更新记录和重要变更，指明版本号、修改内容和日期。
9. 示例代码：为关键接口或复杂场景提供示例代码。
10. 格式和排版：使用代码块和强调样式等来保持一致的格式和排版。
11. 图表和图像：可以使用图表、图像或流程图等可视化工具来说明接口的工作流程或数据流动。
12. 文档导航：在官网上发布时，需要在整个网站上提供简单且直观的目录导航，使访问者能够轻松找到和浏览 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

请求参数

请求示例

1
2
3
4
5
6

{
  "authorName": "Xia Tian",
  "authorEmail": "admin@pil0txia.com",
  "commitMessage": "[Feature]: xxxxxx",
  "filePaths": ["file1.txt", "file2.txt"]
}

返回参数

返回结果示例

1
2
3

{
  "commitHash": "6d5e26a3d8a79242d2018f39b61ae4978b6b7c83"
}

返回码说明

测试

范围

dss-gitlab-appconn 模块，对象为所有的方法。

要求

测试代码的编写可以参考现有的测试文件。在单元测试时，需要注意以下方面：

1. 输入验证：确保测试覆盖了各种可能的输入情况，包括边界值、无效值、空值和有效值。
2. 接口状态：测试应该涵盖接口的各种状态和路径。例如，在测试 testTopicCreateRequestSetName 时，应该包括设置名称为 null 的情况以验证接口的响应。
3. 异常情况：测试接口在异常情况下的行为。例如接口是否正确地处理了错误的输入或不正确的参数。
4. 序列化和反序列化：对于涉及对象的序列化和反序列化的接口，应该编写测试来验证对象的正确序列化和反序列化。确保序列化后的数据包含所需的字段，并且在反序列化后可以正确还原为对象。
5. 副作用和一致性：如果接口执行了一些副作用或对系统状态进行了更改，测试应该验证这些副作用是否按预期发生，并确保接口的行为一致。
6. 测试覆盖率：尽量覆盖接口的各个路径和代码分支，以确保测试足够全面。使用代码覆盖工具（如 JaCoCo 和 Codecov 等）来评估测试的覆盖率，并尽量达到较高的覆盖率。
7. 并发和性能：如果接口设计要求支持高并发或高性能，需要验证接口在高并发和高负载情况下的表现和性能。
8. 引入依赖：在测试中正确模拟或提供依赖项。
9. 可读性和可维护性：编写清晰、简洁、可读性强的测试代码，使用有意义的命名和注释，以便他人能够理解和维护测试。
10. 持续集成和自动化：将测试集成到持续集成（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 小时

项目进度

个人简介

我是来自南京信息工程大学的夏天，大三，目前正在联想实习，承担 Spring Cloud + Kafka + Eureka 方面的后端开发工作。这是我的博客、文档和 Github，日均 PV 400 左右，有些文章的谷歌 / 必应排名也比较高。

每每使用开源工具和框架，都很感谢开发者的付出。在我注册 Github 账号的第五年，我意识到自己应该真正地去研究透彻一个框架、参与一个社区、进行贡献，我也非常希望自己能在时间还算充裕的学生时代，多尝试一些新技术，抓住这个契机。

衷心希望能参加张旗导师您指导的 GLCC 课题。

联系方式：admin@pil0txia.com

未来展望

在已规划的 DSS 1.2.0 中，包含以下新功能：

• 数仓规划：包含主题域、数仓分层、修饰词等
• 数据模型中心：包括指标、维度、度量和向导式建表等
• 数据资产中心：打通 Apache Altas，提供数据血缘能力

在后续的社区贡献中，我会深入理解产品定位，设想产品场景，主动发现增长点与增强点，并持之以恒地作出贡献。