# Python 项目开发准则 - 开发指南摘要

本摘要引用自完整文档 `@/Python项目开发准则.md`

## 核心 5 项要求

1. **类型注解** - 所有函数必须有完整的参数和返回类型
   ```python
   def process(data: dict) -> list[str]:
       pass
   ```

2. **Docstring** - 所有公开函数/类必须有 Google 风格文档
   ```python
   def process(data: dict) -> list[str]:
       """处理数据

       Args:
           data: 输入数据

       Returns:
           处理结果列表
       """
   ```

3. **异常处理** - 捕获具体异常，禁止裸 except
   ```python
   try:
       result = do_something()
   except ValueError as e:
       logger.error(f"错误: {e}")
       raise
   ```

4. **日志记录** - 关键操作必须有日志
   ```python
   logger.info(f"处理完成，耗时: {elapsed}s")
   ```

5. **测试** - 单元测试覆盖率 ≥80%
   ```bash
   uv run pytest --cov=src --cov-fail-under=80
   ```

## 提交前检查

```bash
# 一键运行所有检查
uv run python scripts/check.py

# 或分别运行
uv run black src/ tests/ --check      # 格式
uv run ruff check src/ tests/           # 检查
uv run mypy src/                        # 类型
uv run pytest --cov=src                 # 测试
```

## 特殊规范速查

| 场景 | 规范 | 文档 |
|------|------|------|
| 用户输入验证 | 使用 Pydantic v2 | Ch11 |
| 网络/文件操作 | 使用异步 asyncio | Ch10 |
| API 端点 | RESTful 命名规范 | Ch14 |
| 配置管理 | 使用 .env 环境变量 | Ch12 |
| 错误响应 | 统一格式(code/message/details) | Ch14 |

## 快速模板

### 新模块结构
```
src/module_name/
├── __init__.py        # 导出公开 API
├── models.py          # 数据模型（Pydantic）
├── service.py         # 业务逻辑
└── utils.py           # 工具函数

tests/unit/test_module_name/
├── test_models.py
├── test_service.py
└── test_utils.py
```

### 基础函数模板
```python
from pydantic import BaseModel, ValidationError

class InputData(BaseModel):
    """输入数据模型"""
    name: str
    value: int

def process_data(data: InputData) -> dict:
    """处理数据

    Args:
        data: 输入数据

    Returns:
        处理结果

    Raises:
        ValueError: 处理失败时
    """
    try:
        result = {"processed": True}
        return result
    except Exception as e:
        logger.error(f"处理失败: {e}", exc_info=True)
        raise ValueError(f"数据处理失败: {e}") from e
```

### 异步函数模板
```python
async def fetch_data(url: str) -> dict:
    """异步获取数据

    Args:
        url: 数据 URL

    Returns:
        响应数据
    """
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, timeout=30) as resp:
                return await resp.json()
    except asyncio.TimeoutError:
        logger.warning(f"请求超时: {url}")
        return None
```

## 常见陷阱

❌ **禁止：**
- 硬编码密码/密钥
- 裸 except（捕获所有异常）
- 缺少类型注解或 docstring
- 日志中包含敏感信息
- 直接修改函数入参

✅ **推荐：**
- 敏感信息从 .env 读取
- 捕获具体异常
- 完整的类型系统
- 掩码敏感信息
- 返回新对象

## 需要帮助？

- 完整文档：`@/Python项目开发准则.md`
- 快速清单：`@/.claude/dev-checklist.md`
- 编码约定：`@/.claude/conventions.md`
- 自动检查：`uv run python scripts/check.py`

## 三种 AI 协作方式

### 方式 1: 快速开发
```
请遵守《Python项目开发准则》：
- 完整类型注解 + docstring
- 异常处理规范、关键操作有日志
- 可运行的代码，包含单元测试（≥80% 覆盖率）
```

### 方式 2: 新功能开发
```
请严格遵守《Python项目开发准则》完成以下任务：

## 开发规范
- 所有代码必须符合 PEP 8 和项目编码规范
- 完整的类型注解、Google 风格 docstring
- 异常处理捕获具体异常，关键操作有日志

## 数据验证
- 使用 Pydantic v2 进行输入验证（参见第11章）

## 测试和质量
- 编写单元测试，覆盖率 ≥ 80%
- 运行 black、ruff、mypy 检查
```

### 方式 3: 代码审查
```
请按照《Python项目开发准则》审查以下代码：
1. 检查是否符合 PEP 8 和命名规范
2. 验证类型注解和 docstring 的完整性
3. 评估异常处理和日志的适当性
4. 指出改进建议（附上修复示例）
```
