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"
}

高阶函数

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

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

错误处理

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

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

代码结构

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)

暴力方式获取所有用户列表。

参数： 无

开发

# 安装依赖
npm install

# 构建
npm run build

# 启动服务
npm start

日志记录

日志输出格式如下：

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"

发布指南

打包

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);

附录

环境变量列表

常见问题

1. 如何处理认证失败？

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

2. 无法连接到 API？

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