🚀 Mantis 项目 Cobra 服务文档

Cobra 服务是 Mantis 项目的重要组成部分，它提供了一系列 API 接口，用于与 Mantis 系统进行交互，如获取问题列表、问题详情、用户信息等。同时，具备完善的配置、错误处理和日志记录机制，方便开发和维护。

🚀 快速开始

环境准备

在开始使用 Cobra 服务之前，需要进行环境配置。可以通过环境变量或配置文件两种方式进行配置。

环境变量配置

通过设置以下环境变量来配置服务：

• MANTIS_API_BASE_URL：Mantis API 的基础 URL（必填）
• MANTIS_USER：访问 Mantis API 的用户名（必填）
• MANTIS_PASSWORD：对应用户的密码（必填）
• PORT（默认值: 3000）：服务运行的端口
• ENV（可选，默认: production）：环境模式，支持 development 和 production

配置文件

也可以通过 config.json 文件进行配置：

{
  "mantis": {
    "apiUrl": "https://your-mantis-url.com",
    "username": "admin",
    "password": "secret"
  },
  "port": 3000,
  "env": "development"
}

启动服务

完成配置后，按照以下步骤启动服务：

# 安装依赖
npm install

# 构建
npm run build

# 启动服务
npm start

✨ 主要特性

高阶函数处理

服务使用 withMantisConfigured 高阶函数来处理通用的检查逻辑，确保：

• Mantis API 配置检查
• 统一的错误处理
• 标准化的响应格式
• 自动的日志记录

完善的错误处理

完善的错误处理机制包括：

• Mantis API 错误处理（包含 HTTP 状态码）
• 通用错误处理
• 结构化的错误响应
• 资源使用情况的详细日志

📦 安装指南

打包

npm run build && npm pack

安装

npm install mantis-cobra-service-0.1.0.tgz

配置示例

const withMantisConfigured = require('mantis-cobra-service');

const config = {
  apiUrl: 'https://your-mantis-url.com',
  username: 'admin',
  password: 'secret'
};

withMantisConfigured(config);

💻 使用示例

基础用法

以下是使用 Cobra 服务 API 接口的基础示例：

// 获取问题列表
const { get_issues } = require('mantis-cobra-service');

const params = {
  projectId: 1,
  statusId: 2,
  pageSize: 10,
  page: 1
};

get_issues(params)
 .then(issues => {
    console.log(issues);
  })
 .catch(error => {
    console.error(error);
  });

高级用法

根据不同的业务需求，可以组合使用多个 API 接口，实现更复杂的功能。例如，先获取项目列表，再根据项目 ID 获取该项目下的问题列表：

const { get_projects, get_issues } = require('mantis-cobra-service');

// 获取项目列表
get_projects()
 .then(projects => {
    const projectId = projects[0].id;

    // 根据项目 ID 获取问题列表
    const params = {
      projectId: projectId,
      pageSize: 10,
      page: 1
    };

    return get_issues(params);
  })
 .then(issues => {
    console.log(issues);
  })
 .catch(error => {
    console.error(error);
  });

📚 详细文档

API 工具说明

服务提供了以下 API 接口：

1. 获取问题列表 (get_issues)

获取 Mantis 问题列表，可以根据多个条件进行过滤。 参数：

• projectId (可选)：项目 ID
• statusId (可选)：状态 ID
• handlerId (可选)：处理人 ID
• reporterId (可选)：告诉者 ID
• search (可选)：搜索关键字
• pageSize (可选，默认 20)：页面大小
• page (可选，默认 0)：分页起始位置，从1开始
• select (可选)：返回的数据字段，例如：['id', 'summary', 'description']。可以用于减少返回数据量

2. 获取问题详情 (get_issue_by_id)

根据 ID 获取 Mantis 问题详情。 参数：

• issueId：问题 ID

3. 查询用户 (get_user)

根据用户名查询 Mantis 用户。 参数：

• username：用户名

4. 获取项目列表 (get_projects)

获取 Mantis 项目列表。 参数： 无

5. 获取问题统计 (get_issue_statistics)

获取 Mantis 问题统计数据，可以根据不同维度进行分析。 参数：

• projectId (可选)：项目 ID
• groupBy：分组依据，可选值: 'status', 'priority', 'severity', 'handler', 'reporter'
• period (默认 'all')：时间范围，可选值: 'all', 'today', 'week', 'month'

6. 获取分派统计 (get_assignment_statistics)

获取 Mantis 问题分派统计数据，分析不同用户的分派情况。 参数：

• projectId (可选)：项目 ID
• includeUnassigned (默认 true)：是否包含未分派的问题
• statusFilter (可选)：状态过滤器，只计算特定状态的问题

7. 获取所有用户 (get_users)

暴力方式获取所有用户列表。 参数： 无

🔧 技术细节

代码结构

Cobra 服务的代码结构清晰，主要围绕 API 接口的实现和相关工具函数的封装。通过模块化的设计，提高了代码的可维护性和可扩展性。

日志记录

日志输出格式如下：

time=2023-10-26T15:34:12.879Z level=INFO message="启动服务" port=3000 env=development
time=2023-10-26T15:34:13.000Z level=ERROR message="无法连接到 Mantis API" error="connection timeout"

📄 许可证

文档中未提及许可证相关信息。

附录

环境变量列表

常见问题

1. 如何处理认证失败？

   • 检查用户名和密码是否正确。
   • 确保环境变量或配置文件中的凭据无误。

2. 无法连接到 API？

   • 检查网络连接。
   • 确认 API 服务是否正常运行。