简介这是一款面向 JIRA 普通用户的批量建单插件基于 Java 开发允许从 CSV 文件一次导入并创建多个问题同时保留 JIRA 自身的字段校验与权限控制。与一般导入器不同它会强制校验必填字段与业务约束适合需要批量录入测试用例、运维工单或表单数据的团队。压缩包共 93 个文件大小约 11.99MB以 32 个 Java 源码文件为核心辅以 14 个 CSV 样例模板、11 个 Velocity 页面模板、6 个前端 js/css、6 个 XML 配置和 2 个 psd 图标源文件从后端接口到页面样式均有覆盖。包内含有完整项目目录、README 与测试数据读者可沿着代码了解 CSV 如何被解析并映射到 JIRA 问题字段也可自行调整模板或样式来适配个性化的批量录入流程降低从零开发 JIRA 插件的学习门槛。目前已有 725 人学习下载对从事 JIRA 二次开发或需要用脚本化方式管理工单的技术人员有直接参考价值。1. 批量创建 JIRA 问题一个 CSV 文件加一个插件普通用户也能一次建几十条某测试团队在提测前收到一份 200 行的缺陷清单需要逐条录进 JIRA但没人给测试组开管理员权限批量导入数据只能等管理员抽空处理一等就是大半天。这个名为 bulk-create-issues-for-jira 的插件解决的就是这种场景JIRA 普通用户不需要任何后台权限只需要上传一个 CSV 文件就能一次创建多个问题。反直觉的是插件全程不绕过任何权限校验项目不可见、字段不可用JIRA 拒绝的理由和用户在页面上建单完全一致。它更像给普通用户配了一个“手速放大器”适合 QA、运营、客服这类每天批量录入工单的团队。2. 插件全景从 CSV 上传到 JIRA REST API 的完整数据链路2.1 功能边界批量建单插件只管四件事这个插件表面看是一个页面入口实际拆开是四个职责清晰的模块。模块核心职责刻意不做的事CSV 读取去 BOM、识别编码、按列建立索引不负责业务数据是否合法字段映射把 CSV 列名翻译成 JIRA 字段 key不支持字段联动、级联、公式批量提交逐条调用创建问题的 REST API不做整批事务回滚结果报告按原始行号反馈成功与失败原因不自动重试 400 类业务错误把“不做什么”写清楚是因为批量导入类工具最容易引发误解。使用者天然会以为插件能绕过权限、能自动补必填字段、能更新已有问题甚至能批量删除。实际上这个插件只做一件事——把用户在界面上逐条点击“创建问题”的操作换成程序按 CSV 行循环提交。权限校验发生的位置和页面完全一样项目是否能建、问题类型是否可用、字段是否必填全部由 JIRA 后端决定。所以插件不会成为权限后门它需要的是一个已经能建单的普通用户身份再把这个身份的手速放大几十倍。典型操作流程是这样登录 JIRA 后进入插件页面选择目标项目上传 CSV 文件插件解析前 20 行做映射预览用户确认“CSV 某一列对应 JIRA 哪个字段”后进入提交阶段提交完成后结果报告按行号列出成功与失败原因。整个流程里唯一的新增动作是“上传 CSV 和确认映射”其余和用户手工建单的权限判断路径是重叠的。2.2 技术选型Servlet 入口 公开 REST APIJIRA 插件开发一般有两种入口Servlet 和 REST 端点。这个插件选择 Servlet主要原因是页面要走 multipart 文件上传、映射预览、进度刷新这一套交互Servlet 在 JIRA 插件框架里集成起来更直接不需要绕注解扫描。选型用在哪为什么这么选Java 8全部后端逻辑JIRA Server 插件的主流基线Maven工程构建JIRA 插件 SDK 默认就是 MavenOpenCSVCSV 解析引号、转义、字段内换行处理比手写 split 稳定JacksonJSON 序列化避免手拼 JSON 字符串导致转义问题REST API/rest/api/2/issue创建问题与页面同一条通道不依赖内部私有接口这里有一个关键决定创建问题不直接用 JIRA 内部的 IssueService而是请求公开的 REST API。理由有两条。第一REST API 是稳定的对外契约大版本升级后基本不变插件生命周期更长内部 Service 接口经常随版本重构一旦插件里调用的方法签名变了整个插件可能在升级后无法加载。第二REST API 会完整走一遍权限校验和字段校验和用户在界面上操作结果等价不容易出现“程序能建但页面不能建”的权限黑洞。关于身份上下文要说明一下插件发起 REST API 调用时必须使用当前登录用户的身份而不是配置一个管理员账号在后台创建。如果用一个固定管理员 token 去建单等于给所有普通用户开了一个提权通道这是批量导入工具最容易踩的红线。实际实现时Servlet 从当前会话拿到用户凭证再用带凭证的 HTTP 客户端请求同机 REST 接口嫌麻烦也可以直接注入 IssueService 走内部接口效果一样只是升级兼容性略差。2.3 工程目录结构与主流程工程结构按功能分包避免把所有逻辑塞进一个 Servletsrc/main/java/com/example/bulkcreate ├── servlet │ └── BulkCreateServlet.java # 上传与导入入口 ├── csv │ ├── CsvParser.java # CSV 解析、BOM、编码 │ └── CsvColumnMapping.java # 列名到 JIRA 字段的映射表 ├── mapping │ ├── FieldMapper.java # 字段值转换接口 │ ├── SimpleFieldMapper.java # 摘要/描述等透传字段 │ ├── SelectFieldMapper.java # 单选字段包装成 {name: ...} │ └── DateFieldMapper.java # 日期格式归一化 ├── jira │ └── JiraClient.java # 封装创建问题 REST 调用 ├── model │ ├── ImportRow.java # 单行数据 原始行号 │ └── ImportReport.java # 成功/失败结果 └── config └── PluginConfig.java # 字段映射与项目配置主流程按四步推进每步都有对应的页面状态。上传阶段只做两件事把 CSV 存成临时文件解析出表头预览阶段读取前 20 行数据根据配置自动匹配列名用户要在这里确认项目 key 和问题类型提交阶段按批次循环调用 REST API并把每行结果写进 ImportReport报告阶段把成功 key、失败行号和原因按原始行号回显。初次接入最常见的问题集中在预览阶段——目标项目没有出现在下拉框里几乎都是因为当前登录用户对这个项目没有创建问题的权限这是 JIRA 行为不是插件 Bug。3. 核心模块拆解CSV 解析、字段映射与批量提交3.1 CSV 解析模块先解决 BOM 和编码再谈映射实战里最容易翻车的是编码不是解析。中文 Windows 的 Excel 导出的 CSV 默认是 GBK 编码Mac 和 Linux 上又常常是 UTF-8 带 BOM。如果程序固定按 UTF-8 读GBK 文件第一行表头就会乱成一团严重时全部列名对不上映射。所以解析器的第一步是识别并跳过 BOM再保留一个按 GBK 重试的兜底路径。public ListImportRow parse(InputStream in) throws IOException { PushbackInputStream pb new PushbackInputStream(in, 3); byte[] head new byte[3]; int read pb.read(head); boolean hasBom read 3 (head[0] 0xFF) 0xEF (head[1] 0xFF) 0xBB (head[2] 0xFF) 0xBF; if (!hasBom) { // 不是 BOM 就把读走的字节还回去保证后续解析不丢内容 pb.unread(head, 0, read); } Reader reader new InputStreamReader(pb, StandardCharsets.UTF_8); try (CSVReader csv new CSVReaderBuilder(reader).build()) { // 第一行作为表头trim 后建立 列名 - 下标 索引 String[] header csv.readNext(); for (int i 0; i header.length; i) { header[i] header[i].trim().toLowerCase(); } String[] line; while ((line csv.readNext()) ! null) { if (isBlank(line)) { continue; // 跳过空行避免空行变成一条空白问题 } rows.add(new ImportRow(line, rowIndex)); } } }这段代码做三件事。用 PushbackInputStream 预读三个字节判断是不是 UTF-8 BOM如果不是把字节 unread 回去保证后续 CSV 解析不受影响表头 trim 后统一转小写建立列名到数组下标的索引。表头 trim 必须在建立索引之前完成否则索引 key 还带着空格后面映射怎么都对不上。转小写是为了匹配“Summary”和“summary”这种大小写差异用户从不同系统导出的表头往往风格不一致。说说为什么不直接用 CSV 库的编码参数。很多 CSV 库不主动处理 BOM尤其是国内环境常见的 Excel 导出文件带 BOM 会让第一列列名多一个不可见字符映射接口失效得毫无提示。所以去 BOM 放在解析器最前面不依赖 CSV 库。整体解析过程中如果出现大量替换字符形如“锟斤拷”常见做法是把文件按 GBK 再读一遍把两种解析结果并排展示给用户选择而不是自动切换编码。自动猜编码在数据量大时偶尔翻车让用户选一次最直接。另外CSV 字段里允许换行和逗号这是 Excel 导入场景的基本盘。处理这类内容不建议用 line.split(,)正确做法是用 OpenCSV 这类库它能根据引号和转义符正确切分带逗号、带换行的字段。如果自己写正则遇到描述里带引号的日志会切得支离破碎。3.2 字段映射模块把 CSV 行翻译成 JIRA 的 fields 对象CSV 的列名和 JIRA 字段名通常对不上比如表头写“严重级别”JIRA 里是 priority表头写“发生日期”对应的是某个自定义字段。映射模块维护一张配置表把 CSV 列名翻译成 JIRA 字段 key再用不同的 FieldMapper 处理不同类型的值。{ project: WEB, columns: { 标题: { field: summary }, 严重级: { field: priority, type: select }, 发生日期: { field: customfield_10021, type: date }, 模块: { field: components, type: array-select } } }这个配置的意思是CSV 里“标题”列写给 summary“严重级”列写给 priority按单选字段处理“发生日期”列写给自定义字段 customfield_10021按日期字段处理。不同字段类型最终给 REST API 的 payload 结构完全不一样。单选字段要包一层 name数组字段要包一层数组日期字段要先做格式归一化。public class SelectFieldMapper implements FieldMapper { Override public Object toJiraValue(String rawValue) { // JIRA 单选字段要求包 {name: ...}直接传字符串会报 400 return Collections.singletonMap(name, rawValue.trim()); } }单选字段是批量导入最容易报错的地方。JIRA REST API 接受的值是 {name: High}直接传字符串会被拒绝。数组字段组件、标签、多选则在此基础上再套一层 List每个元素都是一个 {name: ...}。SimpleFieldMapper 负责摘要、描述这类透传字段但透传不等于不过滤——描述里可能带换行和制表符最后统一交给 Jackson 序列化时处理绝不手写字符串拼接。还有一点要说明白映射配置是按“项目 问题类型”的维度存的因为不同项目的必填字段不一样。某个项目创建 Bug 时必填“影响版本”映射配置就要给这个项目单独加一行 version 的映射。预览页上用户确认完映射再提交遇到必填字段缺失的行在提交前就能标出来而不是等提交后一条条报错。这种“先校验再提交”的顺序比把校验堆在 REST API 的报错里要省事得多。3.3 批量提交模块失败隔离是批量导入的灵魂批量创建没有现成的批量事务接口最稳妥的实现就是循环调用单条 REST API。这里的核心设计是失败隔离第 10 行失败不影响第 11 行继续提交。public void submit(ListImportRow rows, ImportReport report) { for (int i 0; i rows.size(); i) { ImportRow row rows.get(i); try { HttpResponse resp jiraClient.createIssue(row.buildPayload()); if (resp.isSuccess()) { report.addSuccess(row, resp.getKey()); } else { // 400 这类业务错误重试多少次都是同样的结果 report.addFailure(row, resp.getErrorMessage()); } } catch (TimeoutException e) { // 网络超时可以重试一次先记进待重试列表 report.addRetryable(row); } catch (Exception e) { report.addFailure(row, e.getMessage()); } } }这里把超时和业务拒绝分开处理因为两者的恢复策略完全不同。超时重试一次就够了重试前等几百毫秒避免把 JIRA 负载打上去400 类业务错误重试多少次都一样直接记录到失败列表。report 会保留原始 CSV 行号结果页能精确显示“第 37 行失败优先级字段不允许为空”而不是笼统的“部分失败”。批量提交还有一个隐含的配额问题。JIRA 在高并发创建时响应会明显变慢常见做法是控制单位时间内的提交量。这里默认一批 50 条配合循环里的短暂 sleep相当于给 JIRA 留出处理余量。sleep 时间不需要很长几百毫秒对几百行的数据总量影响不大但对 JIRA 的 CPU 和数据库压力是质变。如果 JIRA 实例负载高把批次调小到 20实例配置好可以放宽到 100这个参数抽到配置里不要写死在代码中。失败隔离还带来一个额外好处导入可以重跑。报告里给出失败行号用户修好 CSV 对应行后把失败行重新导入一遍成功行不会重复创建。这比“要么全部成功要么全部失败”的强事务设计实用得多因为 JIRA REST API 本来就没有跨行的回滚能力强行做事务只会让一次翻车拖垮整批数据。4. 从源码到运行编译、安装与参数配置4.1 环境准备JDK 版本与插件描述文件JIRA 插件本质上是一个 Maven 工程基础环境需要 Java 8 或 11跟着当前 JIRA Server 的主版本要求走Maven 3.6。插件描述文件 atlassian-plugin.xml 负责把 Servlet 注册到指定路径atlassian-plugin keycom.example.bulk-create-issues nameBulk Create Issues plugin-info descriptionAllow normal users to create issues from CSV file/description vendor nameExample Team/ /plugin-info servlet keybulk-create-servlet classcom.example.bulkcreate.servlet.BulkCreateServlet url-pattern/bulk-create/url-pattern /servlet /atlassian-pluginservlet 在 JIRA 插件里默认对登录用户可见但代码里要显式校验当前用户避免匿名请求进入。大多数插件会在 servlet 类上加 RequireJiraUser 注解JIRA 在请求进入之前先做登录校验。没有这个注解插件页面可能被匿名访问到虽然 JIRA 后端 API 会二次拦截但页面本身应该先挡住。这里的“普通用户可用”指的是不要求管理员权限但必须登录 JIRA登录身份就是后续所有 API 调用的身份。依赖方面pom.xml 里要声明 JIRA 插件 SDK 提供的系统依赖范围。特别注意 jira.version 这个属性它决定编译时引用哪个版本的 JIRA API 类。如果在一个老版本 JIRA 实例上部署用新版本 API 编译的插件加载阶段就可能因为类不存在直接失败反过来在新版 JIRA 上跑旧版编译的插件又可能出现接口行为不一致。这个坑不比业务代码少第一次接入最好拉一个本地测试实例验证。页面前端不用复杂框架一个 JSP 模板加 WebResource 声明就够。Servlet 接收 multipart 上传后直接把解析预览渲染成页面提交阶段用轻量 JSON 接口回报进度。把前端资源声明在 atlassian-plugin.xml 的 web-resource 节点里JIRA 会自动带上上下文路径避免手写资源路径导致 404。二次开发时不用担心前端工程化这个项目的页面层就是普通 Java Web 那套。4.2 编译打包与安装编译命令很简单mvn clean package -DskipTests # 产物在 target/ 目录下文件名形如 bulk-create-issues-for-jira-version.jarjar 生成后进入 JIRA 管理后台的应用插件管理页上传这个 jar。JIRA 会解析 atlassian-plugin.xml 并注册 servlet导航里出现插件入口。新装插件一般热加载不需要重启 JIRA。注意同一个实例反复上传新 jar 后如果页面样式或接口表现异常先重启 JIRA 再排查。本地联调阶段可以不用手工上传。JIRA 插件 SDK 提供的 atlas-run 命令会拉起一个带测试数据的本地 JIRA 实例代码改动自动同步适合反复验证atlas-run --product jira --version 8.x这段命令里的 8.x 要替换成当前目标 JIRA 的主版本号。atlas-run 启动的实例用的是 H2 内存数据库重启后数据不保留但用来验证插件加载、CSV 导入流程完全够用。真正要在真实数据上验证还是得部署到测试 JIRA 实例因为本地实例的数据和权限配置与生产差异很大。4.3 一次完整导入的参数清单与操作步骤准备一个最简单的 CSV第一行表头后面每行一条问题summary,issuetype,priority,description 登录页白屏,Bug,High,打开登录页后页面空白 导出无数据,Bug,Medium,导出按钮点击后无文件导入时插件页面上的关键参数如下参数说明示例目标项目无权限的项目直接过滤不会出现WEB问题类型默认取 CSV 里 issuetype 列BugCSV 文件UTF-8 或带 BOMGBK 也能兜底defect.csv映射预览确认每列对应 JIRA 字段summary → 摘要确认映射后点提交结果报告分三块成功列表含新问题 key、失败列表行号 原因、待重试列表超时行。200 条数据的实际耗时取决于 JIRA 响应速度通常几分钟内完成。如果结果全是失败先去检查目标项目 key 和问题类型在这个项目里是否可用这两个字段错了会全军覆没。还有一个实用的检验习惯第一次导入先取 5 行样本跑一遍确认映射和字段没问题再放全量。样本导入的成功率基本就是全量的上限。5. 避坑指南CSV 批量建单最容易翻车的五个场景CSV 批量建单翻车十有八九不是 JIRA 配置问题而是 CSV 文件本身和 REST API 的交互细节问题。下面五条是从几轮接入中反复遇到的真实场景里拎出来的按“现象 → 原因 → 解决”三条线展开每一条都能直接在导入时对上号。5.1 Excel 导出 CSV 后中文乱码现象上传后页面预览里表头和正文全是乱码“登录页”变成“鐧诲綍椤”之类的替换字符。原因中文 Windows 的 Excel 默认按 GBK 编码保存 CSV插件按 UTF-8 解码字节流被错误映射到 Unicode 字符集。解决解析器先去 BOM没有 BOM 且出现明显乱码时把文件按 GBK 再解析一次让用户二选一。同时页面提示“建议另存为 CSV UTF-8 格式”。程序侧的兜底必须做不能只靠提示因为用户手里带着历史数据的 CSV 不会专门去改编码。判断乱码要在解析早期做不要等几千行数据全部解析完再发现表头不对。5.2 一提交就整批失败看不到是哪行错现象100 条数据提交后一个都没建成报错只有一句“createMeta failed: field not found”。原因字段映射配置里某个自定义字段 key 写错或者必填字段没填而提交程序在第一行失败时就中断了循环。解决把 try-catch 放在单条循环内逐条记录失败原因结果页显示“第 23 行失败customfield_10001 该字段必填”而不是一句笼统提示。这在代码层面就是 3.3 里那个设计不要因为图省事把整批包在一个 try 里。另外一个排查技巧先在 JIRA 界面上手工建一条问题看这个项目的必填字段到底有哪些再回来核对映射配置。页面上能建成功REST API 基本也能成功两边字段校验规则是同源的。5.3 日期字段填了 2024/1/5 被拒绝现象CSV 里日期写成 2024/1/5提交时 JIRA 报“Invalid date format”。原因JIRA REST API 的日期字段要求 ISO 格式 yyyy-MM-ddExcel 里常见的斜杠格式不在识别范围内。解决在 DateFieldMapper 里按 yyyy-MM-dd、yyyy/M/d、yyyy/M/dd、M/d/yyyy 多种格式尝试解析最终统一输出 ISO 格式。格式列表要放在配置里而不是写死在代码里这样后面遇到新的日期写法加一条配置就行不用动代码重新打包。解析失败时不要静默吞掉要把原始值和期望格式一起写进失败原因方便用户回看。5.4 表头带前导空格映射预览匹配不上现象CSV 第一列显示名是“ summary”前面有一个空格自动映射时这一列永远匹配不到 JIRA 的 summary 字段。原因表头从别处复制粘贴过来自带不可见空格解析时如果没做 trim列索引里的 key 就带着空格。解决在建立列索引之前统一 trim 表头同时大小写不敏感匹配。这里有一个顺序坑先建索引再 trim 是没用的索引里的 key 还是原值后面 mapping 按 trim 后的名字去找必然失配。检查时注意这类问题不要依赖用户在 Excel 里清理Excel 里看起来干净的表头未必没有空格程序侧兜底才可靠。5.5 描述字段含多行文本导致 JSON 报错现象description 列里用户复制了三行日志提交时报 400错误信息是 JSON parse error。原因CSV 字段里的换行符进入字符串后拼 JSON 时没有转义把 JSON 结构截断了。解决所有 payload 用 Jackson 序列化不要手写字符串拼接。同时 CSV 解析器要能正确识别带引号的字段OpenCSV 默认支持引号和双引号转义这一步不要自己用 split(,) 处理否则带逗号的描述也会被切断。一个直观的验证方法把失败的行单独复制成一小份 CSV用接口调试工具手动提交一次看到的错误信息会比插件结果页更完整适合定位是解析层问题还是字段值问题。对照这份清单导入前先跑 5 行样本把编码、表头、必填字段、日期格式都过一遍剩下的导入过程基本不会再出幺蛾子。失败行报告本身就是最好的排查入口看到哪行错、错在哪个字段比猜原因省太多时间。6. 二次开发实战加一个可配置的多格式日期映射器6.1 扩展点FieldMapper 是一个 Java 接口想加新字段类型不需要动 Servlet 和提交模块实现 FieldMapper 接口后在映射工厂注册即可public interface FieldMapper { Object toJiraValue(String rawValue); boolean supports(String jiraFieldKey); }supports 告诉映射工厂这个 mapper 负责哪些 JIRA 字段toJiraValue 把 CSV 字符串转成 REST API 接受的 Java 对象。改造日期支持时把原来只认 yyyy-MM-dd 的实现替换成多格式版本public class MultiFormatDateMapper implements FieldMapper { Override public boolean supports(String fieldKey) { return fieldKey.endsWith(date) || fieldKey.startsWith(customfield_); } Override public Object toJiraValue(String rawValue) { for (String pattern : Arrays.asList(yyyy-MM-dd, yyyy/M/d, yyyy/M/dd, M/d/yyyy)) { try { return LocalDate.parse(rawValue.trim(), DateTimeFormatter.ofPattern(pattern)) .format(DateTimeFormatter.ISO_LOCAL_DATE); } catch (DateTimeParseException ignored) { // 继续尝试下一种格式全部失败再抛异常 } } throw new MappingException(无法识别日期: rawValue); } }提示日期格式列表放在配置文件里后续遇到新格式只需加一行不用重新打包。改造完成后做两件事。第一是单测把 2024-01-05、2024/1/5、1/5/2024 各写一个断言确认输出都是 2024-01-05。第二是手动回归用前面那份缺陷清单 CSV 再跑一次清单里混着斜杠日期跑通就说明替换没有破坏原有流程。从那以后我每次改字段映射都会先在本地实例上跑一遍真实 CSV 再动手改代码改成后还要用同一份文件回归一次省掉了不少上线后才发现的对不齐问题。如果你正好在折腾 JIRA 批量导入这份工程可以直接拿起来跑把映射配置换成你项目里的真实字段就行。希望帮到你。本文还有配套的精品资源点击获取