企业官网建设流程全解析

简介：专为JIRA定制的一款批量建单插件，允许普通用户借助CSV文件一次创建多个问题，免去逐条手动录入的繁琐。所有问题均基于当前用户权限创建，并严格校验必填字段与业务约束，相比官方导入器更贴合实际配置要求，适合需要高频提交工单的团队或JIRA二次开发者。压缩包共93个文件，以32个Java源码为主体，辅以14个CSV示例数据、11个VM页面模板、6个JS与6个XML配置文件，另有PSD设计源图与CSS样式，整体约11.99MB。目前已有725人学习下载，内容包含完整Maven工程结构、测试资源及marketing素材，可直接编译部署或作为插件开发范本。通过阅读源码与CSV样例，可快速掌握JIRA问题字段配置、校验逻辑及REST/API集成思路，为批量导入场景提供可复用的落地参考。

1. 这个插件解决的是什么场景：权限收紧后的批量建单

如果你的团队在用 JIRA 管迭代，你会很快遇到一个矛盾：管理员有批量导入问题的权限，但真正每天要提单、维护需求池的往往是普通开发、测试和产品运营。这些普通用户没有 JIRA 管理后台的 bulk 操作入口，也没法用 Excel 一次性导入几十条 issue。于是最常见的情况是——大家把需求写在共享表格里，管理员收到表格后再一条条手打进 JIRA，费时间不说，误粘贴、漏行、字段填错简直是家常便饭。

这个插件要做的就是把「收集表格」和「落地 issue」打通：启动插件后，普通用户可以在 JIRA 的项目页面里直接上传一个 CSV 文件，配置文件按约定放好，系统批量读取、逐行校验、自动创建 issue，并且把每条导入的结果写回一张记录表。它的适用对象很明确，就是那些没有管理员后台权限、但需要批量建单的一线业务同学；而项目里涉及到的 JIRA API 调用、CSV 解析、异常回滚和结果回执，也是你在做一个完整的 JIRA 插件集成时绕不开的骨架代码。下文按「项目结构 -> API 调用 -> CSV 解析 -> 避坑 -> 改造」的顺序，把这个插件从头拆到尾。

2. 插件架构与项目结构：一个普通 JIRA 插件的完整骨架

2.1 与 JIRA 的集成方式

JIRA 插件通常有两种形态：一种是跑在 JIRA 服务端内部的 Java 插件（使用 Atlassian SDK 开发，打成 jar 上传安装）；另一种是通过 REST API 外部调用的独立服务。这个项目属于前者，它以 OSGi bundle 的方式部署到 JIRA 中，运行时调用的是 JIRA 内部的 Java API 和 Active Objects 数据库表，而不是走 HTTP 去请求自己的接口。这么选的直接好处是：用户权限可以直接复用 JIRA 的User与ProjectPermission体系，不需要自己再做一套登录和授权；另外插件能直接从当前登录用户上下文里拿到ApplicationUser对象，CSV 里的 reporter 配置也可以和真实用户做比对校验。

插件在一个工程里拆成了三个职责模块：.java源码层、atlassian-plugin.xml注册层、js前端入口层和数据库迁移文件层。源码里最核心的接口是BulkCreateService，它接收一个 CSV 文件流、一个项目 Key 和当前用户，返回一个包含成功数、失败数和每条错误原因的结果对象。前端部分是用 JIRA 的 Web Panel 或 Servlet 提供上传入口，点击上传后文件流被提交到后台 Servlet，再由BulkCreateService调度解析器和 issue 创建器。

2.2 目录结构与模块职责

拆开工程目录看，每个包负责的事情非常清楚：

src/main/java/ com/example/bulkcreate/ servlet/ UploadServlet.java // 接收前端上传的 CSV 文件 service/ BulkCreateService.java // 协调解析与创建，返回结果集 IssueCreateService.java // 单条 issue 创建，封装 JIRA API csv/ CsvParser.java // 解析 CSV，生成行对象 CsvRow.java // 单行数据的字段模型 model/ BulkCreateResult.java // 结果汇总模型 ImportError.java // 单条失败原因模型 src/main/resources/ atlassian-plugin.xml // 插件描述符，注册 servlet/AP/权限 js/ bulk-create.js // 前端逻辑：文件选择、上传、结果展示 css/ bulk-create.css db/ create-records-table.xml // Active Objects 建表迁移文件

从结构上可以看到，这个插件没有把代码堆在一个类里，而是把「上传入口」「解析器」「业务服务」拆开。这样做的目的很直接：如果你以后想增加 Excel 格式导入，只需要在service层加一个ExcelParser，再在BulkCreateService里做一个格式判断，前端和 issue 创建逻辑都不用动。同样，如果你想把导入历史存进 JIRA 的数据库以便复查，可以直接沿用BulkCreateRecord这个 Active Objects 实体。

2.3 插件描述符 atlassian-plugin.xml

atlassian-plugin.xml是 JIRA 插件能否被识别和授权的前提。关键配置有两块：一是定义了前端资源（web-resource），二是把UploadServlet注册成了可访问的 URL，同时还声明了权限验证方式。这里贴出核心部分：

<atlassian-plugin key="com.example.bulkcreate" name="Bulk Create Issues"> <plugin-info> <description>CSV batch create issues for JIRA</description> <vendor-name>Example</vendor-name> <version>1.0.0</version> </plugin-info> <servlet key="upload-servlet" name="Upload Servlet"> <url-pattern>/bulk-create/upload</url-pattern> <description>Handle CSV upload</description> </servlet> <web-resource key="bulk-create-resources"> <resource type="download" name="bulk-create.js" location="/js/bulk-create.js"/> <resource type="download" name="bulk-create.css" location="/css/bulk-create.css"/> <context>jira.project</context> </web-resource> </atlassian-plugin>

web-resource里的context决定前端资源出现在哪个页面，jira.project表示只出现在项目页面，这样用户进入具体项目后可以直接看到「批量导入」入口。servlet的url-pattern必须写完整路径，建议带插件自己的前缀，避免和别的插件冲突。servlet默认没有做额外登录校验，因为它跑在 JIRA 域内，JIRA 自身的 session 会先过滤掉未登录请求；但插件内部仍然要查一遍当前用户对目标项目的建单权限，这部分逻辑在IssueCreateService里完成。

3. 核心模块拆解：一次 CSV 导入从上传到 issue 落库的完整链路

3.1 前端触发：上传文件并提交到 Servlet

前端的入口是一个简单的表单。用户在项目页面点击「批量导入」后，bulk-create.js读取选中的 CSV 文件，用 FormData 把文件流直接 POST 给/bulk-create/upload，并在请求参数里带上目标projectKey。这里没有用 AJAX 轮询或分片上传，因为 CSV 文件一般不会很大，几 MB 以内一次提交基本不会有超时问题。

const uploadCsv = (file, projectKey) => { const formData = new FormData(); formData.append('file', file); formData.append('projectKey', projectKey); fetch('/rest/bulk-create/1.0/upload', { method: 'POST', body: formData }) .then(res => res.json()) .then(result => renderResult(result)) .catch(err => alert(`上传失败：${err.message}`)); };

这个接口路径里的/rest/前缀不是 JIRA REST API，而是插件自己注册的 servlet 别名路径，实际路由由插件 key 和 url-pattern 拼接决定。projectKey由页面隐含字段带入，写死在前端并不安全，所以后端会再次校验当前用户是否具备该项目的CREATE_ISSUES权限。如果校验失败，返回 JSON 里的successCount为 0，但错误列表会给出权限不足的提示。

3.2 后端解析：CsvParser 把文本行映射成字段对象

CSV 解析是这个项目里最容易翻车、也最值得逐行讲的部分。项目里的CsvParser并没有引入 OpenCSV 这类第三方库，而是直接用 BufferedReader 按行读取，再用逗号切分。这么做的一个实际考虑是插件运行在 JIRA 的 OSGi 容器中，引入额外依赖需要处理包导入声明，稍不注意就会出现ClassNotFoundException。自写一个短解析器，可控性更高。

public List<CsvRow> parse(InputStream inputStream) throws IOException { List<CsvRow> rows = new ArrayList<>(); BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8)); String headerLine = reader.readLine(); if (headerLine == null) { throw new IllegalArgumentException("CSV 文件为空"); } String[] headers = headerLine.split(",", -1); String line; int lineNumber = 1; while ((line = reader.readLine()) != null) { lineNumber++; if (line.trim().isEmpty()) { continue; } String[] values = splitCsvLine(line, headers.length); rows.add(new CsvRow(headers, values, lineNumber)); } return rows; }

splitCsvLine的处理逻辑要考虑带引号的字段。例如描述里有逗号，像"新增用户头像, 并增加缓存"，如果简单按逗号 split 就会错位。项目中采用了一个小状态机：遇到双引号时开启「引号内模式」，引号内的逗号不切分，遇到下一个引号再退出。这能覆盖大多数从 Excel 导出的 CSV 场景。但如果单元格内容包含换行，这种逻辑处理不了——规范做法是告知用户先处理掉单元格内的换行符，避免解析错行。

CsvParser返回的是List<CsvRow>，每个CsvRow内部持有的是headers和values两个数组，以及原始行号。原始行号非常重要，后面创建失败时，错误信息里能准确告诉用户「第 12 行创建失败」，而不是让人去数文件。

3.3 单条 issue 创建：调用 JIRA Java API 封装

创建 issue 的核心在IssueCreateService。这段代码用的是 JIRA 7.x 之后的IssueService接口。有人会问，为什么不直接用IssueManager？因为IssueService会做权限校验和数据校验，直接使用IssueManager相当于绕过了业务规则校验，导致创建出来的 issue 可能缺少必填字段，或者严重越权。项目中明确使用IssueService，这一点对插件这种场景来说是必须的——它要承接普通用户的输入，必须走完整校验链。

public IssueService.CreateValidationResult createIssue(String projectKey, String summary, String description, String reporter, String priority, ApplicationUser currentUser) { IssueInputParameters params = issueService.newIssueInputParameters(); params.setProjectId(projectKey) .setIssueTypeId("10002") .setSummary(summary) .setReporterId(reporter) .setDescription(description) .setPriorityId(priority); CreateValidationResult validationResult = issueService.validateCreate(currentUser, params); if (validationResult.isValid()) { issueService.create(currentUser, validationResult); } return validationResult; }

setIssueTypeId("10002")里的10002是当前 JIRA 实例中某个 issue 类型的 ID。不同实例里 ID 不同，所以项目在配置里把这个值做成了可配置项，由插件管理员在后台设定。setReporterId中的 reporter 是从 CSV 传过来的用户名，这里有个隐藏风险——如果 CSV 中的 reporter 不是 JIRA 里的有效用户，validateCreate会直接校验失败。很多初次使用插件的用户会在这卡住，看到一条「用户不存在」的错误。解决办法是在解析阶段就查一次UserUtil，发现无效用户直接标记，而不是到创建阶段才报。

validateCreate返回的CreateValidationResult里带有逐字段的错误信息，项目会把validationResult.getErrors()收集起来，转成ImportError塞进结果集。这样即使用户一次导入了 200 行，每一行的失败原因是「负责人不存在」「摘要为空」「优先级非法」，都能在回执里分门别类地看到，不至于 200 行里失败 30 行时一脸懵。

3.4 批量调度：逐条创建 + 收集错误，不中断整体导入

BulkCreateService是整个插件的编排者。它的循环逻辑中有一个设计选择值得单独说：遇到失败行是立即中断还是继续？这个项目的答案是「继续」。因为批量导入的典型场景是一次性处理上百条需求，如果第 3 行失败就中断，后面 97 条会被阻塞，改完 CSV 后又要重新上传整个文件，体验极差。相反，逐条创建、逐条收集错误，最后一次性返回结果，用户只需要对照错误列表修改对应行，然后重新上传出错的部分。

public BulkCreateResult bulkCreate(InputStream csvStream, String projectKey, ApplicationUser user) { List<CsvRow> rows = csvParser.parse(csvStream); BulkCreateResult result = new BulkCreateResult(); if (rows.isEmpty()) { result.addError("文件没有有效数据行"); return result; } for (CsvRow row : rows) { try { IssueService.CreateValidationResult validationResult = issueCreateService.createIssue( projectKey, row.get("summary"), row.get("description"), row.get("reporter"), row.get("priority"), user ); if (validationResult.isValid()) { result.incrementSuccess(); } else { Map<String, String> errors = validationResult.getErrors(); result.addError(new ImportError(row.getLineNumber(), errors.toString())); } } catch (Exception e) { result.addError(new ImportError(row.getLineNumber(), e.getMessage())); } } return result; }

外层 try-catch 包住单行创建，作用是隔离单行异常。即使validateCreate本身因为意外情况抛异常，也不会拖垮后续行。有一点要注意：这个循环是单线程顺序执行的，200 行的耗时大约在几十秒级别。如果将来要支持上千行，建议改成线程池分批提交，但必须注意 JIRA 的IssueService实现并不是所有版本都线程安全，贸然并发可能引入数据一致性问题。

4. CSV 格式约定与字段映射：导入规则怎么定，解析器才不会翻车

4.1 第一行必须是表头

这个项目约定 CSV 第一行为表头行，支持的中文字段名有摘要、描述、负责人、优先级、组件，也可以使用英文summary、description、reporter、priority、components。CsvParser把第一行读入headers数组，之后用户写配置时可以直接说「把 Excel 的第一行改成这个表头」，而不需要理解什么字段映射概念。

必须提醒一点：CSV 文件的编码必须是 UTF-8。如果用户从 Windows 版 Excel 直接「另存为 CSV」，默认生成的是 ANSI 编码，用 UTF-8 读取时中文会变成乱码，导致创建的 issue 标题出现一堆「测试」之类的内容。项目里对文件编码做了检测，在读取前判断 BOM 头，遇到非 UTF-8 就直接返回提示，而不是用错误数据创建一堆乱码 issue。

4.2 支持的自定义映射配置

除了使用固定表头之外，项目还留了一个进阶能力：在插件后台配置一个字段映射 JSON，把 CSV 的任意列名映射到 JIRA 的字段 ID。这个设计是为了兼容用户已有的 Excel 模板——每个团队的现成表格列名各不相同，有的是「问题描述」，有的是「需求明细」，如果不支持自定义映射，强迫所有人改表头，推广阻力会非常大。配置片段如下：

{ "summary": "标题", "description": "详细描述", "reporter": "提出人", "priority": "紧急程度" }

解析时CsvRow.get("summary")会先去查映射配置，如果配置里把summary指向了真实列名标题，就从对应列取值。实现上就是用配置 Map 把表头统一成规范字段名，再让IssueCreateService只认规范字段名。这样职责隔离得很清楚：解析器只负责「把任意列名变成规范字段」，创建服务只关心「从规范字段取值并传给 JIRA API」。

4.3 必填字段校验前置

CSV 的行内容五花八门，空行、多余空格、全角逗号都可能出现。项目在解析后立刻做一次基础体检，而不是把脏数据送到 JIRA 那里由 validate 统一报错。基础体检输出几种典型错误：摘要列为空、负责人带有前后空格、优先级不存在。这里有一个小技巧：

private String clean(String value) { if (value == null) { return ""; } return value.trim().replace("\uFEFF", ""); }

\uFEFF是 BOM 字符，在很多从 Excel 导出的 CSV 中，第一行第一个字段前面会带着这个隐藏字符。如果不清理，第一行创建的 issue 标题前面会多出一个不可见字符，JIRA 上看不出来，但搜索时就是匹配不到。加上replace("\uFEFF", "")之后，这个问题被彻底解决。我从维护类似插件的血泪经验里总结出这条：凡是用户上传的文件，永远先清 BOM、清首尾空格、统一换行符，再做业务校验。

5. 常见问题与避坑记录：插件装好、文件传对了，依然可能翻车的几个地方

5.1 上传文件 404：Servlet 路径和 alassian-plugin.xml 不一致

现象：前端页面能正常打开，但点击上传后请求返回 404，Network 面板里看到请求地址是/bulk-create/upload，后台日志也不见打印任何内容。

原因：atlassian-plugin.xml中<url-pattern>/bulk-create/upload</url-pattern>注册的路径在运行时会被加上插件上下文前缀，实际可访问路径通常是/rest/bulk-create/1.0/upload这种形式，但具体前缀取决于插件 key 和rest还是servlet的声明方式。如果前端fetch的路径和后端实际注册路径不一致，请求自然到不了 Servlet。

解决：在插件启动后，先在浏览器里访问http://jira-address/rest/bulk-create/1.0/upload确认能否返回 405 或错误 JSON；确认路径后再把前端fetch的地址和后端<url-pattern>改成一致。建议直接把url-pattern固定为/bulk-create/upload，省得每次记上下文。

5.2 Active Objects 表没有自动创建

现象：插件日志报net.java.ao.ActiveObjectsException: Table 'bulk_create_record' not found。

原因：这个插件在记录导入历史时依赖 Active Objects，而 AO 表需要专门的迁移文件在插件启动时执行建表。如果你直接把create-records-table.xml放在db目录，但atlassian-plugin.xml里没有声明对应的<ao>配置，表就不会创建。

解决：在插件描述符里补上 Active Objects 配置，保证迁移文件在插件安装后被自动执行。配置示例：

<ao key="ao-module"> <entity>com.example.bulkcreate.model.BulkCreateRecord</entity> </ao>

5.3 CSV 第一行字段被吞掉

现象：CSV 一共 101 行数据，导入后只创建了 100 条 issue，第一条始终不见。

原因：第一行的表头如果带 BOM，并且解析器在readLine()时直接把 BOM 当成了表头内容的一部分，就会出现第一行的列名错位——比如summary变成了\uFEFFsummary，后续row.get("summary")匹配不到列名，返回 null，但该行不会报错，而是被跳过。

解决：在save文件时检测并剥离 BOM，同时配置 UTF-8 无 BOM 格式输出；如果用户已上传带 BOM 文件，解析器里也做一次判断。上文clean()方法里的replace("\uFEFF", "")就是干这个用的。

5.4 多行描述导致错行

现象：CSV 里某条描述文本包含换行，导入后原本 3 条 issue 变成了 5 条，后面所有数据错位。

原因：CSV 规范中，包含换行的字段必须用双引号包裹，大多数导出工具也会这么做；但用户手工复制粘贴时，很容易漏掉引号。解析器按行读取，碰到「裸换行」就自动拆成两行，于是后面的列全部错位。

解决：在解析器里增加一个状态判断——如果当前行在引号未闭合状态下结束，继续读下一行并拼接，直到引号闭合。这能兼容大多数带引号的换行数据。对于没有引号包裹的裸换行，直接报行号提示用户修改。也可以借鉴成熟 CSV 库的实现，把解析器重写得更稳健。

5.5 负责人是显示名而不是用户名

现象：CSV 里「负责人」写的是「张三」而不是zhangsan，创建时提示用户不存在。

原因：JIRA 内部存储和 API 识别用户的唯一标识是用户名（或accountId），CSV 里写的是显示名。validateCreate的setReporterId只认用户名。

解决：在解析后增加一个用户映射步骤——用UserUtil按显示名模糊查找用户，找到后替换成用户名；找不到就把这一行标记为失败，并提示「负责人张三未匹配到 JIRA 用户」。在插件后台再做一层「CSV 显示名 -> JIRA 用户名」的映射维护，效果会更好。

6. 二次开发：给插件加上「只导入新增行」和「导入前预览」能力

如果你要基于这个项目做二次开发，建议先改两个地方：一是把「预览」能力加进来，二是把「增量导入」做进去。这两个是最实用的改造点，因为现阶段插件是「上传即执行」，用户只有在结果回执里才知道哪些行失败，整个流程是黑匣子。

6.1 改造一：导入前预览

在BulkCreateService里加一个preview(InputStream, projectKey)方法，它只做解析、字段校验和用户校验，不调用issueService.create。返回一个预检结果列表，前端把它渲染成一个表格，用户看到哪行有问题，当场改完再上传，而不是上传后才知道翻车。

实现上只需要把bulkCreate里的createIssue调用换成validateOnly，并在IssueCreateService里加一个空实现的createIssue(..., boolean validateOnly)。

public boolean isValidateOnly() { return false; }

这样改还有一个好处：插件未来接 JIRA Automation 或 CI 做扫表导入时，可以先跑 preview 确认数据质量，再执行真正导入。

6.2 改造二：增量导入

增量导入的判断依据是「摘要 + 项目 Key + 创建人」唯一索引。在导入前，查一次 JIRA 的IssueService或直接 SQL 查jiraissue表（插件内部有 db 访问能力），把现有 issue 的摘要拉出来做成一个 Set，解析 CSV 时如果某行摘要已经存在，就跳过并标记为重复。

Set<String> existingSummaries = loadExistingSummaries(projectKey); rows.stream() .filter(row -> !existingSummaries.contains(row.get("summary"))) .forEach(row -> createIssue(projectKey, row));

注意 JQL 查询量不能太大，一次性查出项目全部 issue 几百条还好，几千条建议分页拉取。增量导入能避免用户每隔几天重新上传一次全量 CSV 时的重复建单问题。

6.3 改造三：结果落库成 AO 表

项目里虽然有BulkCreateRecord实体，但默认没把每次导入历史写进表里。建议把每次上传的文件名、项目 Key、成功数、失败数、耗时和操作人记录进 Active Objects 表。这样后续既能排查历史问题，也能做团队导入量统计，还能避免用户重复上传同一文件而不自知。

写 AO 表时要注意事务边界：逐条 issue 创建过程中每个issueService.create是独立事务，不能让一条失败回滚之前已创建成功的 50 条，所以结果落库必须在整体循环结束后执行。

6.4 验证方式与收尾

二次开发完成后，最慢但可靠的验证方法是搭一个本地 JIRA（用 SDK 的atlas-run或者 Docker 镜像），安装插件，然后准备三份 CSV：全量正确、部分错误、包含重复行，分别跑测试。重点观察结果回执里的行号和错误信息是否准确定位到了 CSV 的原始行。跑完这些场景，插件的健壮性基本能顶住一线用户的实际使用。

我早年做类似导入工具时吃过「没有预览直接跑批」的亏——一次导入造成了上百条脏数据，后来维护数据花了一个周末。从那以后，我每次给这类工具加新功能前都强制自己先跑一遍「全量 -> 部分错误 -> 全错误」三种测试文件，确认回执信息没有歧义才敢放给用户。希望这篇解析能帮你在接手团队内部工具类插件时少踩几个类似的坑。

本文还有配套的精品资源，点击获取