Bitzsoft.Integrations.ProjectManagement.Trello 1.0.4

Bitzsoft.Integrations.ProjectManagement.Trello

Atlassian Trello REST API 项目与看板卡片协同连接器实现。遵循项目管理通用抽象规范，实现通用 IProjectManagementService 接口。

功能特性

• 通用契约对齐：完整实现 IProjectManagementService 抽象规范，支持看板（Boards）创建与列表查询、卡片（Cards）创建、详情获取、信息修改、归档完成（closed = true）与列表查询。
• ApiKey + ApiToken 鉴权：遵循 Atlassian Trello 安全规范，通过 API Key 与用户授权 Token 双重参数认证。
• 看板列表与卡片层级：自动处理 Trello 看板与列表（Lists）结构，智能定位卡片归属并同步描述与截止日期。
• 多条件状态过滤：支持根据开放或完成状态筛选看板卡片。
• 工业级弹性韧性：内置 Polly 标准韧性管道（429 Too Many Requests / 503 Service Unavailable 指数退避重试与熔断保护）及出站审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.Trello

<PackageReference Include="Bitzsoft.Integrations.ProjectManagement.Trello" Version="1.0.0" />

配置

在 appsettings.json 中配置 Trello 连接器参数：

{
  "ProjectManagement": {
    "Trello": {
      "ApiKey": "your-trello-api-key",
      "ApiToken": "your-trello-api-token",
      "BaseUrl": "https://api.trello.com/1"
    }
  }
}

配置项说明

注册服务

支持通过配置源绑定或委托方式进行依赖注入注册：

using Microsoft.Extensions.DependencyInjection;

// 方式 1：通过 IConfiguration 绑定注册（推荐，默认读取 ProjectManagement:Trello）
services.AddTrelloProjectManagement(configuration);

// 自定义配置节路径：
// services.AddTrelloProjectManagement(configuration, "Integrations:Trello");

// 方式 2：通过委托手动配置注册
services.AddTrelloProjectManagement(options =>
{
    options.ApiKey = "your-trello-api-key";
    options.ApiToken = "your-trello-api-token";
    options.BaseUrl = "https://api.trello.com/1";
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 Trello 看板与卡片：

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement;
using Bitzsoft.Integrations.ProjectManagement.Dtos;
using TaskStatus = Bitzsoft.Integrations.ProjectManagement.Dtos.TaskStatus;

namespace YourNamespace;

public class TrelloTaskAppService
{
    private readonly IProjectManagementService _pmService;

    public TrelloTaskAppService(IProjectManagementService pmService)
    {
        _pmService = pmService;
    }

    public async Task<List<PmProject>> GetBoardsAsync(
        CancellationToken cancellationToken = default)
    {
        return await _pmService.ListProjectsAsync(cancellationToken);
    }

    public async Task<PmTask> CreateCardAsync(
        string boardId,
        string cardName,
        string description,
        string? assigneeId = null,
        DateTimeOffset? dueDate = null,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateTaskRequest
        {
            ProjectId = boardId,
            Name = cardName,
            Description = description,
            AssigneeId = assigneeId,
            DueDate = dueDate,
            Priority = TaskPriority.High
        };

        return await _pmService.CreateTaskAsync(request, cancellationToken);
    }

    public async Task<PmTask> GetCardDetailAsync(
        string cardId,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.GetTaskAsync(cardId, cancellationToken);
    }

    public async Task<PmTask> UpdateCardAsync(
        string cardId,
        string newName,
        string? newDescription = null,
        CancellationToken cancellationToken = default)
    {
        var request = new UpdateTaskRequest
        {
            Name = newName,
            Description = newDescription
        };

        return await _pmService.UpdateTaskAsync(cardId, request, cancellationToken);
    }

    public async Task<PmResult> ArchiveCardAsync(
        string cardId,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.CompleteTaskAsync(cardId, cancellationToken);
    }

    public async Task<List<PmTask>> ListCardsAsync(
        string boardId,
        TaskStatus? status = null,
        CancellationToken cancellationToken = default)
    {
        var query = new TaskQuery
        {
            ProjectId = boardId,
            Status = status
        };

        return await _pmService.ListTasksAsync(query, cancellationToken);
    }
}

架构与鉴权原理

Trello 连接器内部封装了 TrelloHttpClient：

• 凭据注入：由于 Trello 标准认证基于 URL 查询参数，底层 HttpClient 会在每个请求的 QueryString 中自动附加 key={ApiKey}&token={ApiToken}。
• 列表定位机制：创建卡片时若仅传入 BoardId，内部逻辑会自动查询该看板下的列表集合，默认使用第一个活跃列表作为卡片落脚点。

异常处理与弹性策略

连接器集成了基于 Polly 的指数退避重试与熔断机制：

• 限流防护：当触发 Trello 速率限制（HTTP 429）或服务端瞬时异常（HTTP 503）时，系统自动按照指数递增等待时间进行重试。
• 语义清晰：针对卡片不存在（404）或权限不足（401/403），返回详细的错误日志或封装好的异常。

依赖

相关包