FunctionalScaffold/README.md

FunctionalScaffold

算法工程化 Serverless 解决方案脚手架

一个基于 FastAPI 和 Docker 的 Serverless 算法服务脚手架，帮助算法工程师快速构建生产级的算法服务。

特性

• ✅ 标准化 API 接口 - 符合 RESTful 规范的 HTTP 接口
• ✅ 同步/异步调用 - 支持同步调用和异步任务
• ✅ 开箱即用 - 完整的项目结构和配置
• ✅ 自动文档 - Swagger/OpenAPI 自动生成
• ✅ 监控指标 - Prometheus 指标和 Grafana 仪表板
• ✅ 健康检查 - 存活和就绪探针
• ✅ 容器化部署 - Docker 和 Kubernetes 支持
• ✅ Serverless 就绪 - 支持阿里云函数计算和 AWS Lambda
• ✅ 完整测试 - 单元测试和集成测试

文档

文档	描述
快速入门	10 分钟上手指南
算法开发指南	详细的算法开发教程
API 参考	完整的 API 文档
监控指南	监控和告警配置
API 规范	OpenAPI 规范说明
Kubernetes 部署	K8s 集群部署指南
日志集成(Loki)	日志收集部署说明
阿里云函数运算FC部署入门	阿里云FC部署入门

快速开始

前置要求

• Python 3.9+
• Docker (可选)

本地开发

1. 克隆仓库

git clone <repository-url>
cd FunctionalScaffold

2. 创建虚拟环境并安装依赖

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

3. 启动开发服务器

# 方式1：使用脚本
./scripts/run_dev.sh

# 方式2：直接运行
uvicorn functional_scaffold.main:app --reload --port 8000

4. 访问 API 文档

打开浏览器访问：

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

使用 Docker

# 构建镜像
docker build -f deployment/Dockerfile -t functional-scaffold:latest .

# 运行容器
docker run -p 8000:8000 functional-scaffold:latest

# 或使用 docker-compose
cd deployment
docker-compose up

# 如果阿里FC无法识别 Platform:unknown/unknown 的情况时，请按下列执行打包:
export DOCKER_DEFAULT_PLATFORM=linux/amd64
export BUILDX_NO_DEFAULT_ATTESTATIONS=1
docker compose build
docker compose push 

API 端点

核心接口

• POST /invoke - 同步调用算法
• POST /jobs - 创建异步任务
• GET /jobs/{job_id} - 查询任务状态

健康检查

• GET /healthz - 存活检查
• GET /readyz - 就绪检查

监控

• GET /metrics - Prometheus 指标

示例请求

同步调用 - 质数判断

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

响应：

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

异步任务

# 创建任务
curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d '{"algorithm": "PrimeChecker", "params": {"number": 17}}'

# 查询状态
curl http://localhost:8000/jobs/{job_id}

项目结构

FunctionalScaffold/
├── src/functional_scaffold/      # 核心代码
│   ├── algorithms/               # 算法实现
│   ├── api/                      # API 层
│   ├── core/                     # 核心功能
│   ├── utils/                    # 工具函数
│   ├── config.py                 # 配置管理
│   └── main.py                   # 应用入口
├── tests/                        # 测试
├── deployment/                   # 部署配置
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── kubernetes/
│   └── serverless/
├── monitoring/                   # 监控配置
├── scripts/                      # 辅助脚本
└── docs/                         # 文档

开发指南

详细的开发指南请参考 算法开发指南。

添加新算法

1. 在 src/functional_scaffold/algorithms/ 创建新算法文件
2. 继承 BaseAlgorithm 类并实现 process 方法
3. 在 API 路由中注册新端点

示例：

from .base import BaseAlgorithm

class MyAlgorithm(BaseAlgorithm):
    def process(self, input_data):
        # 实现算法逻辑
        result = do_something(input_data)
        return {"result": result}

运行测试

# 运行所有测试
pytest tests/ -v

# 运行测试并生成覆盖率报告
pytest tests/ --cov=src/functional_scaffold --cov-report=html

# 使用脚本
./scripts/run_tests.sh

代码质量

# 代码格式化
black src/ tests/

# 代码检查
ruff check src/ tests/

导出 OpenAPI 规范

python scripts/export_openapi.py

生成的文件位于 docs/swagger/openapi.json

部署

Kubernetes

kubectl apply -f deployment/kubernetes/

阿里云函数计算

fun deploy -t deployment/serverless/aliyun-fc.yaml

AWS Lambda

sam deploy --template-file deployment/serverless/aws-lambda.yaml

监控

详细的监控配置请参考 监控指南。

Prometheus 指标

访问 /metrics 端点查看可用指标：

• http_requests_total - HTTP 请求总数
• http_request_duration_seconds - HTTP 请求延迟
• algorithm_executions_total - 算法执行总数
• algorithm_execution_duration_seconds - 算法执行延迟
• jobs_created_total - 异步任务创建总数
• jobs_completed_total - 异步任务完成总数

Grafana 仪表板

导入 monitoring/grafana/dashboard.json 到 Grafana

配置

通过环境变量或 .env 文件配置：

# 应用配置
APP_NAME=FunctionalScaffold
APP_VERSION=1.0.0
APP_ENV=development

# 服务器配置
HOST=0.0.0.0
PORT=8000
WORKERS=4

# 日志配置
LOG_LEVEL=INFO
LOG_FORMAT=json

# 指标配置
METRICS_ENABLED=true

参考 .env.example 查看完整配置选项。

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！