3. Jira查询语言JQL入门

在Jira中，仪表盘上的每一个数字、每一张图表，背后几乎都站着一句JQL。JQL（Jira Query Language）是Jira的查询语言，它把"我想看什么"翻译成Jira能精确执行的条件表达式。不会JQL，你只能依赖别人做好的筛选器；会了JQL，你就能自己定义"什么算本周新增缺陷""哪些需求卡在测试超过三天"，进而把这些口径固化到仪表盘上，形成可复用的研发效能度量。

一、JQL的基本语法结构

一句JQL由若干"字段 + 运算符 + 值"的条件组成，条件之间用逻辑关键字连接，最后可接排序。基本形式如下：

字段 运算符 值 [AND|OR 字段 运算符 值 ...] [ORDER BY 字段 [ASC|DESC]]

例如，查询"项目为PAY、状态为进行中、且指派给我"的缺陷：

project = PAY AND issuetype = 缺陷 AND status = "进行中" AND assignee = currentUser()

这里有几个必须记住的规则。第一，字段名和关键字（AND、OR、ORDER BY、ASC、DESC）不区分大小写，但值通常区分，尤其是状态、优先级这类中文或自定义值。第二，值中若含空格或与关键字同名，必须用英文双引号包裹，如 status = "In Progress"。第三，日期、函数、字段引用有各自写法，不能随意加引号，否则会被当成字符串字面量。

常用运算符按用途分三类：比较类（=、!=、>、>=、<、<=）、集合类（IN、NOT IN）、文本类（~ 包含、!~ 不包含）。集合类适合一次匹配多个值，例如 status IN ("进行中", "待测试")；文本类用于摘要、描述等自由文本的模糊匹配，例如 summary ~ "登录失败"。逻辑连接中，AND 的优先级高于 OR，混用时建议用括号明确分组，避免歧义。

二、常用函数：让查询"活"起来

JQL真正的效率来自函数。它们让查询不再写死具体值，而是随当前用户、当前时间动态计算，这正是仪表盘能"每天自动更新"的关键。

• currentUser()：当前登录用户。常用于"我的待办"：assignee = currentUser() AND resolution = Unresolved。
• now() / startOfDay() / endOfDay()：当前时刻、今天开始、今天结束。配合比较运算符可表达时间窗口。
• startOfWeek() / endOfWeek() / startOfMonth()：本周、本月的边界，用于周报、月报口径。
• -1d、-4h、-2w：相对偏移量，d=天、h=小时、w=周。例如 created >= -7d 表示最近7天创建。
• membersOf("研发组")：某用户组的所有成员，适合按团队聚合：assignee IN membersOf("支付研发组")。
• linkedIssues()、issueHistory()：按关联关系或变更历史筛选，用于追溯"被谁阻塞过""状态被谁改过"。

把函数和时间偏移组合，就能写出典型的效能口径。例如"本周新创建且仍未解决的缺陷"：

project = PAY AND issuetype = 缺陷
AND created >= startOfWeek()
AND resolution = Unresolved
ORDER BY priority DESC, created ASC

注意 resolution = Unresolved 与 status != 已完成 并不等价：前者判断"是否已解决"，后者判断"当前状态"，一个已解决但尚未关闭的工单，两者结果不同。做度量时必须先明确口径，再选字段。

三、从查询到筛选器：把口径固化下来

在Jira搜索界面输入JQL并执行后，点击"另存为"即可创建筛选器（Filter）。筛选器有名称、所有者，并可选择共享给项目、组或全体用户。共享这一步很关键：仪表盘上的图表只能引用"你有权限看到"的筛选器，若筛选器私有，别人打开仪表盘会看到空白或报错。

创建筛选器时建议遵循三条实践。其一，命名体现口径而非人名，如"PAY-本周新增未解决缺陷"，而不是"张三的查询"。其二，把时间窗口写进JQL而不是靠人工改，例如用 startOfWeek() 而非固定日期，这样筛选器才能长期复用。其三，为仪表盘图表准备"粒度一致"的筛选器：趋势图用按创建时间统计的筛选器，分布图用按当前状态统计的筛选器，避免同一张图上口径打架。

四、JQL执行与结果判读

下面这张图把"输入JQL → 解析条件 → 匹配工单 → 输出结果 → 保存为筛选器"的完整链路，以及各环节的关键判断点画在一起，便于对照理解。

执行JQL后，先看结果条数是否符合预期，再抽查几条工单的字段值是否真的满足条件。如果条数明显偏多，常见原因是漏了 resolution 或 status 条件；如果偏少，检查是否把函数误加了引号，或值的大小写、空格与Jira中实际存储不一致。确认无误后再保存为筛选器，并立刻在仪表盘上引用一次，验证共享权限是否生效。