{"id":50336955,"url":"https://github.com/studyzy/tapd-sdk-go","last_synced_at":"2026-05-29T14:01:30.338Z","repository":{"id":351980632,"uuid":"1213329874","full_name":"studyzy/tapd-sdk-go","owner":"studyzy","description":"tapd sdk based on https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/","archived":false,"fork":false,"pushed_at":"2026-05-29T11:05:30.000Z","size":183,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T11:07:37.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/studyzy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T09:11:22.000Z","updated_at":"2026-05-29T11:05:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/studyzy/tapd-sdk-go","commit_stats":null,"previous_names":["studyzy/tapd-sdk-go"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/studyzy/tapd-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/studyzy%2Ftapd-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/studyzy%2Ftapd-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/studyzy%2Ftapd-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/studyzy%2Ftapd-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/studyzy","download_url":"https://codeload.github.com/studyzy/tapd-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/studyzy%2Ftapd-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33655441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T14:01:29.437Z","updated_at":"2026-05-29T14:01:30.326Z","avatar_url":"https://github.com/studyzy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tapd-sdk-go\n\n[![Go](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://go.dev/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)\n\nTAPD（腾讯敏捷产品研发平台）Open API 的 Go SDK，零外部依赖，仅使用标准库实现。\n\n## API 文档来源\n\n本 SDK 的设计基于 TAPD 官方开放平台 API 文档：\n\n\u003e \u003chttps://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/\u003e\n\nTAPD Open API 共提供约 192 个接口，覆盖 20 个模块。本 SDK 经全量审计后已基本覆盖官方文档所有公开接口。\n\n## 功能概览\n\nSDK 覆盖 20+ 种 TAPD 资源类型，提供 **200+ 个 API 方法**：\n\n| 资源 | 方法数 | 支持操作 |\n|------|--------|----------|\n| **Story（需求）** | 25 | CRUD、计数、变更、模板、复制、批量更新、视图查询、分类、链接关系、时间关系、转换工作项类型等 |\n| **Task（任务）** | 8 | CRUD、计数、批量更新、获取已删除、视图查询 |\n| **Bug（缺陷）** | 12 | CRUD、计数、链接缺陷、复制、批量更新、模板、IDs 转 token、相关需求等 |\n| **Iteration（迭代）** | 6 | 列表、创建、更新、计数、锁定、解锁 |\n| **MiniItem（轻量工作项）** | 18 | 完整 CRUD + 分类 + 变更 + 关联 + 已删除 + 链接需求/缺陷 |\n| **TCase（测试用例）** | 28 | CRUD、分类、测试计划完整套件、用例实例（指派/执行/移除/结果）、关联管理 |\n| **Comment（评论）** | 4 | 列表、添加、更新、计数 |\n| **Wiki（文档）** | 12 | CRUD、计数、附件计数、Drawio、实体权限、关注者、标签 |\n| **Timesheet（工时）** | 5 | 列表、添加、更新、计数、删除 |\n| **Attachment（附件）** | 7 | 上传/Base64 上传、图片链接、列表、下载、文档下载 |\n| **Workflow（工作流）** | 6 | 状态流转、状态映射、结束状态、所有结束状态、起始状态、工作流列表 |\n| **Change（变更历史）** | 7 | 需求/缺陷/任务变更及计数、迭代变更 |\n| **Board（看板）** | 4 | 工作项创建、列表、更新、板块列表 |\n| **Release（发布计划）** | 12 | 新发布 CRUD、发布单/活动日志/模板/自定义字段、发布附件 |\n| **Setting（配置）** | 21 | 模块/版本/基线/特性 CRUD、自定义字段配置、选项更新、级联字段、项目设置 |\n| **Workspace（项目）** | 15 | 列表、详情、子项目、公司项目、成员、角色、工作日历、长 ID 转换、文档列表 |\n| **User（用户）** | 2 | 个人配置、第三方用户映射 |\n| **Program（项目集）** | 2 | 批量绑定/解绑业务对象、关联项目 |\n| **Webhook** | 1 | 解析 webhook 事件载荷（JSON/form） |\n| **Source（源码）** | 3 | 保存提交、获取提交、提交对象 |\n| **Report（报表）** | 1 | 项目报告 |\n| **Measure（度量）** | 1 | 状态流转时间 |\n| **Category（需求分类）** | 1 | 需求分类列表 |\n| **CustomField（自定义字段）** | 6 | 字段配置、需求/缺陷字段标签、字段详情、工作项类型 |\n| **Relation（实体关联）** | 2 | 需求关联缺陷、创建关联 |\n| **Misc（杂项）** | 6 | 发布计划列表、源码提交关键字、待办需求/任务/缺陷、企业微信消息 |\n\n## 安装\n\n```bash\ngo get github.com/studyzy/tapd-sdk-go\n```\n\n## 快速开始\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    tapd \"github.com/studyzy/tapd-sdk-go\"\n    \"github.com/studyzy/tapd-sdk-go/model\"\n)\n\nfunc main() {\n    // 方式一：使用 Access Token（推荐）\n    client := tapd.NewClient(\"your-access-token\", \"\", \"\")\n\n    // 方式二：使用 Basic Auth\n    // client := tapd.NewClient(\"\", \"api_user\", \"api_password\")\n\n    // 方式三：连接自定义 TAPD 站点\n    // client := tapd.NewClientWithBaseURL(\n    //     \"https://api.my-tapd.com\",   // API 地址\n    //     \"https://www.my-tapd.com\",   // 前端页面地址\n    //     \"your-access-token\", \"\", \"\",\n    // )\n\n    // 获取用户参与的项目列表\n    ctx := context.Background()\n    workspaces, err := client.ListWorkspaces(ctx)\n    if err != nil {\n        log.Fatal(err)\n    }\n    for _, ws := range workspaces {\n        fmt.Printf(\"项目: %s (ID: %s)\\n\", ws.Name, ws.ID)\n    }\n\n    // 查询需求列表\n    stories, err := client.ListStories(ctx, \u0026model.ListStoriesRequest{\n        WorkspaceID: \"12345678\",\n        Status:      \"open\",\n        Limit:       10,\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    for _, s := range stories {\n        fmt.Printf(\"需求: %s [%s]\\n\", s.Name, s.Status)\n    }\n}\n```\n\n## 架构设计\n\n### 模块结构\n\n```\ntapd-sdk-go/\n├── go.mod                 # 独立模块，零外部依赖\n├── client.go              # Client 核心：认证、HTTP 封装、响应解析\n├── story.go               # 需求 API（基础 CRUD）\n├── story_extras.go        # 需求扩展 API（分类、链接、批量、复制等）\n├── task.go                # 任务 API\n├── bug.go                 # 缺陷 API（基础 CRUD）\n├── bug_extras.go          # 缺陷扩展 API（链接、复制、批量、模板等）\n├── mini_item.go           # 轻量工作项 API（CRUD + 分类 + 关联 + 变更）\n├── iteration.go           # 迭代 API（含锁定/解锁）\n├── comment.go             # 评论 API\n├── wiki.go                # Wiki 文档 API\n├── wiki_extras.go         # Wiki 扩展 API（附件、Drawio、权限、关注、标签）\n├── tcase.go               # 测试用例 API\n├── tcase_test_plan.go     # 测试计划 API\n├── tcase_instance.go      # 用例实例 API\n├── timesheet.go           # 工时 API\n├── attachment.go          # 附件/图片 API（含上传、下载、文档下载）\n├── workflow.go            # 工作流 API\n├── change.go              # 变更历史 API（需求/缺陷/任务/迭代）\n├── board.go               # 看板 API\n├── release.go             # 发布计划 API（new_releases、launch_forms、launch_accessories）\n├── setting.go             # 配置 API（模块/版本/基线/特性、自定义字段）\n├── report.go              # 报表 API\n├── measure.go             # 度量 API\n├── source.go              # 源码提交 API\n├── category.go            # 需求分类 API\n├── custom_field.go        # 自定义字段 API\n├── relation.go            # 实体关联 API\n├── workspace.go           # 项目 API（含成员/角色/子项目/工作日历/文档）\n├── user.go                # 用户 API（个人配置、第三方映射）\n├── program.go             # 项目集 API\n├── webhook.go             # Webhook 事件解析（JSON/form）\n├── misc.go                # 杂项：待办、源码关键字、企业微信\n└── model/                 # 数据模型与请求参数\n    ├── model.go                  # 通用模型（TAPDResponse、Workspace 等）\n    ├── request.go                # 通用请求结构体\n    ├── story.go / story_extras.go        # Story 及扩展请求/响应\n    ├── task.go                   # Task 及其请求结构体\n    ├── bug.go / bug_extras.go            # Bug 及扩展请求/响应\n    ├── mini_item.go              # MiniItem 及其请求结构体\n    ├── iteration.go / iteration_lock.go  # Iteration 及锁定相关\n    ├── comment.go                # Comment 及其请求结构体\n    ├── wiki.go / wiki_extras.go          # Wiki 及扩展请求/响应\n    ├── tcase.go / tcase_test_plan.go / tcase_instance.go\n    ├── timesheet.go              # Timesheet 及其请求结构体\n    ├── attachment.go             # Attachment/ImageInfo 及请求结构体\n    ├── board.go                  # BoardCard/BoardColumn 及请求结构体\n    ├── change.go                 # WorkitemChange/BugChange/IterationChange\n    ├── release.go                # Release/LaunchForm/LaunchAccessory 等\n    ├── setting.go                # Module/Version/Baseline/Feature 及自定义字段\n    ├── workflow.go               # WorkflowTransition 及相关类型\n    ├── workspace.go              # 工作日历、长 ID、文档等扩展类型\n    ├── user.go                   # PersonalSetting、ThirdUserMapping\n    ├── program.go                # 项目集请求/响应\n    ├── webhook.go                # WebhookEvent 及事件常量\n    ├── report.go                 # WorkspaceReport\n    ├── source.go                 # 源码提交对象\n    ├── category.go               # Category 模型\n    └── custom_fields.go          # 自定义字段辅助函数（ExtractCustomFields 等）\n```\n\n### 设计原则\n\n1. **零外部依赖**：仅使用 Go 标准库，可被任何项目无冲突引入。\n2. **独立模块**：SDK 作为独立 Go module（`github.com/studyzy/tapd-sdk-go`），可被第三方项目直接引用。\n3. **统一模式**：所有资源 API 遵循一致的调用模式：\n   - 请求参数定义为 `model/` 下的结构体，通过 `ToParams()` 方法转为 `map[string]string`\n   - Client 方法调用内部 `doGet`/`doPost` 发起 HTTP 请求\n   - 自动解析 TAPD 统一响应格式 `{status, data, info}`\n   - 自动处理 TAPD 特有的数据包裹格式（如 `[{\"Story\": {...}}]`）\n4. **自定义字段透传**：`Story`、`Task`、`Bug` 通过自定义 `UnmarshalJSON`/`MarshalJSON` 将 `custom_field_*` 和 `custom_plan_field_*` 字段自动捕获到 `CustomFields map[string]string`，避免数据丢失。\n5. **双模式认证**：支持 Bearer Token（推荐）和 Basic Auth 两种认证方式。\n6. **可配置站点地址**：API 和前端 URL 均可自定义，支持连接非 `tapd.cn` 的 TAPD 部署。\n7. **结构化错误**：返回 `TAPDError` 包含 HTTP 状态码、退出码和错误消息，便于调用方精确处理。\n\n### 认证方式\n\n| 方式 | 环境变量 | 说明 |\n|------|----------|------|\n| Bearer Token（推荐） | `TAPD_ACCESS_TOKEN` | 通过 TAPD 个人设置获取 |\n| Basic Auth | `TAPD_API_USER` + `TAPD_API_PASSWORD` | API 账号密码 |\n\n当同时提供两种凭据时，Bearer Token 优先。\n\n### 自定义站点地址\n\nSDK 默认连接 `https://api.tapd.cn`，如需连接其他 TAPD 部署，使用 `NewClientWithBaseURL`：\n\n```go\nclient := tapd.NewClientWithBaseURL(\n    \"https://api.my-tapd.com\",   // apiURL：API 请求地址\n    \"https://www.my-tapd.com\",   // webURL：前端页面地址（用于生成条目链接）\n    \"your-access-token\", \"\", \"\",\n)\n\n// 获取前端页面基础地址\nfmt.Println(client.WebURL()) // https://www.my-tapd.com\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `apiURL` | `https://api.tapd.cn` | API 请求基础地址，传空字符串使用默认值 |\n| `webURL` | `https://www.tapd.cn` | 前端页面基础地址，传空字符串使用默认值 |\n\n### 错误处理\n\nSDK 返回结构化的 `TAPDError`，包含以下退出码映射：\n\n| HTTP 状态码 | 退出码 | 含义 |\n|-------------|--------|------|\n| 401 | 1 | 认证失败 |\n| 404 | 2 | 资源未找到 |\n| 422 | 3 | 参数错误 |\n| 429/500/502 | 4 | 服务端错误/限流 |\n| 其他 | 4 | API 错误 |\n\n```go\nstories, err := client.ListStories(req)\nif err != nil {\n    if tapdErr, ok := err.(*tapd.TAPDError); ok {\n        fmt.Printf(\"退出码: %d, HTTP: %d, 消息: %s\\n\",\n            tapdErr.ExitCode, tapdErr.HTTPStatus, tapdErr.Message)\n    }\n}\n```\n\n## API 覆盖对照\n\n经全量审计后，本 SDK 对 `docs/api_reference` 与 `docs/mini_api_reference` 文档中的接口已基本完整覆盖：\n\n| TAPD 模块 | 官方接口数 | SDK 已覆盖 | 覆盖范围 |\n|-----------|-----------|-----------|----------|\n| 需求 (Story) | 33 | 25 | CRUD、变更、模板、分类、链接、批量、复制、视图查询、转换工作项类型 |\n| 缺陷 (Bug) | 21 | 12 | CRUD、链接、复制、批量、模板、IDs 转 token、相关需求 |\n| 任务 (Task) | 10 | 8 | CRUD、批量更新、删除项、视图查询、变更 |\n| 迭代 (Iteration) | 8 | 6 | 列表、创建、更新、计数、锁定、解锁 |\n| 轻量工作项 (MiniItem) | 17 | 18 | CRUD、分类、变更、关联、已删除、链接需求/缺陷（含 mini_api 全部接口）|\n| 测试 (TCase) | 27 | 28 | CRUD、分类、测试计划、用例实例、关联、字段配置 |\n| Wiki | 11 | 12 | CRUD、计数、附件计数、Drawio、实体权限、关注者、标签 |\n| 评论 (Comment) | 4 | 4 | 全部覆盖（含 mini_api）|\n| 工时 (Timesheet) | 5 | 5 | 全部覆盖 |\n| 附件 (Attachment) | 7 | 7 | 上传、Base64 上传、列表、下载、图片链接、文档下载 |\n| 项目 (Workspace) | 17 | 15 | 列表、详情、子项目、成员、角色、工作日历、长 ID、文档 |\n| 工作流 (Workflow) | 6 | 6 | 全部覆盖 |\n| 发布 (Release) | 11 | 12 | 新发布 CRUD、发布单全套（活动日志/模板/字段配置）、发布附件 |\n| 配置 (Setting) | 21 | 21 | 模块/版本/基线/特性 CRUD、自定义字段配置、选项更新、级联字段、项目设置 |\n| 用户 (User) | 3 | 2 | 个人配置、第三方用户映射（角色已通过 Workspace 模块覆盖）|\n| 项目集 (Program) | 2 | 2 | 全部覆盖 |\n| Webhook | - | 1 | Webhook 事件载荷解析（JSON/form）|\n| 度量 (Measure) | 1 | 1 | 状态流转时间 |\n| 报表 (Report) | 1 | 1 | 项目报告 |\n| 源码 (Source) | 3 | 3 | 保存提交、获取提交、提交对象 |\n| 看板 (Board) | 4 | 4 | 全部覆盖 |\n| 变更历史 (Change) | - | 7 | 需求/缺陷/任务变更及计数、迭代变更 |\n| 自定义字段 | - | 6 | 字段配置、字段标签/详情（需求+缺陷+工作项类型） |\n| 关联 (Relation) | - | 2 | 需求关联缺陷、创建关联 |\n| 分类 (Category) | - | 1 | 需求分类列表 |\n| 其他 | - | 6 | 待办需求/任务/缺陷、源码关键字、企业微信消息 |\n\n## 测试\n\nSDK 使用 `net/http/httptest` 进行 mock server 测试，每个 API 文件都有对应的测试文件：\n\n```bash\ngo test ./...\n```\n\n## 许可证\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudyzy%2Ftapd-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstudyzy%2Ftapd-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudyzy%2Ftapd-sdk-go/lists"}