• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端

导读：本文围绕 lakeFS Java SDK（io.lakefs.clients.sdk）中的PullsApi，系统讲解在数据湖中通过 API 创建、查询、列表、更新与合并 Pull Request 的完整方法。你将掌握每一个接口的 Java 调用示例、请求/响应模型、权限与状态码语义，并对照仓库源码（api/swagger.yml、pkg/api/controller.go、pkg/catalog/catalog.go）理解其底层实现，从而在自己的 Java 数据管道中可靠地实现"Git 式"的代码评审与合并流程。

一、Pull Request 在 lakeFS 中的定位

lakeFS 把对象存储"变成"一个带分支（Branch）、提交（Commit）、合并（Merge）语义的版本化数据湖。Pull Request 是连接"分支开发"与"主干合并"的关键协作单元：数据工程师在特性分支上写入数据、提交变更后，通过 Pull Request 发起评审，评审通过后将其合并到目标分支。

从 API 契约看，Pulls 相关接口在 api/swagger.yml 中被打上了pulls与experimental两个 tag（见 swagger.yml 第 6216 行），表示该组能力仍处于实验性演进阶段。所有路径均挂在/api/v1之下，且都以/repositories/{repository}/pulls为前缀。

服务端实现位于 pkg/api/controller.go（HTTP 控制器层）与 pkg/catalog/catalog.go（catalog 业务层），SDK 文档所描述的每个方法都能在这两层找到一一对应的实现。

二、环境准备：引入 SDK 与配置认证

2.1 添加依赖

Java SDK 的构建与安装方式见 clients/java/README.md：先执行mvn clean install将客户端库安装到本地 Maven 仓库，然后在项目 POM 中加入依赖：

<dependency> <groupId>io.lakefs</groupId> <artifactId>sdk</artifactId> <version>0.0.0</version> <scope>compile</scope> </dependency>

Gradle 用户则配置：

repositories { mavenCentral() // Needed if the 'sdk' jar has been published to maven central. mavenLocal() // Needed if the 'sdk' jar has been published to the local maven repo. } dependencies { implementation "io.lakefs:sdk:0.0.0" }

2.2 初始化 ApiClient 与认证

所有接口的根地址都相对于/api/v1。在调用PullsApi之前，需要创建ApiClient并配置至少一种认证方式。SDK 支持三种认证：

• basic_auth：HTTP Basic 认证，通过HttpBasicAuth.setUsername/setPassword配置访问凭证；
• cookie_auth：API Key 认证，通过ApiKeyAuth.setApiKey配置，可选setApiKeyPrefix("Token")设置前缀（默认为 null）；
• jwt_token：HTTP Bearer 认证，通过HttpBearerAuth.setBearerToken配置 JWT。

import io.lakefs.clients.sdk.ApiClient; import io.lakefs.clients.sdk.ApiException; import io.lakefs.clients.sdk.Configuration; import io.lakefs.clients.sdk.auth.*; import io.lakefs.clients.sdk.models.*; import io.lakefs.clients.sdk.PullsApi; ApiClient defaultClient = Configuration.getDefaultApiClient(); defaultClient.setBasePath("/api/v1"); // Configure HTTP basic authorization: basic_auth HttpBasicAuth basic_auth = (HttpBasicAuth) defaultClient.getAuthentication("basic_auth"); basic_auth.setUsername("YOUR USERNAME"); basic_auth.setPassword("YOUR PASSWORD"); // Configure API key authorization: cookie_auth ApiKeyAuth cookie_auth = (ApiKeyAuth) defaultClient.getAuthentication("cookie_auth"); cookie_auth.setApiKey("YOUR API KEY"); //cookie_auth.setApiKeyPrefix("Token"); // Configure HTTP bearer authorization: jwt_token HttpBearerAuth jwt_token = (HttpBearerAuth) defaultClient.getAuthentication("jwt_token"); jwt_token.setBearerToken("BEARER TOKEN"); PullsApi apiInstance = new PullsApi(defaultClient);

从服务端源码看，权限校验是逐接口执行的（见下文的接口解析），因此请确保所用凭证对目标仓库具备相应的读/写权限。

三、PullsApi 接口总览

其中repository为仓库名，pull_request为 Pull Request ID（创建成功时返回的字符串 ID）。

四、创建 Pull Request：createPullRequest

4.1 接口语义

createPullRequest(repository, pullRequestCreation).execute()对应POST /repositories/{repository}/pulls，请求体为PullRequestCreation，成功返回201，响应体为PullRequestCreationResponse（仅包含新 PR 的id）。

4.2 请求体 PullRequestCreation

模型定义见 clients/java/docs/PullRequestCreation.md，字段如下：

服务端 schema（api/swagger.yml 第 1988 行）同样要求title、source_branch、destination_branch三个必填字段。

4.3 Java 示例

String repository = "repository_example"; PullRequestCreation pullRequestCreation = new PullRequestCreation(); pullRequestCreation.title("add qa dataset") .description("adds the QA dataset to the main branch") .sourceBranch("feature/qa-dataset") .destinationBranch("main"); try { PullRequestCreationResponse result = apiInstance.createPullRequest(repository, pullRequestCreation) .execute(); System.out.println(result.getId()); // 保存该 ID，后续 get/update/merge 都要用到 } catch (ApiException e) { System.err.println("Exception when calling PullsApi#createPullRequest"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); }

4.4 服务端到底做了什么

结合 pkg/api/controller.go 第 5632 行 与 pkg/catalog/catalog.go 第 3362 行，一次创建请求会经历：

1. 权限校验：要求WritePullRequestAction且资源为permissions.RepoArn(repository)（仓库级写权限）；
2. 身份注入：从认证上下文读取当前用户，Author字段取user.Committer()；
3. 参数校验：仓库名、源分支、目标分支 ID 均需通过graveler.ValidateRepositoryID/ValidateBranchID；且源分支与目标分支不能相同，否则返回graveler.ErrSameBranch（对应 HTTP 400/409）；
4. 存在性检查：源、目标分支必须真实存在于仓库中；
5. 生成 ID 并落库：PR ID 通过graveler.NewRunID()生成，CreationDate取当前时间，随后写入底层 KV 存储。

这也解释了为什么 SDK 文档中该接口会返回400（校验失败）、404（仓库或分支不存在）与409（资源冲突）等状态码。

4.5 HTTP 响应详情

请求头Content-Type: application/json，响应Accept: application/json。

五、查询单个 Pull Request：getPullRequest

5.1 接口语义

getPullRequest(repository, pullRequest).execute()对应GET /repositories/{repository}/pulls/{pull_request}，返回完整的PullRequest模型。参数中pullRequest为 PR ID（创建响应中返回的 id）。

String repository = "repository_example"; String pullRequest = "pullRequest_example"; // pull request id try { PullRequest result = apiInstance.getPullRequest(repository, pullRequest) .execute(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling PullsApi#getPullRequest"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); }

5.2 返回值 PullRequest

模型字段（clients/java/docs/PullRequest.md）：

StatusEnum取值：open、closed、merged（Java 侧枚举常量为OPEN/CLOSED/MERGED，见 PullRequest.java）。

服务端实现（controller.go 第 5668 行）要求ReadPullRequestAction权限，并将底层存储中的状态统一转为小写字符串后返回；mergedCommitId仅对已合并的 PR 有值。

5.3 HTTP 响应详情

六、列表查询：listPullRequests

6.1 接口语义与分页参数

listPullRequests(repository).prefix(prefix).after(after).amount(amount).status(status).execute()对应GET /repositories/{repository}/pulls，返回PullRequestsList。四个可选查询参数：

String repository = "repository_example"; String prefix = "prefix_example"; String after = "after_example"; Integer amount = 100; String status = "open"; try { PullRequestsList result = apiInstance.listPullRequests(repository) .prefix(prefix) .after(after) .amount(amount) .status(status) .execute(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling PullsApi#listPullRequests"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); }

6.2 分页与状态过滤的底层语义

从服务端代码（controller.go 第 5590 行、catalog.go 第 3424 行）可以确认三个关键细节：

• amount 归一化：paginationAmount将负数或未传值归一为默认 100，超出上限（DefaultMaxPerPage = 1000，定义于 controller.go 第 49-52 行）时截断为 1000；
• status 语义：pullRequestStatus只识别open/closed；在shouldSkipByStatus中，closed实际会同时包含CLOSED与MERGED两种状态（即"已结束的 PR"），open则严格只匹配OPEN，其余值返回全部；
• 分页实现：底层基于 PR ID 排序的迭代器，after作为 Seek 游标，prefix用于按 ID 前缀过滤，返回超过limit时通过hasMore标记是否还有下一页。

6.3 返回值 PullRequestsList

模型见 clients/java/docs/PullRequestsList.md：包含pagination（分页信息，含has_more等字段，模型定义见 Pagination）与results（List<PullRequest>）。注意：列表接口出于权限最小化考虑，返回的每条 PR 的description会被服务端显式置为null（见 controller.go 第 5611 行 的注释），完整描述需通过getPullRequest获取。

6.4 HTTP 响应详情

七、更新 Pull Request：updatePullRequest

7.1 接口语义

updatePullRequest(repository, pullRequest, pullRequestBasic).execute()对应PATCH /repositories/{repository}/pulls/{pull_request}，请求体为PullRequestBasic，成功返回200（响应体为空）。该接口用于修改 PR 的标题、描述或状态（例如评审结束后手动关闭 PR）。

String repository = "repository_example"; String pullRequest = "pullRequest_example"; // pull request id PullRequestBasic pullRequestBasic = new PullRequestBasic(); pullRequestBasic.title("new title").description("new description").status(PullRequestBasic.StatusEnum.CLOSED); try { apiInstance.updatePullRequest(repository, pullRequest, pullRequestBasic) .execute(); } catch (ApiException e) { System.err.println("Exception when calling PullsApi#updatePullRequest"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); }

7.2 请求体 PullRequestBasic

模型见 clients/java/docs/PullRequestBasic.md，三个字段均为可选（即支持只更新其中一部分）：

服务端实现（controller.go 第 5700 行）要求WritePullRequestAction权限，并透传给 catalog.go 第 3491 行 的UpdatePullRequest，最终由 KV 存储层完成合并更新。注意：merged状态通常由合并操作自动写入，手工更新请以open/closed为主。

7.3 HTTP 响应详情

八、合并 Pull Request：mergePullRequest

8.1 接口语义

mergePullRequest(repository, pullRequest).execute()对应PUT /repositories/{repository}/pulls/{pull_request}/merge，成功返回200与MergeResult。这是整个 Pull Request 生命周期中最核心的动作：它真正把源分支的变更合入目标分支，并产生一个新的提交。

String repository = "repository_example"; String pullRequest = "pullRequest_example"; // pull request id try { MergeResult result = apiInstance.mergePullRequest(repository, pullRequest) .execute(); System.out.println(result.getReference()); // 合并后的引用（commit 引用） } catch (ApiException e) { System.err.println("Exception when calling PullsApi#mergePullRequest"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); }

8.2 返回值 MergeResult

模型见 clients/java/docs/MergeResult.md，仅包含一个字段：

对应实现类 MergeResult.java 中SERIALIZED_NAME_REFERENCE = "reference"。

8.3 服务端合并流程与权限要求

controller.go 第 5723 行 的实现揭示了合并的完整链路：

1. 先取 PR 再鉴权：先GetPullRequest拿到 PR 及其目标分支，然后要求同时满足两个权限（AND 语义）：
   • CreateCommitAction，资源为目标分支permissions.BranchArn(repository, pr.Destination)；
   • WritePullRequestAction，资源为仓库；
2. 状态前置检查：PR 状态必须是open，否则返回 400 "bad pull request status"；
3. 执行合并：调用c.Catalog.Merge(ctx, repository, pr.Destination, pr.Source, ...)完成分支合并，得到合并后的 commit 引用；
4. 更新 PR 状态：将 PR 状态置为merged，并把MergedCommitID写为合并产生的 commit 引用；
5. 返回结果：MergeResult{Reference: reference}。

如果合并存在冲突，接口会返回409（文档特别注明：该 409 的内容 schema 未来将改为 Error 格式，目前仍返回空的MergeResult，属于弃用中的行为），412则代表前置条件失败（precondition failed）。

8.4 HTTP 响应详情

九、异常处理与状态码速查

SDK 中所有同步调用均抛出ApiException，其标准处理模式为：

catch (ApiException e) { System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); }

各接口常见状态码汇总（完整表见上述各节）：

十、模型对象与源码对照

Pulls 相关模型在 Java SDK 中的位置如下（均由 OpenAPI Generator 根据 api/swagger.yml 自动生成，对应pkg/api/apigen/lakefs.gen.go中的 Go 结构体）：

Java 端PullsApi本体位于 PullsApi.java，每个方法都提供链式参数构建（如new APIlistPullRequestsRequest(...).prefix(...).after(...).amount(...).status(...)）以及execute()（同步）与executeWithHttpInfo()（返回ApiResponse<T>，可进一步拿到完整 HTTP 状态与响应头）两种执行方式。

十一、端到端调用链：从 SDK 到 KV 存储

以"创建 → 列表 → 合并"的典型流程为例，完整调用链为：

Java SDK (PullsApi) → HTTP /api/v1/repositories/{repo}/pulls ... → pkg/api/controller.go（权限校验 + 参数归一化 + 日志统计） → pkg/catalog/catalog.go（业务校验：分支存在性、源目标一致性、状态过滤） → graveler Store（PullRequest 记录读写，最终落 KV 存储）

对应的服务端方法索引：

• HTTP 控制器：ListPullRequests（controller.go 5590）、CreatePullRequest（controller.go 5632）、GetPullRequest（controller.go 5668）、UpdatePullRequest（controller.go 5700）、MergePullRequest（controller.go 5723）；
• Catalog 业务层：CreatePullRequest（catalog.go 3362）、GetPullRequest（catalog.go 3340）、ListPullRequest（catalog.go 3424）、UpdatePullRequest（catalog.go 3491）。

当你在 Java 程序中调用mergePullRequest时，实际发生的远不止一次 HTTP PUT：服务端会依次完成 PR 状态校验、分支合并、PR 状态翻转与合并 commit 记录写入，最终返回给客户端一个可供后续引用的 commitreference——这正是把 lakeFS 的 Pull Request 变成数据湖 CI/CD 流水线中可靠一环的底层保证。

十二、实战建议

1. 保留 PR ID：创建成功后立刻保存PullRequestCreationResponse.getId()，后续查询、更新、合并都依赖它；
2. 合并前检查状态：调用getPullRequest确认status == open且mergedCommitId == null，避免对已关闭/已合并的 PR 发起合并而收到 400；
3. 列表分页要循环：PullRequestsList.pagination中的has_more为 true 时，用上一条结果的 PR ID 作为下一次请求的after游标，直到has_more为 false；amount建议保持在 100～1000 之间；
4. 权限规划：合并操作需要"目标分支的提交权限 + 仓库的 PR 写权限"双重授权，创建/更新需要 PR 写权限，查询需要 PR 读权限，请据此为服务账号配置最小权限策略；
5. 关注实验性标记：Pulls 相关接口在 OpenAPI 规范中标注为experimental，升级 lakeFS 服务端时留意该组接口的兼容性变化（例如 409 冲突响应体的格式调整已在文档中明确提示为弃用行为）。

通过上述方法与源码对照，你已具备用 Java SDK 完整驱动 lakeFS Pull Request 生命周期的能力——从分支上的数据变更，到发起评审、状态流转，再到最终合并为不可变的提交。

• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端