Roog (顾新培)
5feb795d12
变更内容： - 移除冗余文档，包括 Grafana 指南、指标对比、修复总结、OpenAPI 规范等。 - 精简项目文档结构，优化 README 文件内容。 - 提升文档层次清晰度，集中核心指南。
290 lines
6.0 KiB
Markdown
290 lines
6.0 KiB
Markdown
# FunctionalScaffold
|
||
|
||
**算法工程化 Serverless 解决方案脚手架**
|
||
|
||
一个基于 FastAPI 和 Docker 的 Serverless 算法服务脚手架，帮助算法工程师快速构建生产级的算法服务。
|
||
|
||
## 特性
|
||
|
||
- ✅ **标准化 API 接口** - 符合 RESTful 规范的 HTTP 接口
|
||
- ✅ **同步/异步调用** - 支持同步调用和异步任务
|
||
- ✅ **开箱即用** - 完整的项目结构和配置
|
||
- ✅ **自动文档** - Swagger/OpenAPI 自动生成
|
||
- ✅ **监控指标** - Prometheus 指标和 Grafana 仪表板
|
||
- ✅ **健康检查** - 存活和就绪探针
|
||
- ✅ **容器化部署** - Docker 和 Kubernetes 支持
|
||
- ✅ **Serverless 就绪** - 支持阿里云函数计算和 AWS Lambda
|
||
- ✅ **完整测试** - 单元测试和集成测试
|
||
- ✅ **CI/CD** - GitHub Actions 工作流
|
||
|
||
## 文档
|
||
|
||
| 文档 | 描述 |
|
||
|------|------|
|
||
| [快速入门](docs/getting-started.md) | 10 分钟上手指南 |
|
||
| [算法开发指南](docs/algorithm-development.md) | 详细的算法开发教程 |
|
||
| [API 参考](docs/api-reference.md) | 完整的 API 文档 |
|
||
| [监控指南](docs/monitoring.md) | 监控和告警配置 |
|
||
| [API 规范](docs/api/README.md) | OpenAPI 规范说明 |
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- 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 src.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
|
||
```
|
||
|
||
## 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！
|