10 KiB

Raw Blame History

API 参考文档

1. 概述

Reporting Service 提供 RESTful API，用于报表的生成、查询和导出。

Base URL: /api/v1

响应格式: 所有响应均使用统一的 JSON 格式

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

错误响应格式:

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "Validation failed",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

2. 健康检查 API

2.1 健康检查

Endpoint: GET /health

检查服务是否运行正常。

响应示例:

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "reporting-service",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

2.2 就绪检查

Endpoint: GET /health/ready

检查服务是否准备好处理请求（包括数据库连接等）。

响应示例:

{
  "success": true,
  "data": {
    "status": "ready",
    "service": "reporting-service",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

3. 报表定义 API

3.1 获取所有报表定义

Endpoint: GET /reports/definitions

获取所有可用的报表定义列表。

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "reportCode": "RPT_LEADERBOARD",
      "reportName": "排行榜报表",
      "reportType": "LEADERBOARD_REPORT",
      "description": "用户排行榜数据报表",
      "parameters": {
        "required": ["startDate", "endDate"],
        "optional": ["limit", "offset"]
      },
      "isActive": true,
      "scheduleCron": "0 0 1 * * *",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

3.2 获取单个报表定义

Endpoint: GET /reports/definitions/:code

根据报表代码获取报表定义详情。

路径参数:

参数	类型	描述
code	string	报表代码 (如 `RPT_LEADERBOARD`)

响应示例:

{
  "success": true,
  "data": {
    "id": "1",
    "reportCode": "RPT_LEADERBOARD",
    "reportName": "排行榜报表",
    "reportType": "LEADERBOARD_REPORT",
    "description": "用户排行榜数据报表",
    "parameters": {
      "required": ["startDate", "endDate"],
      "optional": ["limit", "offset"]
    },
    "isActive": true,
    "scheduleCron": "0 0 1 * * *",
    "lastGeneratedAt": "2024-01-14T01:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-14T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

错误响应 (404):

{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "message": "Report definition not found: RPT_INVALID",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

4. 报表生成 API

4.1 生成报表

Endpoint: POST /reports/generate

生成新的报表快照。

请求体:

{
  "reportCode": "RPT_LEADERBOARD",
  "reportPeriod": "DAILY",
  "startDate": "2024-01-01",
  "endDate": "2024-01-01",
  "filterParams": {
    "limit": 100,
    "category": "all"
  }
}

请求参数说明:

参数	类型	必填	描述
reportCode	string	是	报表代码
reportPeriod	enum	是	报表周期: `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY`, `CUSTOM`
startDate	string	是	开始日期 (ISO 8601 格式)
endDate	string	是	结束日期 (ISO 8601 格式)
filterParams	object	否	额外筛选参数

响应示例:

{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportType": "LEADERBOARD_REPORT",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-01",
    "rowCount": 100,
    "status": "COMPLETED",
    "generatedAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

验证错误 (400):

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "reportPeriod must be one of the following values: DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, CUSTOM",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

5. 报表快照 API

5.1 查询报表快照列表

Endpoint: GET /reports/snapshots

查询报表快照列表，支持分页和筛选。

查询参数:

参数	类型	必填	描述
reportCode	string	否	按报表代码筛选
reportPeriod	enum	否	按报表周期筛选
startDate	string	否	开始日期范围
endDate	string	否	结束日期范围
page	number	否	页码 (默认: 1)
limit	number	否	每页数量 (默认: 20, 最大: 100)

请求示例:

GET /reports/snapshots?reportCode=RPT_LEADERBOARD&reportPeriod=DAILY&page=1&limit=10

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "12345",
      "reportCode": "RPT_LEADERBOARD",
      "reportType": "LEADERBOARD_REPORT",
      "reportPeriod": "DAILY",
      "periodKey": "2024-01-15",
      "rowCount": 100,
      "periodStartAt": "2024-01-15T00:00:00.000Z",
      "periodEndAt": "2024-01-15T23:59:59.999Z",
      "generatedAt": "2024-01-16T01:00:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

5.2 获取快照详情

Endpoint: GET /reports/snapshots/:id

根据快照ID获取详细数据。

路径参数:

参数	类型	描述
id	string	快照ID

响应示例:

{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportType": "LEADERBOARD_REPORT",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-15",
    "snapshotData": {
      "rows": [
        { "rank": 1, "userId": 1001, "username": "user1", "score": 9850 },
        { "rank": 2, "userId": 1002, "username": "user2", "score": 9720 }
      ],
      "summary": {
        "totalEntries": 100,
        "averageScore": 5432,
        "maxScore": 9850
      }
    },
    "summaryData": {
      "totalEntries": 100,
      "generationTime": "2.5s"
    },
    "rowCount": 100,
    "dataSource": ["leaderboard-service"],
    "periodStartAt": "2024-01-15T00:00:00.000Z",
    "periodEndAt": "2024-01-15T23:59:59.999Z",
    "generatedAt": "2024-01-16T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

5.3 获取最新快照

Endpoint: GET /reports/snapshots/:code/latest

获取指定报表代码的最新快照。

路径参数:

参数	类型	描述
code	string	报表代码

响应示例:

{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-15",
    "rowCount": 100,
    "generatedAt": "2024-01-16T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

错误响应 (404):

{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "message": "No snapshot found for report: RPT_INVALID",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

6. 导出 API

6.1 导出报表

Endpoint: POST /export

将报表快照导出为指定格式。

请求体:

{
  "snapshotId": "12345",
  "format": "EXCEL",
  "options": {
    "includeCharts": true,
    "sheetName": "排行榜数据"
  }
}

请求参数说明:

参数	类型	必填	描述
snapshotId	string	是	快照ID
format	enum	是	导出格式: `EXCEL`, `CSV`, `PDF`, `JSON`
options	object	否	导出选项

导出选项 (按格式):

Excel 选项:

选项	类型	描述
includeCharts	boolean	是否包含图表
sheetName	string	工作表名称

PDF 选项:

选项	类型	描述
title	string	PDF标题
orientation	string	方向: `portrait`, `landscape`

响应示例:

{
  "success": true,
  "data": {
    "fileId": "file_67890",
    "fileName": "RPT_LEADERBOARD_2024-01-15.xlsx",
    "format": "EXCEL",
    "fileSize": 102400,
    "downloadUrl": "/api/v1/files/file_67890/download",
    "expiresAt": "2024-01-22T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

6.2 获取导出文件列表

Endpoint: GET /export/files

查询已导出的文件列表。

查询参数:

参数	类型	必填	描述
snapshotId	string	否	按快照ID筛选
format	enum	否	按格式筛选
page	number	否	页码
limit	number	否	每页数量

响应示例:

{
  "success": true,
  "data": [
    {
      "fileId": "file_67890",
      "fileName": "RPT_LEADERBOARD_2024-01-15.xlsx",
      "format": "EXCEL",
      "fileSize": 102400,
      "snapshotId": "12345",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

6.3 下载文件

Endpoint: GET /files/:fileId/download

下载导出的文件。

路径参数:

参数	类型	描述
fileId	string	文件ID

响应: 文件二进制流

响应头:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="RPT_LEADERBOARD_2024-01-15.xlsx"

7. 错误码参考

HTTP状态码	错误码	描述
400	BAD_REQUEST	请求参数验证失败
401	UNAUTHORIZED	未认证
403	FORBIDDEN	无权限访问
404	NOT_FOUND	资源不存在
409	CONFLICT	资源冲突 (如重复生成)
422	UNPROCESSABLE_ENTITY	业务逻辑错误
500	INTERNAL_ERROR	服务器内部错误
503	SERVICE_UNAVAILABLE	服务不可用

8. 认证

API 支持 JWT Bearer Token 认证（可配置）。

请求头:

Authorization: Bearer <token>

未认证响应 (401):

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

9. 限流

端点类型	限制
读取操作	100 次/分钟
生成报表	10 次/分钟
导出操作	20 次/分钟

超出限制返回 HTTP 429 Too Many Requests。

10 KiB Raw Blame History Unescape Escape

API 参考文档

1. 概述

2. 健康检查 API

2.1 健康检查

2.2 就绪检查

3. 报表定义 API

3.1 获取所有报表定义

3.2 获取单个报表定义

4. 报表生成 API

4.1 生成报表

5. 报表快照 API

5.1 查询报表快照列表

5.2 获取快照详情

5.3 获取最新快照

6. 导出 API

6.1 导出报表

6.2 获取导出文件列表

6.3 下载文件

7. 错误码参考

8. 认证

9. 限流

10 KiB

Raw Blame History