main:添加核心文件并初始化项目

新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
2026-02-02 10:46:01 +08:00
parent 3c3659d314
commit 5921f71756
54 changed files with 5726 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,399 @@
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。
+
+## 项目概述
+
+**FunctionalScaffold（函数式脚手架）** 是一个算法工程化 Serverless 解决方案的脚手架生成器。
+
+- 为了方便团队交流，项目的自然语言使用中文，包括代码注释和文档等
+
+### 核心目标
+
+解决三大痛点：
+1. **不确定的算力需求** - 需要动态扩缩容能力
+2. **算法同学工程化能力不足** - 降低工程化门槛
+3. **后端同学集成难度过高** - 标准化接口规范
+
+## 技术架构
+
+采用 **Docker 封装的 Serverless API 服务**方案：
+
+- 算法代码 + 运行环境打包为 Docker 镜像
+- 部署到云厂商 Serverless 平台实现自动扩缩容
+- FastAPI 作为 HTTP 接口层
+- 算法逻辑保持独立和专注
+
+### 架构流程
+
+```
+用户请求 → API网关 → 容器实例（冷/热启动）→ FastAPI → 算法程序 → 返回结果
+                                              ↓
+                                        外部服务（OSS/数据库）
+```
+
+### 代码架构
+
+项目采用 **src layout** 结构（Python 最佳实践）：
+
+```
+src/functional_scaffold/
+├── algorithms/          # 算法层 - 所有算法必须继承 BaseAlgorithm
+│   ├── base.py         # 提供 execute() 包装器（埋点、错误处理）
+│   └── prime_checker.py # 示例：质数判断算法
+├── api/                # API 层 - FastAPI 路由和模型
+│   ├── models.py       # Pydantic 数据模型（使用 ConfigDict）
+│   ├── routes.py       # 路由定义（/invoke, /healthz, /readyz, /jobs）
+│   └── dependencies.py # 依赖注入（request_id 生成）
+├── core/               # 核心功能 - 横切关注点
+│   ├── errors.py       # 异常类层次结构
+│   ├── logging.py      # 结构化日志（JSON 格式）
+│   ├── metrics.py      # Prometheus 指标和装饰器
+│   └── tracing.py      # 分布式追踪（ContextVar）
+├── utils/              # 工具函数
+│   └── validators.py   # 输入验证
+├── config.py           # 配置管理（pydantic-settings）
+└── main.py             # FastAPI 应用入口
+```
+
+**关键设计模式：**
+
+1. **算法抽象层**：所有算法继承 `BaseAlgorithm`，只需实现 `process()` 方法。`execute()` 方法自动处理埋点、日志和错误包装。
+
+2. **依赖注入**：使用 FastAPI 的 `Depends()` 机制注入 request_id，通过 `ContextVar` 在异步上下文中传递。
+
+3. **配置管理**：使用 `pydantic-settings` 从环境变量或 `.env` 文件加载配置，支持类型验证。
+
+4. **可观测性**：
+   - 日志：结构化 JSON 日志（pythonjsonlogger）
+   - 指标：Prometheus 格式（request_counter, request_latency, algorithm_counter）
+   - 追踪：request_id 关联所有日志和指标
+
+## 开发命令
+
+### 环境设置
+
+```bash
+# 创建虚拟环境并安装依赖（开发模式）
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+### 运行服务
+
+```bash
+# 方式1：使用辅助脚本（推荐）
+./scripts/run_dev.sh
+
+# 方式2：直接运行（开发模式，自动重载）
+uvicorn src.functional_scaffold.main:app --reload --port 8000
+
+# 方式3：生产模式
+uvicorn src.functional_scaffold.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+访问地址：
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+- Metrics: http://localhost:8000/metrics
+
+### 测试
+
+```bash
+# 运行所有测试
+pytest tests/ -v
+
+# 运行单个测试文件
+pytest tests/test_algorithms.py -v
+
+# 运行单个测试类
+pytest tests/test_algorithms.py::TestPrimeChecker -v
+
+# 运行单个测试方法
+pytest tests/test_algorithms.py::TestPrimeChecker::test_prime_numbers -v
+
+# 生成覆盖率报告
+pytest tests/ --cov=src/functional_scaffold --cov-report=html
+# 查看报告：open htmlcov/index.html
+
+# 使用辅助脚本（包含代码检查）
+./scripts/run_tests.sh
+```
+
+### 代码质量
+
+```bash
+# 代码格式化（自动修复）
+black src/ tests/
+
+# 代码检查（不修改文件）
+black --check src/ tests/
+
+# 代码检查
+ruff check src/ tests/
+
+# 自动修复可修复的问题
+ruff check --fix src/ tests/
+```
+
+配置说明：
+- Black: 行长度 100，目标 Python 3.9+
+- Ruff: 行长度 100，目标 Python 3.9+
+
+### Docker
+
+```bash
+# 构建镜像
+docker build -f deployment/Dockerfile -t functional-scaffold:latest .
+
+# 运行容器
+docker run -p 8000:8000 functional-scaffold:latest
+
+# 使用 docker-compose（包含 Prometheus + Grafana）
+cd deployment
+docker-compose up
+# Grafana: http://localhost:3000 (admin/admin)
+# Prometheus: http://localhost:9090
+```
+
+### 文档
+
+```bash
+# 导出 OpenAPI 规范到 docs/swagger/openapi.json
+python scripts/export_openapi.py
+```
+
+## 添加新算法
+
+### 1. 创建算法类（继承 BaseAlgorithm）
+
+```python
+# src/functional_scaffold/algorithms/my_algorithm.py
+from typing import Dict, Any
+from .base import BaseAlgorithm
+
+class MyAlgorithm(BaseAlgorithm):
+    """我的算法类"""
+
+    def process(self, input_data: Any) -> Dict[str, Any]:
+        """
+        算法处理逻辑
+
+        Args:
+            input_data: 输入数据
+
+        Returns:
+            Dict[str, Any]: 处理结果
+        """
+        # 实现算法逻辑
+        result = do_something(input_data)
+        return {"result": result}
+```
+
+### 2. 注册到 `__init__.py`
+
+```python
+# src/functional_scaffold/algorithms/__init__.py
+from .my_algorithm import MyAlgorithm
+__all__ = [..., "MyAlgorithm"]
+```
+
+### 3. 添加 API 端点（在 `api/routes.py`）
+
+```python
+@router.post("/my-endpoint")
+async def my_endpoint(
+    request: MyRequest,
+    request_id: str = Depends(get_request_id)
+):
+    """我的算法端点"""
+    algorithm = MyAlgorithm()
+    result = algorithm.execute(request.data)
+    return MyResponse(request_id=request_id, **result)
+```
+
+### 4. 定义数据模型（在 `api/models.py`）
+
+```python
+class MyRequest(BaseModel):
+    """我的请求模型"""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"data": "示例数据"}
+        }
+    )
+
+    data: str = Field(..., description="输入数据")
+```
+
+### 5. 编写测试
+
+```python
+# tests/test_my_algorithm.py
+def test_my_algorithm():
+    """测试我的算法"""
+    algo = MyAlgorithm()
+    result = algo.process("测试数据")
+    assert result["result"] == expected
+```
+
+## 配置管理
+
+配置通过 `src/functional_scaffold/config.py` 的 `Settings` 类管理：
+
+- 从环境变量读取（不区分大小写）
+- 支持 `.env` 文件
+- 使用 `pydantic-settings` 进行类型验证
+
+配置示例：
+```bash
+# .env 文件
+APP_ENV=production
+LOG_LEVEL=INFO
+METRICS_ENABLED=true
+```
+
+访问配置：
+```python
+from functional_scaffold.config import settings
+print(settings.app_env)  # "production"
+```
+
+## 可观测性
+
+### 日志
+
+使用 `core/logging.py` 的 `setup_logging()`：
+
+```python
+from functional_scaffold.core.logging import setup_logging
+
+# 设置日志
+logger = setup_logging(level="INFO", format_type="json")
+
+# 记录日志
+logger.info("处理请求", extra={"user_id": "123"})
+```
+
+### 指标
+
+使用 `core/metrics.py` 的装饰器：
+
+```python
+from functional_scaffold.core.metrics import track_algorithm_execution
+
+@track_algorithm_execution("my_algorithm")
+def my_function():
+    """我的函数"""
+    pass
+```
+
+可用指标：
+- `http_requests_total{method, endpoint, status}` - HTTP 请求总数
+- `http_request_duration_seconds{method, endpoint}` - HTTP 请求延迟
+- `algorithm_executions_total{algorithm, status}` - 算法执行总数
+- `algorithm_execution_duration_seconds{algorithm}` - 算法执行延迟
+
+### 追踪
+
+Request ID 自动注入到所有请求：
+
+```python
+from functional_scaffold.core.tracing import get_request_id
+
+# 在请求上下文中获取 request_id
+request_id = get_request_id()
+```
+
+## 部署
+
+### Kubernetes
+
+```bash
+kubectl apply -f deployment/kubernetes/deployment.yaml
+kubectl apply -f deployment/kubernetes/service.yaml
+```
+
+配置说明：
+- 3 个副本
+- 资源限制：256Mi-512Mi 内存，250m-500m CPU
+- 健康检查：存活探针 (/healthz)，就绪探针 (/readyz)
+
+### 阿里云函数计算
+
+```bash
+fun deploy -t deployment/serverless/aliyun-fc.yaml
+```
+
+### AWS Lambda
+
+```bash
+sam deploy --template-file deployment/serverless/aws-lambda.yaml
+```
+
+## 必须交付的三大组件
+
+### 1. 接入规范
+
+**API 端点标准：**
+- `/invoke` - 同步调用接口
+- `/jobs` - 异步任务接口（当前返回 501）
+- `/healthz` - 存活检查
+- `/readyz` - 就绪检查
+- `/metrics` - Prometheus 指标
+
+**Schema 规范：**
+- 请求/响应 Schema（Pydantic 验证）
+- 错误响应格式（统一的 ErrorResponse）
+- 元数据和版本信息（每个响应包含 metadata）
+
+### 2. Python SDK 运行时
+
+**已实现的能力：**
+- ✅ 参数校验（Pydantic + utils/validators.py）
+- ✅ 错误包装和标准化（core/errors.py）
+- ✅ 埋点（core/metrics.py - 延迟、失败率）
+- ✅ 分布式追踪的关联 ID（core/tracing.py）
+- ⏳ Worker 运行时（重试、超时、DLQ - 待实现）
+
+### 3. 脚手架生成器
+
+**已包含的模板：**
+- ✅ 示例算法函数（algorithms/prime_checker.py）
+- ✅ Dockerfile（deployment/Dockerfile）
+- ✅ CI/CD 流水线配置（.github/workflows/）
+- ✅ Serverless 平台部署 YAML（deployment/serverless/）
+- ✅ Grafana 仪表板模板（monitoring/grafana/dashboard.json）
+- ✅ 告警规则配置（monitoring/alerts/rules.yaml）
+
+## 开发理念
+
+**算法同学只需修改核心算法函数。** 所有基础设施、可观测性、部署相关的工作都由脚手架处理。
+
+算法开发者只需：
+1. 继承 `BaseAlgorithm`
+2. 实现 `process()` 方法
+3. 返回字典格式的结果
+
+框架自动提供：
+- HTTP 接口封装
+- 参数验证
+- 错误处理
+- 日志记录
+- 性能指标
+- 健康检查
+- 容器化部署
+
+## 注意事项
+
+1. **Pydantic V2**：使用 `ConfigDict` 而非 `class Config`，使用 `model_config` 而非 `Config`。
+
+2. **异步上下文**：request_id 使用 `ContextVar` 存储，在异步函数中自动传递。
+
+3. **测试隔离**：每个测试使用 `TestClient`，不需要启动真实服务器。
+
+4. **Docker 构建**：Dockerfile 使用非 root 用户（appuser），包含健康检查。
+
+5. **配置优先级**：环境变量 > .env 文件 > 默认值。