main:删除多余文档并清理项目目录
变更内容： - 移除冗余文档，包括 Grafana 指南、指标对比、修复总结、OpenAPI 规范等。 - 精简项目文档结构，优化 README 文件内容。 - 提升文档层次清晰度，集中核心指南。
This commit is contained in:
441
docs/api-reference.md
Normal file
441
docs/api-reference.md
Normal file
@@ -0,0 +1,441 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user