go-openproject: 与OpenProject API交互的Golang客户端库

go-openproject是一个用于与OpenProject项目管理软件API交互的Golang客户端库。下面我将介绍如何使用这个库进行基本的OpenProject API操作。

安装

首先安装go-openproject库：

go get github.com/opf/go-openproject

基本使用

1. 初始化客户端

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/opf/go-openproject"
)

func main() {
	// 从环境变量获取API密钥
	apiKey := os.Getenv("OPENPROJECT_API_KEY")
	if apiKey == "" {
		log.Fatal("OPENPROJECT_API_KEY环境变量未设置")
	}

	// 初始化客户端
	client, err := openproject.NewClient(nil, "https://your-openproject-instance.com", apiKey)
	if err != nil {
		log.Fatalf("创建客户端失败: %v", err)
	}

	// 测试连接
	testConnection(client)
}

func testConnection(client *openproject.Client) {
	ctx := context.Background()
	
	// 获取当前用户信息
	user, _, err := client.Me.Get(ctx)
	if err != nil {
		log.Fatalf("获取用户信息失败: %v", err)
	}
	
	fmt.Printf("成功连接OpenProject! 当前用户: %s (%s)\n", user.Name, user.Email)
}

2. 项目管理

// 获取所有项目
func listProjects(client *openproject.Client) {
	ctx := context.Background()
	
	projects, _, err := client.Project.List(ctx, nil)
	if err != nil {
		log.Fatalf("获取项目列表失败: %v", err)
	}
	
	fmt.Println("项目列表:")
	for _, p := range projects.Embedded.Elements {
		fmt.Printf("- %s (ID: %d)\n", p.Name, p.Id)
	}
}

// 创建新项目
func createProject(client *openproject.Client) {
	ctx := context.Background()
	
	newProject := &openproject.ProjectPayload{
		Name:        "新项目示例",
		Description: "这是一个通过API创建的项目",
		Status:      "on track",
		Public:      false,
	}
	
	project, _, err := client.Project.Create(ctx, newProject)
	if err != nil {
		log.Fatalf("创建项目失败: %v", err)
	}
	
	fmt.Printf("成功创建项目: %s (ID: %d)\n", project.Name, project.Id)
}

3. 工单管理

// 获取项目工单
func listWorkPackages(client *openproject.Client, projectID int) {
	ctx := context.Background()
	
	filters := []*openproject.Filter{
		{
			Project: &openproject.ProjectFilter{
				Operator: "=",
				Values:   []string{fmt.Sprintf("%d", projectID)},
			},
		},
	}
	
	wps, _, err := client.WorkPackage.List(ctx, filters, nil, nil, nil)
	if err != nil {
		log.Fatalf("获取工单列表失败: %v", err)
	}
	
	fmt.Println("工单列表:")
	for _, wp := range wps.Embedded.Elements {
		fmt.Printf("- %s (ID: %d, 状态: %s)\n", wp.Subject, wp.Id, wp.Embedded.Status.Name)
	}
}

// 创建新工单
func createWorkPackage(client *openproject.Client, projectID int) {
	ctx := context.Background()
	
	newWP := &openproject.WorkPackagePayload{
		Subject:     "API创建的工单示例",
		Description: "这是通过API创建的工单描述",
		Type:        "Task",
		Project:     &openproject.Project{Id: projectID},
	}
	
	wp, _, err := client.WorkPackage.Create(ctx, newWP)
	if err != nil {
		log.Fatalf("创建工单失败: %v", err)
	}
	
	fmt.Printf("成功创建工单: %s (ID: %d)\n", wp.Subject, wp.Id)
}

4. 自定义字段和更新操作

// 更新工单
func updateWorkPackage(client *openproject.Client, wpID int) {
	ctx := context.Background()
	
	update := &openproject.WorkPackagePayload{
		Description: "更新后的描述内容",
		Status:      &openproject.Status{Id: 2}, // 假设2是"进行中"状态的ID
		CustomFields: []*openproject.CustomField{
			{
				Id:    1, // 自定义字段ID
				Value: "高优先级",
			},
		},
	}
	
	wp, _, err := client.WorkPackage.Update(ctx, wpID, update)
	if err != nil {
		log.Fatalf("更新工单失败: %v", err)
	}
	
	fmt.Printf("成功更新工单ID %d: %s\n", wp.Id, wp.Subject)
}

高级用法

分页和过滤

func listWorkPackagesWithPaging(client *openproject.Client) {
	ctx := context.Background()
	
	// 设置分页参数
	page := 1
	pageSize := 10
	
	// 设置过滤器 - 只获取特定状态的工单
	filters := []*openproject.Filter{
		{
			Status: &openproject.StatusFilter{
				Operator: "=",
				Values:   []string{"3"}, // 假设3是"已完成"状态的ID
			},
		},
	}
	
	// 设置排序 - 按创建日期降序
	sortBy := []*openproject.SortParam{
		{
			Field:    "createdAt",
			Direction: "desc",
		},
	}
	
	wps, resp, err := client.WorkPackage.List(ctx, filters, sortBy, &page, &pageSize)
	if err != nil {
		log.Fatalf("获取工单列表失败: %v", err)
	}
	
	fmt.Printf("第%d页，共%d页\n", page, resp.TotalPages)
	fmt.Println("已完成工单:")
	for _, wp := range wps.Embedded.Elements {
		fmt.Printf("- %s (创建于: %s)\n", wp.Subject, wp.CreatedAt.Format("2006-01-02"))
	}
}

错误处理

func handleErrors(client *openproject.Client) {
	ctx := context.Background()
	
	// 尝试获取不存在的工单
	_, resp, err := client.WorkPackage.Get(ctx, 999999)
	if err != nil {
		if resp != nil && resp.StatusCode == 404 {
			fmt.Println("工单不存在")
		} else {
			log.Fatalf("获取工单失败: %v", err)
		}
	}
}

总结

go-openproject库提供了与OpenProject API交互的便捷方式。通过这个库，你可以：

1. 管理项目和工单
2. 处理自定义字段
3. 实现复杂的分页和过滤查询
4. 执行创建、读取、更新和删除操作

在实际使用时，建议：

• 将API密钥存储在环境变量中
• 添加适当的错误处理和日志记录
• 对于批量操作，考虑添加适当的延迟以避免API速率限制
• 定期检查库更新以获取新功能和修复

希望这个指南能帮助你开始使用go-openproject库与OpenProject API进行交互！