main:添加核心文件并初始化项目
新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
This commit is contained in:
259
README.md
Normal file
259
README.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# FunctionalScaffold
|
||||
|
||||
**算法工程化 Serverless 解决方案脚手架**
|
||||
|
||||
一个基于 FastAPI 和 Docker 的 Serverless 算法服务脚手架，帮助算法工程师快速构建生产级的算法服务。
|
||||
|
||||
## 特性
|
||||
|
||||
- ✅ **标准化 API 接口** - 符合 RESTful 规范的 HTTP 接口
|
||||
- ✅ **开箱即用** - 完整的项目结构和配置
|
||||
- ✅ **自动文档** - Swagger/OpenAPI 自动生成
|
||||
- ✅ **监控指标** - Prometheus 指标和 Grafana 仪表板
|
||||
- ✅ **健康检查** - 存活和就绪探针
|
||||
- ✅ **容器化部署** - Docker 和 Kubernetes 支持
|
||||
- ✅ **Serverless 就绪** - 支持阿里云函数计算和 AWS Lambda
|
||||
- ✅ **完整测试** - 单元测试和集成测试
|
||||
- ✅ **CI/CD** - GitHub Actions 工作流
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- 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 /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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
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 路由中注册新端点
|
||||
|
||||
示例：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 监控
|
||||
|
||||
### Prometheus 指标
|
||||
|
||||
访问 `/metrics` 端点查看可用指标：
|
||||
|
||||
- `http_requests_total` - HTTP 请求总数
|
||||
- `http_request_duration_seconds` - HTTP 请求延迟
|
||||
- `algorithm_executions_total` - 算法执行总数
|
||||
- `algorithm_execution_duration_seconds` - 算法执行延迟
|
||||
|
||||
### 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！
|
||||
Reference in New Issue
Block a user