FunctionalScaffold/docs/api-reference.md

# API 参考文档

本文档详细描述 FunctionalScaffold 提供的所有 API 端点。

## 基础信息

- **Base URL**: `http://localhost:8000`
- **Content-Type**: `application/json`
- **认证**: 当前版本无需认证

## 端点概览

| 方法 | 端点 | 描述 |
|------|------|------|
| POST | `/invoke` | 同步调用算法 |
| POST | `/jobs` | 创建异步任务 |
| GET | `/jobs/{job_id}` | 查询任务状态 |
| GET | `/healthz` | 存活检查 |
| GET | `/readyz` | 就绪检查 |
| GET | `/metrics` | Prometheus 指标 |

---

## 同步调用接口

### POST /invoke

同步调用质数判断算法，立即返回结果。

#### 请求

```http
POST /invoke
Content-Type: application/json
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| number | integer | 是 | 待判断的整数 |

**示例**

```json
{
  "number": 17
}
```

#### 响应

**成功响应 (200 OK)**

```json
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "result": {
    "number": 17,
    "is_prime": true,
    "factors": [],
    "algorithm": "trial_division"
  },
  "metadata": {
    "algorithm": "PrimeChecker",
    "version": "1.0.0",
    "elapsed_time": 0.001
  }
}
```

**错误响应 (400 Bad Request)**

```json
{
  "error": "VALIDATION_ERROR",
  "message": "number must be an integer",
  "details": {"field": "number", "value": "abc"},
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 示例调用

```bash
curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"number": 17}'
```

---

## 异步任务接口

### POST /jobs

创建异步任务，立即返回任务 ID，任务在后台执行。

#### 请求

```http
POST /jobs
Content-Type: application/json
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| algorithm | string | 是 | 算法名称（如 PrimeChecker） |
| params | object | 是 | 算法参数 |
| webhook | string | 否 | 任务完成后的回调 URL |

**示例**

```json
{
  "algorithm": "PrimeChecker",
  "params": {"number": 17},
  "webhook": "https://example.com/callback"
}
```

#### 响应

**成功响应 (202 Accepted)**

```json
{
  "job_id": "a1b2c3d4e5f6",
  "status": "pending",
  "message": "任务已创建",
  "created_at": "2026-02-02T10:00:00+00:00"
}
```

**错误响应 (404 Not Found)**

```json
{
  "detail": {
    "error": "ALGORITHM_NOT_FOUND",
    "message": "算法 'NonExistent' 不存在",
    "details": {"available_algorithms": ["PrimeChecker"]},
    "request_id": "xxx"
  }
}
```

**错误响应 (503 Service Unavailable)**

```json
{
  "detail": {
    "error": "SERVICE_UNAVAILABLE",
    "message": "任务服务暂不可用，请稍后重试",
    "request_id": "xxx"
  }
}
```

#### 示例调用

```bash
curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "PrimeChecker",
    "params": {"number": 17},
    "webhook": "https://webhook.site/your-uuid"
  }'
```

---

### GET /jobs/{job_id}

查询异步任务的执行状态和结果。

#### 请求

```http
GET /jobs/{job_id}
```

**路径参数**

| 参数 | 类型 | 描述 |
|------|------|------|
| job_id | string | 任务唯一标识（12位十六进制） |

#### 响应

**成功响应 (200 OK) - 任务进行中**

```json
{
  "job_id": "a1b2c3d4e5f6",
  "status": "running",
  "algorithm": "PrimeChecker",
  "created_at": "2026-02-02T10:00:00+00:00",
  "started_at": "2026-02-02T10:00:01+00:00",
  "completed_at": null,
  "result": null,
  "error": null,
  "metadata": null
}
```

**成功响应 (200 OK) - 任务完成**

```json
{
  "job_id": "a1b2c3d4e5f6",
  "status": "completed",
  "algorithm": "PrimeChecker",
  "created_at": "2026-02-02T10:00:00+00:00",
  "started_at": "2026-02-02T10:00:01+00:00",
  "completed_at": "2026-02-02T10:00:02+00:00",
  "result": {
    "number": 17,
    "is_prime": true,
    "factors": [],
    "algorithm": "trial_division"
  },
  "error": null,
  "metadata": {
    "algorithm": "PrimeChecker",
    "version": "1.0.0",
    "elapsed_time": 0.001
  }
}
```

**成功响应 (200 OK) - 任务失败**

```json
{
  "job_id": "a1b2c3d4e5f6",
  "status": "failed",
  "algorithm": "PrimeChecker",
  "created_at": "2026-02-02T10:00:00+00:00",
  "started_at": "2026-02-02T10:00:01+00:00",
  "completed_at": "2026-02-02T10:00:02+00:00",
  "result": null,
  "error": "Invalid input: number must be positive",
  "metadata": null
}
```

**错误响应 (404 Not Found)**

```json
{
  "detail": {
    "error": "JOB_NOT_FOUND",
    "message": "任务 'xxx' 不存在或已过期"
  }
}
```

#### 任务状态说明

| 状态 | 描述 |
|------|------|
| pending | 等待执行 |
| running | 执行中 |
| completed | 已完成 |
| failed | 执行失败 |

#### 示例调用

```bash
curl http://localhost:8000/jobs/a1b2c3d4e5f6
```

---

### Webhook 回调

当任务完成时，如果指定了 webhook URL，系统会发送 POST 请求到该 URL。

**回调请求**

```http
POST {webhook_url}
Content-Type: application/json
```

**回调负载**

```json
{
  "job_id": "a1b2c3d4e5f6",
  "status": "completed",
  "algorithm": "PrimeChecker",
  "result": {"number": 17, "is_prime": true},
  "error": null,
  "metadata": {"elapsed_time": 0.001},
  "completed_at": "2026-02-02T10:00:02+00:00"
}
```

**重试机制**

- 最大重试次数：3 次
- 重试间隔：1s, 5s, 15s（指数退避）
- 超时时间：10 秒

---

## 健康检查接口

### GET /healthz

存活检查端点，用于 Kubernetes 存活探针。

#### 响应

**成功响应 (200 OK)**

```json
{
  "status": "healthy",
  "timestamp": 1706868000.123
}
```

#### 示例调用

```bash
curl http://localhost:8000/healthz
```

---

### GET /readyz

就绪检查端点，用于 Kubernetes 就绪探针。

#### 响应

**成功响应 (200 OK)**

```json
{
  "status": "ready",
  "timestamp": 1706868000.123,
  "checks": {
    "algorithm": true
  }
}
```

#### 示例调用

```bash
curl http://localhost:8000/readyz
```

---

## 监控接口

### GET /metrics

返回 Prometheus 格式的监控指标。

#### 响应

**成功响应 (200 OK)**

```
Content-Type: text/plain; version=0.0.4; charset=utf-8

# HELP http_requests_total HTTP 请求总数
# TYPE http_requests_total counter
http_requests_total{endpoint="/invoke",method="POST",status="success"} 42

# HELP http_request_duration_seconds HTTP 请求延迟
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{endpoint="/invoke",method="POST",le="0.01"} 35
...

# HELP algorithm_executions_total 算法执行总数
# TYPE algorithm_executions_total counter
algorithm_executions_total{algorithm="PrimeChecker",status="success"} 42

# HELP jobs_created_total 创建的异步任务总数
# TYPE jobs_created_total counter
jobs_created_total{algorithm="PrimeChecker"} 10

# HELP jobs_completed_total 完成的异步任务总数
# TYPE jobs_completed_total counter
jobs_completed_total{algorithm="PrimeChecker",status="completed"} 8
jobs_completed_total{algorithm="PrimeChecker",status="failed"} 2
```

#### 可用指标

| 指标名称 | 类型 | 标签 | 描述 |
|---------|------|------|------|
| http_requests_total | counter | method, endpoint, status | HTTP 请求总数 |
| http_request_duration_seconds | histogram | method, endpoint | HTTP 请求延迟 |
| http_requests_in_progress | gauge | - | 当前进行中的请求数 |
| algorithm_executions_total | counter | algorithm, status | 算法执行总数 |
| algorithm_execution_duration_seconds | histogram | algorithm | 算法执行延迟 |
| jobs_created_total | counter | algorithm | 创建的异步任务总数 |
| jobs_completed_total | counter | algorithm, status | 完成的异步任务总数 |
| job_execution_duration_seconds | histogram | algorithm | 异步任务执行时间 |
| webhook_deliveries_total | counter | status | Webhook 回调发送总数 |

#### 示例调用

```bash
curl http://localhost:8000/metrics
```

---

## 错误码说明

| 错误码 | HTTP 状态码 | 描述 |
|--------|------------|------|
| VALIDATION_ERROR | 400 | 请求参数验证失败 |
| ALGORITHM_NOT_FOUND | 404 | 指定的算法不存在 |
| JOB_NOT_FOUND | 404 | 任务不存在或已过期 |
| ALGORITHM_ERROR | 500 | 算法执行错误 |
| INTERNAL_ERROR | 500 | 服务器内部错误 |
| SERVICE_UNAVAILABLE | 503 | 服务暂不可用 |

---

## 在线文档

启动服务后，可以访问交互式 API 文档：

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json