如何基于Spring Boot开发REST API调用GitLab API实现仓库分支查询与合并请求功能？

我刚好做过类似的GitLab API集成项目，给你梳理一套完整的落地方案，一步步来就能搞定：

首先得搞定GitLab的API访问权限：

• 登录你的GitLab实例，生成一个个人访问令牌（PAT），权限至少要勾选 read_repository（拉取分支用）和 write_repository（发起合并请求用）
• 把GitLab的基础API地址（比如你的私有GitLab地址是 https://your-gitlab.com，那API前缀就是 https://your-gitlab.com/api/v4）和令牌配置到Spring Boot的 application.yml 里，避免硬编码：

gitlab:
  base-url: https://your-gitlab-instance.com/api/v4
  access-token: your-personal-access-token-here

推荐用官方维护的 gitlab4j-api 客户端，它已经封装了所有GitLab API的调用细节，比自己写RestTemplate省事太多。在Maven的 pom.xml 里加依赖：

<dependency>
    <groupId>org.gitlab4j</groupId>
    <artifactId>gitlab4j-api</artifactId>
    <version>5.3.0</version> <!-- 用最新稳定版就行 -->
</dependency>

写个配置类，把GitLabApi实例注入到Spring容器里，方便后续Service层调用：

@Configuration
public class GitLabConfig {

    @Value("${gitlab.base-url}")
    private String baseUrl;

    @Value("${gitlab.access-token}")
    private String accessToken;

    @Bean
    public GitLabApi gitLabApi() {
        GitLabApi gitLabApi = new GitLabApi(baseUrl, accessToken);
        // 配置请求超时，避免长时间挂起
        gitLabApi.setRequestTimeout(10000);
        return gitLabApi;
    }
}

创建一个 GitLabService，封装你需要的两个核心功能：

4.1 拉取指定仓库的分支详情 #

根据项目路径（比如 your-group/your-service）或者项目ID，调用API获取分支列表，返回分支名称、最后提交信息、是否受保护等详情：

@Service
public class GitLabService {

    private final GitLabApi gitLabApi;

    // 构造注入GitLab客户端
    public GitLabService(GitLabApi gitLabApi) {
        this.gitLabApi = gitLabApi;
    }

    // 通过项目路径获取分支列表
    public List<Branch> getBranchesByProjectPath(String projectPath) throws GitLabApiException {
        Project project = gitLabApi.getProjectApi().getProject(projectPath);
        return gitLabApi.getRepositoryApi().getBranches(project.getId());
    }

    // 也支持通过项目ID直接获取（如果前端传ID更方便的话）
    public List<Branch> getBranchesByProjectId(Long projectId) throws GitLabApiException {
        return gitLabApi.getRepositoryApi().getBranches(projectId);
    }
}

这里的 Branch 是 gitlab4j-api 自带的实体类，已经包含了前端需要的所有分支字段，直接返回就行。

4.2 发起分支合并请求（MR） #

接收前端传递的项目路径、源分支、目标分支、MR标题和描述，调用API创建合并请求：

// 发起合并请求的方法
public MergeRequest createMergeRequest(String projectPath, String sourceBranch, String targetBranch, String title, String description) throws GitLabApiException {
    Project project = gitLabApi.getProjectApi().getProject(projectPath);
    // 构建MR参数，还可以加审批人、标签、合并后删除源分支等配置
    MergeRequestParams params = MergeRequestParams.builder()
            .sourceBranch(sourceBranch)
            .targetBranch(targetBranch)
            .title(title)
            .description(description)
            .removeSourceBranch(false) // 可选：合并后是否删除源分支
            .build();
    return gitLabApi.getMergeRequestApi().createMergeRequest(project.getId(), params);
}

写个Controller，把Service的方法封装成HTTP接口，适配前端的调用需求：

@RestController
@RequestMapping("/api/gitlab")
public class GitLabController {

    private final GitLabService gitLabService;

    public GitLabController(GitLabService gitLabService) {
        this.gitLabService = gitLabService;
    }

    // 获取指定项目的分支列表
    @GetMapping("/branches")
    public ResponseEntity<List<Branch>> getBranches(@RequestParam String projectPath) {
        try {
            List<Branch> branches = gitLabService.getBranchesByProjectPath(projectPath);
            return ResponseEntity.ok(branches);
        } catch (GitLabApiException e) {
            // 根据GitLab返回的错误码返回对应HTTP状态，比如404项目不存在、403权限不足
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

    // 发起合并请求
    @PostMapping("/merge-requests")
    public ResponseEntity<MergeRequest> createMergeRequest(@RequestBody MergeRequestRequest request) {
        try {
            MergeRequest mergeRequest = gitLabService.createMergeRequest(
                    request.getProjectPath(),
                    request.getSourceBranch(),
                    request.getTargetBranch(),
                    request.getTitle(),
                    request.getDescription()
            );
            return ResponseEntity.ok(mergeRequest);
        } catch (GitLabApiException e) {
            // 处理分支不存在、目标分支受保护无法合并等错误
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(null);
        }
    }

    // 自定义DTO，接收前端传递的MR参数
    public static class MergeRequestRequest {
        private String projectPath;
        private String sourceBranch;
        private String targetBranch;
        private String title;
        private String description;

        // 省略getter和setter
    }
}

• 权限管控：生产环境不要把PAT硬编码，用环境变量或者配置中心（比如Nacos）管理；另外要确保PAT对应的用户有权限合并目标分支（比如prod分支如果是受保护的，要在GitLab里配置允许该用户合并）
• 错误处理：GitLabApiException 会包含具体的错误信息（比如“项目不存在”“源分支不存在”），可以把这些信息解析后返回给前端，方便前端给用户友好提示
• 批量操作优化：如果需要一次性给多个微服务发起MR，可以循环调用创建MR的方法，同时加上重试机制（比如用Spring Retry），防止网络波动导致部分操作失败
• 测试验证：先在测试环境的GitLab仓库上验证流程，比如创建一个测试项目，先拉取分支再发起MR，确认一切正常后再对接正式环境

内容的提问来源于stack exchange，提问作者Venkaiah Yepuri