TickTick API Go SDK

一个优雅的、类型安全的 TickTick Open API V1 Go 客户端库，参考 notionapi 的架构设计。

✨ 特性

• 🚀 完整的 API 覆盖 - 支持 TickTick Open API V1 的所有功能
• 🔐 OAuth 2.0 支持 - 内置授权流程和 Token 刷新
• 📦 项目管理 - 完整的项目 CRUD 操作
• ✅ 任务管理 - 创建、读取、更新、删除和完成任务
• 🎯 类型安全 - 强类型 API，编译时检查
• 🔄 上下文支持 - 所有操作支持 context.Context
• 🛠 易于使用 - 清晰的 API 设计和丰富的示例
• 📚 完善文档 - 详细的文档和可运行的示例代码

📦 安装

go get github.com/irmini/ticktickapi

🚀 快速开始

基础用法

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/irmini/ticktickapi"
    "github.com/irmini/ticktickapi/types"
)

func main() {
    // 创建客户端
    client := ticktickapi.NewClient("your-access-token")
    ctx := context.Background()

    // 列出所有项目
    projects, err := client.Project.List(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // 在第一个项目中创建任务
    task, err := client.Task.Create(ctx, &types.TaskRequest{
        Title:     "我的第一个任务",
        Content:   "通过 Go SDK 创建",
        ProjectID: projects[0].ID,
        Priority:  types.TaskPriorityMedium,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("任务创建成功: %s (ID: %s)\n", task.Title, task.ID)
}

OAuth 认证

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/irmini/ticktickapi"
)

func main() {
    // 创建 OAuth 配置
    config := ticktickapi.NewOAuthConfig(
        "your-client-id",
        "your-client-secret",
        "http://localhost:8080/callback",
        "tasks:read", "tasks:write",
    )

    // 生成授权 URL（引导用户访问）
    authURL := config.AuthCodeURL("state-string")
    fmt.Printf("请访问: %s\n", authURL)

    // 用户授权后，使用授权码交换 Token
    token, err := config.Exchange(context.Background(), "authorization-code")
    if err != nil {
        log.Fatal(err)
    }

    // 使用 Token 创建客户端
    client := ticktickapi.NewClient(token.AccessToken)

    // 刷新 Token（当需要时）
    newToken, err := config.RefreshToken(context.Background(), token.RefreshToken)
    if err != nil {
        log.Fatal(err)
    }

    // 更新客户端的 Token
    client.SetToken(newToken.AccessToken)
}

📚 API 文档

客户端配置

// 使用默认配置创建客户端
client := ticktickapi.NewClient("access-token")

// 使用自定义超时
client := ticktickapi.NewClient("access-token",
    ticktickapi.WithTimeout(60*time.Second))

// 使用自定义 HTTP 客户端
httpClient := &http.Client{
    Transport: myCustomTransport,
}
client := ticktickapi.NewClient("access-token",
    ticktickapi.WithHTTPClient(httpClient))

项目操作

// 列出所有项目
projects, err := client.Project.List(ctx)

// 获取单个项目
project, err := client.Project.Get(ctx, projectID)

// 创建项目
project, err := client.Project.Create(ctx, &types.ProjectRequest{
    Name:  "新项目",
    Color: "#FF5722",
})

// 更新项目
project, err := client.Project.Update(ctx, projectID, &types.ProjectRequest{
    Name:  "更新后的名称",
    Color: "#2196F3",
})

// 删除项目
err := client.Project.Delete(ctx, projectID)

任务操作

// 列出项目中的所有任务
tasks, err := client.Task.List(ctx, projectID)

// 获取单个任务
task, err := client.Task.Get(ctx, projectID, taskID)

// 创建任务
task, err := client.Task.Create(ctx, &types.TaskRequest{
    Title:     "新任务",
    Content:   "任务描述",
    ProjectID: projectID,
    Priority:  types.TaskPriorityHigh,
})

// 更新任务
task, err := client.Task.Update(ctx, taskID, &types.TaskRequest{
    Title:     "更新后的标题",
    Priority:  types.TaskPriorityLow,
    ProjectID: projectID,
})

// 完成任务
err := client.Task.Complete(ctx, projectID, taskID)

// 删除任务
err := client.Task.Delete(ctx, taskID, projectID)

任务优先级

const (
    TaskPriorityNone   = 0  // 无
    TaskPriorityLow    = 1  // 低
    TaskPriorityMedium = 3  // 中
    TaskPriorityHigh   = 5  // 高
)

任务状态

const (
    TaskStatusNormal    = 0  // 正常（未完成）
    TaskStatusCompleted = 2  // 已完成
)

💡 完整示例

查看 examples 目录获取更多示例：

• basic - 基础 API 调用示例
• oauth - 完整的 OAuth 认证流程

运行示例：

# 基础示例
cd examples/basic
export TICKTICK_ACCESS_TOKEN="your-token"
go run main.go

# OAuth 示例
cd examples/oauth
# 编辑 main.go 设置 CLIENT_ID 和 CLIENT_SECRET
go run main.go

🏗 架构设计

本项目参考了 notionapi 的优秀设计：

ticktickapi/
├── client.go           # 主客户端和配置
├── oauth.go            # OAuth 2.0 认证
├── types/              # API 类型定义
│   ├── project.go      # 项目相关类型
│   ├── task.go         # 任务相关类型
│   └── user.go         # 用户相关类型
├── services/           # 服务层（业务逻辑）
│   ├── project.go      # 项目服务
│   └── task.go         # 任务服务
└── internal/v1/        # V1 API 实现
    ├── client.go       # HTTP 客户端
    ├── project.go      # 项目 API
    └── task.go         # 任务 API

设计原则：

• 分层架构 - HTTP 层 → V1 API 层 → 服务层 → 客户端门面
• 类型安全 - 强类型 API 接口和数据结构
• 易于扩展 - 清晰的模块划分，便于添加新功能
• 统一接口 - 所有服务使用一致的 API 设计模式

🔧 开发

环境要求

• Go 1.21+
• TickTick 开发者账号（注册地址）

运行测试

# 运行所有测试
go test ./...

# 运行测试并显示覆盖率
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

构建

# 构建整个项目
go build ./...

# 构建示例
cd examples/basic && go build
cd examples/oauth && go build

📖 相关资源

• TickTick 开发者文档
• TickTick 开发者控制台
• OAuth 2.0 RFC 6749
• notionapi - 设计灵感来源
• ticktick-py - Python SDK 参考

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的改动 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

贡献指南

• 保持代码风格一致（使用 gofmt 和 golint）
• 添加测试覆盖新功能
• 更新相关文档
• 确保所有测试通过

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

⚠️ 免责声明

本项目是非官方的 TickTick API 客户端。使用本 SDK 时请遵守 TickTick 服务条款 和 API 使用条款。

🙏 致谢

• notionapi - 优秀的架构设计灵感
• ticktick-py - API 功能参考
• TickTick - 优秀的待办事项应用

📮 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发起 Pull Request
• 发送邮件至项目维护者

---

Star ⭐ 本项目如果它对你有帮助！