Jira REST Java Client (JRJC) 简介与自定义字段
Jira REST Java Client (JRJC) 是 Atlassian 官方提供的 Java 库，用于与 Jira REST API 进行交互。它封装了底层的 HTTP 请求和 JSON 解析，使得 Java 开发者能够更便捷地执行 Jira 操作，如创建、更新、查询 Issue 等。在 Jira 中，除了标准字段（如概要、描述、报告人）之外，自定义字段（Custom Fields）允许用户根据项目和业务需求添加额外的属性，这些字段对于捕获特定信息至关重要。
创建 Jira Issue 的基本流程
使用 JRJC 创建 Issue 的基本流程通常涉及构建一个 IssueInput 对象，其中包含项目的键、Issue 类型、概要和描述等信息。以下是一个典型的 Issue 创建代码示例：
import com.atlassian.jira.rest.client.api.JiraRestClient;
import com.atlassian.jira.rest.client.api.domain.IssueType;
import com.atlassian.jira.rest.client.api.domain.input.IssueInput;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 jira 实例已初始化为 JiraRestClient
JiraRestClient jira = /* ... 初始化 JiraRestClient ... */;
String projectKey = "TEST"; // 替换为你的项目键
String summary = "这是我的新 Issue 概要";
String description = "这是一个通过 JRJC 创建的 Issue 描述。";
// 获取 Issue 类型 ID
Long testIssueTypeId = getTestIssueTypeId(projectKey); // 假设此方法能获取到 Issue 类型 ID
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description);
IssueInput input = builder.build();
// 执行 Issue 创建
// return jira.getIssueClient().createIssue(input).claim();
System.out.println("Issue 创建请求已构建。"); // 实际创建会调用 .claim()设置自定义字段的常见挑战与错误分析
在上述基本流程中，如果需要设置自定义字段，开发者通常会尝试使用 IssueInputBuilder.setFieldValue() 方法。然而，在设置自定义字段时，一个常见的错误是遇到 RestClientException，状态码为 400 (Bad Request)，错误信息通常类似于：Field 'Test Type' cannot be set. It is not on the appropriate screen, or unknown.
// 尝试设置自定义字段的代码示例 (可能导致错误)
// 假设 'Test Type' 是一个自定义字段，且其选项 ID 为 14314
// import com.atlassian.jira.rest.client.api.domain.CustomFieldOption; // 可能需要引入
IssueInputBuilder builderWithCustomField = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 尝试使用自定义字段名称 'Test Type'
.setFieldValue("Test Type",
new CustomFieldOption(14314L, null, "Functional", null, null));
// 当执行 createIssue(builderWithCustomField.build()).claim() 时，可能抛出 RestClientException这个错误提示非常关键，它指出了两个主要原因：
- 字段不在适当的屏幕上 (Not on the appropriate screen): 这是最常见的原因。在 Jira 中，Issue 的创建和编辑页面是通过“屏幕方案”（Screen Scheme）配置的。如果某个自定义字段没有被添加到特定项目和 Issue 类型的“创建 Issue”屏幕上，那么即使通过 API 尝试设置其值，Jira 也会拒绝该操作，因为该字段在用户界面上是不可见的，也就不允许通过常规方式进行设置。
- 字段未知 (Unknown): 这通常意味着你提供的字段标识符不正确。对于自定义字段，JRJC 的 setFieldValue() 方法通常期望接收自定义字段的 ID (例如 customfield_10001)，而不是其 名称 (例如 "Test Type")。如果提供了错误的 ID 或名称，Jira 也无法识别该字段。
- 用户权限不足： 执行 API 操作的用户可能没有权限在指定项目或 Issue 类型中创建或编辑 Issue，或者没有权限修改该特定字段。
解决“字段无法设置”错误：屏幕配置与权限
要解决上述错误，需要从 Jira 配置和 API 调用两方面入手：
1. 检查 Jira 屏幕配置
这是解决“字段不在适当的屏幕上”问题的核心。
- 步骤一：确定项目和 Issue 类型。 明确你要创建 Issue 的项目和 Issue 类型。
-
步骤二：检查屏幕方案。
- 作为 Jira 管理员，进入 Jira 管理 > Issue > 屏幕。
- 找到与你的项目和 Issue 类型关联的“屏幕方案”（Screen Scheme）。
- 进入该屏幕方案，查看“创建 Issue 操作”（Create Issue Operation）所使用的屏幕。
- 进入该屏幕，确认你的自定义字段（例如“Test Type”）是否已添加到该屏幕中。
- 步骤三：添加自定义字段到屏幕。 如果字段不在屏幕上，请将其添加到相应的屏幕中。保存更改后，Jira 将允许通过 API 设置该字段。
2. 验证用户权限
确保用于 JRJC 连接的 Jira 用户账户具有以下权限：
- 在目标项目中 创建 Issue 的权限。
- 在目标 Issue 类型中 编辑 Issue 的权限（如果字段是可选的，或者在创建后需要立即更新）。
- 浏览项目 的权限。
JRJC 中自定义字段的正确设置方法
一旦 Jira 配置（屏幕和权限）正确，我们就可以通过 JRJC 正确设置自定义字段了。关键在于使用自定义字段的 ID 而非其名称，并根据字段类型提供正确的值格式。
1. 获取自定义字段 ID
在 JRJC 中设置自定义字段时，setFieldValue() 方法需要自定义字段的唯一 ID，格式通常为 customfield_XXXXX。获取这个 ID 的最可靠方法是通过 Jira REST API 浏览器或 Jira 管理界面：
-
Jira 管理界面：
- 作为 Jira 管理员，进入 Jira 管理 > Issue > 自定义字段。
- 找到你的自定义字段（例如“Test Type”），将鼠标悬停在字段名称上，通常浏览器底部会显示一个链接，其中包含 fieldId=customfield_XXXXX。
-
Jira REST API 浏览器：
- 访问你的 Jira 实例的 /rest/api/2/issue/createmeta?projectKeys=YOUR_PROJECT_KEY&issuetypeNames=YOUR_ISSUE_TYPE_NAME&expand=projects.issuetypes.fields URL。
- 替换 YOUR_PROJECT_KEY 和 YOUR_ISSUE_TYPE_NAME 为实际值。
- 在返回的 JSON 中，查找你的自定义字段名称，其旁边会显示对应的 fieldId。
例如，如果“Test Type”的 ID 是 customfield_10002，那么在 JRJC 中就应该使用这个 ID。
2. 不同类型自定义字段的设置示例
示例一：设置选择列表（Select List）类型的自定义字段
对于单选或多选列表，通常需要提供选项的 ID 或值。如果 JSON 示例中显示 value:"NA:12345" 和 id:"14314"，这意味着你可以通过 CustomFieldOption 对象来设置。
import com.atlassian.jira.rest.client.api.domain.CustomFieldOption;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 customFieldIdForApplication 是 "customfield_10001"
String customFieldIdForApplication = "customfield_10001";
Long optionId = 14314L; // 选项的 ID，来自 Jira 配置或 createmeta
String optionValue = "NA:12345"; // 选项的显示值或内部值
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 正确使用自定义字段 ID，并提供 CustomFieldOption 对象
.setFieldValue(customFieldIdForApplication,
new CustomFieldOption(optionId, null, optionValue, null, null));
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义字段 'Application' 构建 Issue 创建请求。");注意事项： CustomFieldOption 构造函数中的 id 和 value 参数是关键。id 是选项的唯一标识符，value 是选项的显示文本。根据 Jira 版本和字段配置，有时只需要提供 id，有时则需要同时提供 id 和 value。通过 createmeta API 可以查看字段期望的 JSON 结构。
示例二：设置文本（Text Field）类型的自定义字段
对于单行文本、多行文本或 URL 字段，直接提供字符串值即可。
// 假设 customFieldIdForText 是 "customfield_10003"
String customFieldIdForText = "customfield_10003";
String customFieldValue = "这是一个自定义文本字段的值。";
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 直接提供字符串值
.setFieldValue(customFieldIdForText, customFieldValue);
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义文本字段构建 Issue 创建请求。");示例三：设置用户选择器（User Picker）类型的自定义字段
对于用户选择器，需要提供 BasicUser 或 User 对象。
import com.atlassian.jira.rest.client.api.domain.BasicUser;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 customFieldIdForUserPicker 是 "customfield_10004"
String customFieldIdForUserPicker = "customfield_10004";
String username = "jirauser"; // Jira 用户的用户名或 accountId
// 可以通过 JiraRestClient 获取 BasicUser 对象
// BasicUser assignee = jira.getUserClient().getUser(username).claim();
// 如果没有现成的 BasicUser，可以手动构造一个，但确保 username 正确
BasicUser selectedUser = new BasicUser(null, username, username, null);
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
.setFieldValue(customFieldIdForUserPicker, selectedUser);
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义用户选择器字段构建 Issue 创建请求。");最佳实践与故障排除
- 始终使用自定义字段 ID： 避免使用自定义字段的名称，因为名称可能重复或更改，而 ID 是唯一的。
-
利用 createmeta API： 在开发和调试阶段，强烈建议使用 Jira REST API 的 createmeta 端点来检查特定项目和 Issue 类型下所有可创建字段的详细信息，包括它们的 ID、类型、是否必填以及期望的值格式。
- GET /rest/api/2/issue/createmeta?projectKeys={projectKey}&issuetypeNames={issueTypeName}&expand=projects.issuetypes.fields
- 这将返回一个 JSON 结构，其中包含每个字段的 fieldId、name、schema（包含 type 和 custom 属性）、allowedValues（对于选择列表等）等信息，是了解如何正确设置字段值的宝贵资源。
- 精确匹配值类型： 确保你通过 setFieldValue() 传入的值类型与 Jira 期望的字段类型匹配。例如，日期字段需要 DateTime 对象，数字字段需要 Integer 或 Double。
- 错误处理： 始终包含适当的 try-catch 块来捕获 RestClientException，并根据错误信息进行调试。错误消息通常会提供足够的信息来定位问题。
- Jira 版本兼容性： 确保使用的 JRJC 库版本与你的 Jira Server 版本兼容。不同版本的 Jira 可能对 REST API 有细微的改动。
总结
通过 JRJC 在 Jira Server 中设置自定义字段，核心在于理解 Jira 的屏幕配置机制、确保正确的用户权限，并使用自定义字段的唯一 ID。在编写代码之前，务必通过 Jira 管理界面或 createmeta REST API 确认自定义字段的 ID 及其期望的值格式。遵循这些最佳实践，可以有效避免常见的“字段无法设置”错误，并成功地通过编程方式管理 Jira Issue 的自定义属性。
