Golang访问Atlassian云服务(Jira/Confluence/Admin)插件库go-atlassian的使用

概述

go-atlassian是一个Go库，提供了与各种Atlassian产品REST API交互的简单便捷方式。它支持Jira、Confluence、Jira Service Management等产品。

主要特性

• 易于使用的函数和数据结构，抽象了API的复杂性
• 全面支持各种Atlassian产品的API
• 支持常见操作，如创建、更新和删除Atlassian产品中的实体
• 社区积极开发和维护，定期更新和修复错误
• 全面的文档和示例帮助开发者快速上手

安装

如果尚未安装Go，请先安装Go 1.20或更高版本。

使用以下命令获取最新版本的go-atlassian：

go get github.com/ctreminiom/go-atlassian/v2

包导入

可以导入以下包：

使用示例

API令牌认证

// 创建Confluence Cloud客户端
instance, err := confluence.New(nil, "INSTANCE_HOST")
if err != nil {
    log.Fatal(err)
}
// 设置基本认证
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")

使用预配置的HTTP客户端

transport := http.Transport{
    Proxy: http.ProxyFromEnvironment,
    Dial: (&net.Dialer{
        Timeout:   1 * time.Second,
        KeepAlive: 30 * time.Second,
    }).Dial,
    TLSHandshakeTimeout: 10 * time.Second,
}
client := http.Client{
    Transport: &transport,
    Timeout:   4 * time.Second,
}

instance, err := confluence.New(&client, "INSTANCE_HOST")
if err != nil {
    log.Fatal(err)
}
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")

OAuth 2.0 (3LO)认证

// 配置OAuth
oauthConfig := &common.OAuth2Config{
    ClientID:     "YOUR_CLIENT_ID",
    ClientSecret: "YOUR_CLIENT_SECRET",
    RedirectURI:  "https://your-app.com/callback",
}

// 创建支持OAuth授权流程的客户端
client, err := jira.New(
    http.DefaultClient,
    "https://api.atlassian.com", // OAuth流程的临时URL
    jira.WithOAuth(oauthConfig),
)
if err != nil {
    log.Fatal(err)
}

// 生成授权URL
scopes := []string{"read:jira-work", "write:jira-work"}
authURL, err := client.OAuth.GetAuthorizationURL(scopes, "state")
if err != nil {
    log.Fatal(err)
}

// 将用户重定向到authURL进行授权
fmt.Printf("Visit this URL to authorize: %s\n", authURL.String())

// 授权后，交换代码获取令牌
ctx := context.Background()
token, err := client.OAuth.ExchangeAuthorizationCode(ctx, "AUTH_CODE")
if err != nil {
    log.Fatal(err)
}

// 选项1：手动令牌管理
client.Auth.SetBearerToken(token.AccessToken)

// 选项2：创建带有自动续订的新客户端（推荐）
client, err = jira.New(
    http.DefaultClient,
    "https://your-domain.atlassian.net",
    jira.WithOAuth(oauthConfig),      // OAuth服务
    jira.WithAutoRenewalToken(token), // 自动续订
)
if err != nil {
    log.Fatal(err)
}

// 进行API调用
myself, _, err := client.MySelf.Details(ctx, nil)
if err != nil {
    log.Fatal(err)
}

调用原始API端点

package main

import (
    "context"
    "fmt"
    "github.com/ctreminiom/go-atlassian/v2/jira/v3"
    "log"
    "net/http"
    "os"
)

type IssueTypeMetadata struct {
    IssueTypes []struct {
        ID          string `json:"id"`
        Name        string `json:"name"`
        Description string `json:"description"`
    } `json:"issueTypes"`
}

func main() {
    var (
        host  = os.Getenv("SITE")
        mail  = os.Getenv("MAIL")
        token = os.Getenv("TOKEN")
    )

    atlassian, err := v3.New(nil, host)
    if err != nil {
        log.Fatal(err)
    }

    atlassian.Auth.SetBasicAuth(mail, token)

    // 定义原始端点
    apiEndpoint := "rest/api/3/issue/createmeta/KP/issuetypes"

    request, err := atlassian.NewRequest(context.Background(), http.MethodGet, apiEndpoint, "", nil)
    if err != nil {
        log.Fatal(err)
    }

    customResponseStruct := new(IssueTypeMetadata)
    response, err := atlassian.Call(request, &customResponseStruct)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(response.Status)
}

服务接口

库使用服务接口提供模块化和灵活的方式来与Atlassian产品的REST API交互。每个服务接口包含一组方法，对应于相应API中的可用端点。

例如，IssueService接口包括Create、Update和Get等方法，对应于Jira Issues API中的POST、PUT和GET端点。

实现示例

ctx := context.Background()
issueKey := "KP-2"
expand := []string{"transitions"}
issue, response, err := atlassian.Issue.Get(ctx, issueKey, nil, expand)
if err != nil {
    log.Fatal(err)
}
log.Println(issue.Key)
for _, transition := range issue.Transitions {
    log.Println(transition.Name, transition.ID, transition.To.ID, transition.HasScreen)
}

贡献指南

如果你想为这个项目做贡献，请遵循以下指南：

1. 提交描述问题的issue
2. Fork仓库并添加你的贡献
3. 遵循基本的Go约定
4. 创建包含更改描述的pull request

许可证

Copyright © 2023 Carlos Treminio。本项目采用MIT许可证。