Jira API的踩坑记

最新推荐文章于 2025-06-21 12:49:24 发布

字节自动化测试

最新推荐文章于 2025-06-21 12:49:24 发布

阅读量3.1k

点赞数 1

CC 4.0 BY-SA版权

分类专栏： IT 程序员软件测试文章标签： jira http restful 程序人生测试工程师

本文链接：https://blog.youkuaiyun.com/software_test010/article/details/120227991

本文作者在对接Jira API时遇到了挑战，包括无中文文档、响应不统一、包装过度等问题，但也从中学习了HTTP状态码的使用规范。Jira API的201和204响应状态码在接口交互中有特殊意义，同时，作者指出接口响应结构不一致增加了对接难度。尽管有困扰，但对接过程也加深了对API规范的理解。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

在这里插入图片描述

我本来是想写篇文章，吐槽一下jira的api的，但是发现最终jira api，很多地方又让我学到了一些新知识。有些方面真的是没见过这么标准使用的。可能是我之前孤陋寡闻啦，所以本文的内容不仅仅是讲jira的坑，还有一些是jira本身优良的品性，不仅让我学到了一些知识，也让我对规范有了新的理解。本文的内容算是对我最近这段时间以来对接jira API的经验总结，希望能对各位有所帮助。

没有中文

这个是对我来说最大的困难，本身我的英文水平不好之前，阅读文档或者说是一些文章都是直接一键翻译，但是碰到jira的API文档就有点蒙逼了。本来我以为在国内有很多公司都在用jira，这里面少不了的API接口进行功能性的封装，肯定会有中文的文档结果经过几次尝试搜索之后，我终于确认jira API是没有中文文档的。

我使用的一键翻译软件是浏览器自带的尝试过一些，他们总是会把接口请求路径中的英文单词也翻译成汉字，这简直就是不能看。虽然如此，我还是需要中文翻译和英文原文对照着看，因为有些地方翻译成中文之后语序不是那么通顺。总体来说，没有中文文档对App的接入还是有挺大影响的，因为需要不断地去对照着英文原文和理解翻译之后的结果。

在我搜索中文文档的过程中，我看到网上有很多人对API的实现进行了分享，对我来说还是有点大帮助的。但内容比较少，仅限于两三个特别常用的API。没有人完整的翻译过jira API的文档，然后我发现了一个巨坑的事情：jira App文档分嗯多个版本，基本上每一个版本的基拉就对应一个版本的API文档，我没有仔细去看这里面的区别，但是我觉得一个版本一个文档，着实有点坑了。大家如果有机会对接jira API文档，到时候一定要首先确认jira的版本。

HTTPcode

在jira API文档中，http协议响应状态码有很多使用。在我之前的工作经历中，很少注意到http响应状态码这个数据。因为大多数情况都是成功的话，返回200，不成功的话也是返回200（通过业务状态码来区分不同原因），只有在接口请求失败，或者说服务器故障的时候会处理一下400和500系列的响应状态码。在对接Jira API文档的过程中，我遇到了很多种之前没有接触过的200系列的http协议响应状态码。Jira API 是通过http，响应状态码来表示业务处理状态，他并没有使用业务状态码。所以，在对接的过程中，需要单独处理每个接口的http响应状态码。

在POST和PUT全球方法的接口，很少能看到200的状态响应码。下面分享一下，我常见到的201和204状态响应码的标准规范。

201 Created

请求已经被实现，而且有一个新的资源已经依据请求的需要而建立，且其 URI 已经随Location 头信息返回。假如需要的资源无法及时建立的话，应当返回 ‘202 Accepted’。

204 No Content

服务器成功处理了请求，但不需要返回任何实体内容，并且希望返回更新了的元信息。响应可能通过实体头部的形式，返回新的或更新后的元信息。如果存在这些头部信息，则应当与所请求的变量相呼应。如果客户端是浏览器的话，那么用户浏览器应保留发送了该请求的页面，而不产生任何文档视图上的变化，即使按照规范新的或更新后的元信息应当被应用到用户浏览器活动视图中的文档。由于204响应被禁止包含任何消息体，因此它始终以消息头后的第一个空行结尾。

响应不统一

在之前文章一起吐槽接口文档中，我吐槽了一下，接口文档最坑的就是响应不统一，没想到在对接Jira文档的时候就出现了特别多这样的实践机会。我曾经一度怀疑Jira文档是不是故意这么做的，因为各个接口的响应结果。均为json形式，但是最外层的json响应结构。有点1000个接口有1000个响应的即视感。

我之前写项目测试框架的时候，都会对响应结果进行统一的json格式处理，但是对于Jira的api就没有办法使用统一的格式处理，每一个接口都需要进行单独的处理。这无疑也增加了工作量。下面分享我遇到的几种响应结构。

{
   
   
    "issues": [
        {
   
   
            "id": "10000",
            "key": "TST-24",
            "self": "http://www.example.com/jira/rest/api/2/issue/10000"
        },
        {
   
   
            "id": "10001",
            "key": "TST-25",
            "self": "http://www.example.com/jira/rest/api/2/issue/10001"
        }
    ],
    "errors": []
}

{
   
   
    "id": "10000",
    "key": "TST-24",
    "self": "http://www.example.com/jira/rest/api/2/issue/10000"
}

下面这种就属于比较霸王级别的难看。一个响应结构体去。表示编辑之后的issues的状态。结果没想到在JSON对象中包了这么多层。为了让文章能缩短一下，我把里数组重复的内容给删除了，但是还是有这么复杂的响应结构体，简直就是丧心病狂！

{
   
   
    "id": "https://docs.atlassian.com/jira/REST/schema/issue-update#",
    "title": "Issue Update",
    "type": "object",
    "properties": {
   
   
        "transition": {
   
   
            "title": "Transition",
            "type": "object",
            "properties": {
   
   
                "id": {
   
   
                    "type": "string"
                },
                "name": {
   
   
                    "type": "string"
                },
                "to": {
   
   
                    "title": "Status",
                    "type": "object",
                    "properties": {
   
   
                        "statusColor": {
   
   
                            "type": "string"
                        },
                        "description": {
   
   
                            "type": "string"
                        },
                        "iconUrl": {
   
   
                            "type": "string"
                        },
                        "name": {
   
   
                            "type": "string"
                        },
                        "id": {
   
   
                            "type": "string"
                        },
                        "statusCategory": {
   
   
                            "title": "Status Category",
                            "type": "object",
                            "properties": {
   
   
                                "id": {
   
   
                                    "type": "integer"
                                },
                                "key": {
   
   
                                    "type": "string"
                                },
                                "colorName": {
   
   
                                    "type": "string"
                                },
                                "name": {
   
   
                                    "type": "string"
                                }
                            }