Bitzsoft.Integrations.ProjectManagement.Monday 1.0.4

Bitzsoft.Integrations.ProjectManagement.Monday

monday.com GraphQL API v2 项目与任务工作流连接器实现。遵循项目管理通用抽象规范，实现通用 IProjectManagementService 接口。

功能特性

• 通用契约对齐：完整实现 IProjectManagementService 抽象规范，支持看板（Boards）创建与列表、条目（Items）创建、详情获取、字段更新、状态完成与列表查询。
• GraphQL 原生封装：内部封装 monday.com GraphQL API（POST /v2），自动构造类型化 GraphQL 查询与变更（Mutations），免除手工拼接 JSON 语法之苦。
• 直接 API Key 认证：采用 monday.com 规范的直接授权头机制（Authorization: {apiKey}，无 Bearer 前缀）。
• 字段与状态映射：将 monday.com 列值（Column Values）及状态标签映射至标准工作流模型（PmTask 与 TaskStatus）。
• 工业级弹性韧性：内置 Polly 标准韧性管道（429 Too Many Requests / 503 Service Unavailable 指数退避重试与熔断保护）及出站审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.Monday

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

配置

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

{
  "ProjectManagement": {
    "Monday": {
      "ApiKey": "your-monday-api-key",
      "BaseUrl": "https://api.monday.com/v2"
    }
  }
}

配置项说明

注册服务

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

using Microsoft.Extensions.DependencyInjection;

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

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

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

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 monday.com 看板与工作条目：

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 MondayTaskAppService
{
    private readonly IProjectManagementService _pmService;

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

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

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

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

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

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

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

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

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

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

架构与鉴权原理

monday.com 连接器内部封装了高效的 GraphQL 交互引擎：

• 认证注入：在每次 HTTP 请求发出前，通过 Authorization: {ApiKey} 标头传递身份凭据（注意按官方规范不附加 Bearer 前缀）。
• 模型对应：monday.com 空间中的看板（Board）映射为 PmProject，条目（Item）映射为 PmTask。
• GraphQL 批量装配：单次 GraphQL 查询即可一次性拉取条目的状态、负责人、到期日与动态列值，避免 N+1 请求。

异常处理与弹性策略

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

• 限流防护：当触发 monday.com API 复杂度配额或网络波动（HTTP 429 / 503）时，系统自动按照指数递增等待时间进行重试。
• GraphQL 错误解析：当 GraphQL 响应中包含 errors 数组时，内部转换为可读的异常信息并记录到审计日志中。

依赖

相关包