Teambition 集成

Teambition 集成 Starter 提供了完整的 Teambition 开放平台 SDK 封装，支持项目管理、任务管理、文件管理、工时统计等功能。通过简单的配置即可快速集成 Teambition 的各种 API。

主要特性

• 项目管理: 支持项目的创建、查询、更新等操作
• 任务管理: 支持任务的创建、分配、状态更新等
• 文件管理: 支持文件的上传、下载、管理
• 用户管理: 支持用户信息的查询和管理
• 联系人管理: 支持联系人信息的查询
• 工时统计: 支持工时记录和统计
• 事件回调: 支持 Teambition 事件回调处理
• JWT 认证: 支持 JWT Token 自动生成和管理
• 异步调用: 支持异步 API 调用
• 文件下载: 支持文件下载和临时文件管理

安装

Maven 安装

在您的 pom.xml 中添加以下依赖：

<dependency>
    <groupId>com.jeeapp.spring.boot</groupId>
    <artifactId>teambition-spring-boot-starter</artifactId>
</dependency>

Gradle 安装

在您的 build.gradle 中添加以下依赖：

implementation 'com.jeeapp.spring.boot:teambition-spring-boot-starter'

配置

基础配置

在 application.yml 中添加 Teambition 配置：

teambition:
  # API 基础路径
  base-path: https://open.teambition.com/api
  # 应用 ID
  app-id: your-app-id
  # 应用密钥
  app-secret: your-app-secret
  # 租户 ID
  tenant-id: your-tenant-id
  # 是否开启调试模式
  debugging: false

超时配置

teambition:
  # 连接超时时间（毫秒）
  connect-timeout: 10000
  # 读取超时时间（毫秒）
  read-timeout: 30000
  # 写入超时时间（毫秒）
  write-timeout: 30000

使用指南

基础使用

注入 TeambitionClient 即可使用：

import com.jeeapp.teambition.TeambitionClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TeambitionController {

    @Autowired
    private TeambitionClient teambitionClient;

    @GetMapping("/projects")
    public Object getProjects() {
        try {
            return teambitionClient.projectApi().getProjects();
        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

项目管理

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.ProjectApi;
import com.jeeapp.teambition.model.Project;
import org.springframework.stereotype.Service;

@Service
public class ProjectService {

    @Autowired
    private TeambitionClient teambitionClient;

    public List<Project> getAllProjects() throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        return projectApi.getProjects();
    }

    public Project getProject(String projectId) throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        return projectApi.getProject(projectId);
    }

    public Project createProject(String name, String description) throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        Project project = new Project();
        project.setName(name);
        project.setDescription(description);
        return projectApi.createProject(project);
    }
}

任务管理

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.TaskApi;
import com.jeeapp.teambition.model.Task;
import org.springframework.stereotype.Service;

@Service
public class TaskService {

    @Autowired
    private TeambitionClient teambitionClient;

    public List<Task> getTasksByProject(String projectId) throws Exception {
        TaskApi taskApi = teambitionClient.taskApi();
        return taskApi.getTasksByProject(projectId);
    }

    public Task createTask(String projectId, String name, String description) throws Exception {
        TaskApi taskApi = teambitionClient.taskApi();
        Task task = new Task();
        task.setProjectId(projectId);
        task.setName(name);
        task.setDescription(description);
        return taskApi.createTask(task);
    }

    public Task updateTaskStatus(String taskId, String status) throws Exception {
        TaskApi taskApi = teambitionClient.taskApi();
        Task task = new Task();
        task.setId(taskId);
        task.setStatus(status);
        return taskApi.updateTask(task);
    }
}

文件管理

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.FileApi;
import com.jeeapp.teambition.model.File;
import org.springframework.stereotype.Service;
import java.io.InputStream;

@Service
public class FileService {

    @Autowired
    private TeambitionClient teambitionClient;

    public File uploadFile(String projectId, String fileName, InputStream inputStream) throws Exception {
        FileApi fileApi = teambitionClient.fileApi();
        return fileApi.uploadFile(projectId, fileName, inputStream);
    }

    public java.io.File downloadFile(String fileId) throws Exception {
        FileApi fileApi = teambitionClient.fileApi();
        return fileApi.downloadFile(fileId);
    }

    public List<File> getFilesByProject(String projectId) throws Exception {
        FileApi fileApi = teambitionClient.fileApi();
        return fileApi.getFilesByProject(projectId);
    }
}

用户管理

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.UserApi;
import com.jeeapp.teambition.model.User;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Autowired
    private TeambitionClient teambitionClient;

    public List<User> getAllUsers() throws Exception {
        UserApi userApi = teambitionClient.userApi();
        return userApi.getUsers();
    }

    public User getUser(String userId) throws Exception {
        UserApi userApi = teambitionClient.userApi();
        return userApi.getUser(userId);
    }

    public User getUserByEmail(String email) throws Exception {
        UserApi userApi = teambitionClient.userApi();
        return userApi.getUserByEmail(email);
    }
}

工时管理

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.WorkTimeApi;
import com.jeeapp.teambition.model.WorkTime;
import org.springframework.stereotype.Service;
import java.time.LocalDate;

@Service
public class WorkTimeService {

    @Autowired
    private TeambitionClient teambitionClient;

    public List<WorkTime> getWorkTimesByUser(String userId, LocalDate startDate, LocalDate endDate) throws Exception {
        WorkTimeApi workTimeApi = teambitionClient.workTimeApi();
        return workTimeApi.getWorkTimesByUser(userId, startDate, endDate);
    }

    public WorkTime createWorkTime(String taskId, String userId, int hours, String description) throws Exception {
        WorkTimeApi workTimeApi = teambitionClient.workTimeApi();
        WorkTime workTime = new WorkTime();
        workTime.setTaskId(taskId);
        workTime.setUserId(userId);
        workTime.setHours(hours);
        workTime.setDescription(description);
        return workTimeApi.createWorkTime(workTime);
    }
}

事件处理

处理 Teambition 事件回调：

import com.jeeapp.teambition.event.TeambitionEvent;
import com.jeeapp.teambition.event.TaskCreatedEvent;
import com.jeeapp.teambition.event.ProjectUpdatedEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
public class TeambitionEventHandler {

    @EventListener
    public void handleTaskCreated(TaskCreatedEvent event) {
        System.out.println("任务创建: " + event.getTaskId());
        System.out.println("任务名称: " + event.getTaskName());
        System.out.println("项目ID: " + event.getProjectId());
    }

    @EventListener
    public void handleProjectUpdated(ProjectUpdatedEvent event) {
        System.out.println("项目更新: " + event.getProjectId());
        System.out.println("项目名称: " + event.getProjectName());
    }

    @EventListener
    public void handleTeambitionEvent(TeambitionEvent event) {
        System.out.println("收到 Teambition 事件: " + event.getEventType());
    }
}

Webhook 处理

import com.jeeapp.teambition.TeambitionClient;
import org.springframework.web.bind.annotation.*;
import java.util.Map;

@RestController
@RequestMapping("/api/teambition")
public class TeambitionWebhookController {

    @Autowired
    private TeambitionClient teambitionClient;

    @PostMapping("/webhook")
    public String handleWebhook(@RequestHeader Map<String, String> headers, @RequestBody String data) {
        try {
            teambitionClient.publishEvent(headers, data);
            return "success";
        } catch (Exception e) {
            return "error: " + e.getMessage();
        }
    }
}

异步操作

import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.TeambitionApiCallback;
import com.jeeapp.teambition.api.ProjectApi;
import com.jeeapp.teambition.model.Project;
import org.springframework.stereotype.Service;

@Service
public class AsyncProjectService {

    @Autowired
    private TeambitionClient teambitionClient;

    public void createProjectAsync(String name, String description) {
        ProjectApi projectApi = teambitionClient.projectApi();
        Project project = new Project();
        project.setName(name);
        project.setDescription(description);

        projectApi.createProjectAsync(project, new TeambitionApiCallback<Project>() {
            @Override
            public void onSuccess(Project result, int statusCode, Map<String, List<String>> responseHeaders) {
                System.out.println("项目创建成功: " + result.getId());
            }

            @Override
            public void onFailure(Exception e, int statusCode, Map<String, List<String>> responseHeaders) {
                System.out.println("项目创建失败: " + e.getMessage());
            }
        });
    }
}

API 参考

主要 API

API 类	功能	说明
ProjectApi	项目管理	项目的增删改查操作
TaskApi	任务管理	任务的增删改查操作
FileApi	文件管理	文件的上传下载管理
UserApi	用户管理	用户信息的查询
ContactApi	联系人管理	联系人信息的查询
WorkTimeApi	工时管理	工时记录和统计
IdMapApi	ID 映射	ID 映射相关操作

TeambitionClient 主要方法

方法名	参数	返回值
createAppAccessToken()	无	String - JWT Token
projectApi()	无	ProjectApi - 项目管理 API
taskApi()	无	TaskApi - 任务管理 API
fileApi()	无	FileApi - 文件管理 API
userApi()	无	UserApi - 用户管理 API
contactApi()	无	ContactApi - 联系人管理 API
workTimeApi()	无	WorkTimeApi - 工时管理 API
publishEvent(headers, data)	headers, data	void - 发布事件
execute(call)	call	T - 执行 API 调用
executeAsync(call, callback)	call, callback	void - 异步执行 API 调用

完整示例

完整应用示例

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import com.jeeapp.teambition.TeambitionClient;
import com.jeeapp.teambition.api.ProjectApi;
import com.jeeapp.teambition.api.TaskApi;
import com.jeeapp.teambition.model.Project;
import com.jeeapp.teambition.model.Task;
import java.util.List;
import java.util.Map;

@SpringBootApplication
public class TeambitionDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(TeambitionDemoApplication.class, args);
    }
}

@RestController
@RequestMapping("/api/teambition")
public class TeambitionApiController {

    private final TeambitionClient teambitionClient;

    public TeambitionApiController(TeambitionClient teambitionClient) {
        this.teambitionClient = teambitionClient;
    }

    @GetMapping("/projects")
    public List<Project> getProjects() throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        return projectApi.getProjects();
    }

    @GetMapping("/projects/{projectId}")
    public Project getProject(@PathVariable String projectId) throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        return projectApi.getProject(projectId);
    }

    @PostMapping("/projects")
    public Project createProject(@RequestBody Map<String, String> request) throws Exception {
        ProjectApi projectApi = teambitionClient.projectApi();
        Project project = new Project();
        project.setName(request.get("name"));
        project.setDescription(request.get("description"));
        return projectApi.createProject(project);
    }

    @GetMapping("/projects/{projectId}/tasks")
    public List<Task> getTasksByProject(@PathVariable String projectId) throws Exception {
        TaskApi taskApi = teambitionClient.taskApi();
        return taskApi.getTasksByProject(projectId);
    }

    @PostMapping("/tasks")
    public Task createTask(@RequestBody Map<String, String> request) throws Exception {
        TaskApi taskApi = teambitionClient.taskApi();
        Task task = new Task();
        task.setProjectId(request.get("projectId"));
        task.setName(request.get("name"));
        task.setDescription(request.get("description"));
        return taskApi.createTask(task);
    }

    @PostMapping("/webhook")
    public String handleWebhook(@RequestHeader Map<String, String> headers, @RequestBody String data) {
        try {
            teambitionClient.publishEvent(headers, data);
            return "success";
        } catch (Exception e) {
            return "error: " + e.getMessage();
        }
    }
}

相关资源

• Teambition 开放平台
• Teambition API 文档
• Issue Tracker