精通JQL查询：jira-ruby让你轻松筛选和导出JIRA问题数据-平芜编程栈

精通JQL查询：jira-ruby让你轻松筛选和导出JIRA问题数据

【免费下载链接】jira-rubyA Ruby gem for the JIRA REST API项目地址: https://gitcode.com/gh_mirrors/ji/jira-ruby

jira-ruby 是一个面向 JIRA REST API 的 Ruby 库（gem）。借助它对 JQL（JIRA Query Language）的原生支持，你可以在 Ruby 脚本里直接执行JQL 查询，按任意条件筛选Issue、Project 等数据，并把结果一键导出为 CSV 或 JSON，轻松完成 JIRA 数据批量处理 📊

为什么用 jira-ruby 做 JQL 查询？

JQL 是 JIRA 内置的查询语言，语法类似 SQL。日常在页面上筛选问题很方便，但一旦涉及批量导出、定时报表、数据迁移，界面操作就显得力不从心：

页面导出上限低，几千条问题就捉襟见肘
无法自动化，每天重复手点筛选条件很枯燥
导出的字段不可定制，拿不到自定义字段

jira-ruby 将 JIRA REST API 的 JQL 搜索接口封装成了几行 Ruby 代码（核心实现在 lib/jira/resource/issue.rb 的self.jql方法中），让你用写脚本的方式完成原本要手点几十下的操作 ⚡

快速安装：一分钟接入 JIRA

安装非常简单，一条命令即可：

gem install jira-ruby

然后用你的账号和 API Token 初始化客户端（配置项定义在 lib/jira/client.rb）：

require 'jira-ruby' options = { :username => 'myuser', :password => 'my_api_token', :site => 'https://yourcompany.atlassian.net/', :context_path => '', :auth_type => :basic } client = JIRA::Client.new(options)

💡 提示：Jira Cloud 已不再支持直接用密码登录，请在 JIRA 个人设置中生成 API Token 填入:password。

用一行 JQL 筛选问题数据

连接成功后，调用Issue.jql就能执行任意 JQL 查询：

# 查询 SAMPLEPROJECT 项目下所有未解决的 Bug bugs = client.Issue.jql("project = 'SAMPLEPROJECT' AND issuetype = Bug AND resolution is EMPTY") bugs.each do |issue| puts "#{issue.key} - #{issue.summary} - #{issue.status.name}" end

返回的是一个 Issue 对象数组，每个对象都能直接按属性取值（key、summary、created等），完全不用手动解析 JSON。

只取需要的字段：让查询更轻量

如果数据量大，可以指定只返回部分字段，既省流量又提速：

issues = client.Issue.jql( "created >= -30d", fields: [:summary, :status, :created, :assignee] )

遇到自定义字段（如customfield_10021）时，先执行一次字段映射，之后就能用字段名代替 ID：

client.Field.map_fields client.Issue.jql("project = 'SAMPLEPROJECT'", fields: [:summary, :release_date])

字段映射逻辑在 lib/jira/resource/field.rb，它会自动处理重名字段的冲突。

把 JQL 查询结果导出成 CSV 或 JSON

拿到数组后，导出 CSV 只需十来行代码：

require 'csv' issues = client.Issue.jql("project = 'SAMPLEPROJECT' AND sprint is not EMPTY", fields: [:summary, :status, :assignee, :created]) CSV.open('jira_issues.csv', 'w') do |csv| csv << %w[Key Summary Status Assignee Created] issues.each do |i| csv << [i.key, i.summary, i.status.name, i.assignee&.displayName, i.created] end end

JSON 导出同理，issues.map { |i| i.attrs }.to_json即可。配合系统定时任务，你就拥有了一个自动运行的 JIRA 数据导出管道 📦

大数据量场景：分页查询与计数

Issue.jql内部已做了自动翻页（通过nextPageToken），一次性把全量结果取回内存。如果你的数据集特别大，可以改用分页版本jql_paged，逐页处理、降低内存压力：

result = client.Issue.jql_paged(client, "project = 'BIGPROJECT'", max_results: 100) puts "本页 #{result[:issues].size} 条，共 #{result[:total]} 条"

另外，把max_results设为0时，方法只返回总条数而不返回数据，非常适合做统计：

total = client.Issue.jql("status = Done AND created >= -90d", max_results: 0) puts "本季度完成 #{total} 个问题"

直接复用 JIRA 中已保存的过滤器

团队在 JIRA 页面上保存的 Filter（过滤器）同样可以拿来用——每个 Filter 本身就带一条 JQL，取回后调用issues方法即可执行：

filter = client.Filter.find('123') issues = filter.issues # 内部自动用该过滤器的 JQL 执行查询

实现见 lib/jira/resource/filter.rb，这让"页面筛选 + 脚本导出"无缝衔接。

常用 JQL 条件速查表

需求	JQL 写法
指定项目的所有 Bug	`project = 'SAMPLEPROJECT' AND issuetype = Bug`
某人负责且未完成	`assignee = "张三" AND resolution is EMPTY`
近 7 天新建的问题	`created >= -7d`
带特定标签的问题	`labels = urgent`
优先级为最高	`priority = Highest`
标题包含关键词	`summary ~ "登录"`
某版本中修复的问题	`fixversion = 1.2.0`

把这些条件直接传给Issue.jql，即可实现各种灵活的筛选与导出。

常见问题排查

查询返回空结果？先用 JIRA 页面的"高级搜索"验证同一条 JQL，确认语法和项目 Key 无误；
自定义字段取不到？确认已执行client.Field.map_fields，且fields中写的是字段名而非customfield_xxx；
查询很慢？通过fields只取必需字段，或用max_results限制条数；
认证失败？检查:site地址、:context_path（atlassian.net 上一般为空字符串）以及 API Token 是否过期。