FunctionalScaffold/README.md

# FunctionalScaffold

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

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

## 特性

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

## 文档

| 文档                                             | 描述           |
|------------------------------------------------|--------------|
| [快速入门](docs/getting-started.md)                | 10 分钟上手指南    |
| [算法开发指南](docs/algorithm-development.md)        | 详细的算法开发教程    |
| [API 参考](docs/api-reference.md)                | 完整的 API 文档   |
| [监控指南](docs/monitoring.md)                     | 监控和告警配置      |
| [API 规范](docs/api/README.md)                   | OpenAPI 规范说明 |
| [Kubernetes 部署](docs/kubernetes-deployment.md) | K8s 集群部署指南   |
| [日志集成(Loki)](docs/loki-quick-reference.md)     | 日志收集部署说明     |
| [阿里云函数运算FC部署入门](docs/fc-deploy.md)             | 阿里云FC部署入门    |

## 快速开始

### 前置要求

- Python 3.9+
- Docker (可选)

### 本地开发

1. 克隆仓库

```bash
git clone <repository-url>
cd FunctionalScaffold
```

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

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

3. 启动开发服务器

```bash
# 方式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

```bash
# 构建镜像
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 指标

## 示例请求

### 同步调用 - 质数判断

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

响应：

```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
  }
}
```

### 异步任务

```bash
# 创建任务
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/                         # 文档
```

## 开发指南

详细的开发指南请参考 [算法开发指南](docs/algorithm-development.md)。

### 添加新算法

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

示例：

```python
from .base import BaseAlgorithm

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

### 运行测试

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

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

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

### 代码质量

```bash
# 代码格式化
black src/ tests/

# 代码检查
ruff check src/ tests/
```

### 导出 OpenAPI 规范

```bash
python scripts/export_openapi.py
```

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

## 部署

### Kubernetes

```bash
kubectl apply -f deployment/kubernetes/
```

### 阿里云函数计算

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

### AWS Lambda

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

## 监控

详细的监控配置请参考 [监控指南](docs/monitoring.md)。

### 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` 文件配置：

```bash
# 应用配置
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！