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

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

请求

POST /invoke
Content-Type: application/json

请求体

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

示例

{
  "number": 17
}

响应

成功响应 (200 OK)

{
  "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)

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

示例调用

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

---

异步任务接口

POST /jobs

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

请求

POST /jobs
Content-Type: application/json

请求体

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

示例

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

响应

成功响应 (202 Accepted)

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

错误响应 (404 Not Found)

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

错误响应 (503 Service Unavailable)

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

示例调用

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}

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

请求

GET /jobs/{job_id}

路径参数

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

响应

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

{
  "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) - 任务完成

{
  "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) - 任务失败

{
  "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)

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

任务状态说明

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

示例调用

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

---

Webhook 回调

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

回调请求

POST {webhook_url}
Content-Type: application/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)

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

示例调用

curl http://localhost:8000/healthz

---

GET /readyz

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

响应

成功响应 (200 OK)

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

示例调用

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 回调发送总数

示例调用

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