# 编码约定速查

## 命名规范

```python
# 模块、函数、变量：snake_case
def process_user_data():
    user_email = "user@example.com"
    max_retries = 3

# 类：PascalCase
class UserManager:
    pass

# 常量：UPPER_SNAKE_CASE
DEFAULT_TIMEOUT = 30
MAX_BATCH_SIZE = 1000
```

## 类型注解

```python
# 所有函数必须有类型注解
def fetch_data(
    user_id: int,
    include_metadata: bool = True
) -> dict[str, Any]:
    """Docstring here"""
    pass

# 函数参数中的可选值
from typing import Optional
def get_user(user_id: int) -> Optional[User]:
    pass

# 或使用联合类型（Python 3.10+）
def get_user(user_id: int) -> User | None:
    pass

# 列表、字典的类型注解
users: list[User] = []
config: dict[str, int] = {}
results: set[str] = set()

# 异步函数
async def fetch_data_async(url: str) -> dict:
    pass
```

## Docstring 格式（Google 风格）

```python
def calculate_total(items: list[dict], tax_rate: float) -> float:
    """计算订单总价含税。

    Args:
        items: 订单项列表，每项包含 'price' 和 'quantity'
        tax_rate: 税率，范围 0-1

    Returns:
        总价（含税）

    Raises:
        ValueError: 税率超出有效范围时

    Examples:
        >>> items = [{"price": 10.0, "quantity": 2}]
        >>> calculate_total(items, 0.1)
        22.0
    """
    pass
```

## 异常处理

```python
# ❌ 禁止
try:
    result = do_something()
except:
    pass

# ✅ 必须
try:
    result = do_something()
except ValueError as e:
    logger.error(f"值错误: {e}")
    raise CustomError(f"处理失败: {e}") from e
except KeyError as e:
    logger.error(f"键错误: {e}")
    raise
```

## 日志记录

```python
import logging
logger = logging.getLogger(__name__)

# INFO - 重要的业务事件
logger.info(f"用户 {user_id} 登录成功")

# DEBUG - 开发调试信息
logger.debug(f"接收到请求参数: {params}")

# WARNING - 降级处理或重试
logger.warning(f"数据库连接超时，使用缓存数据")

# ERROR - 可恢复的错误
logger.error(f"数据处理失败: {error}", exc_info=True)

# CRITICAL - 不可恢复的错误
logger.critical("数据库连接丢失，应用无法继续运行")
```

## 导入顺序

```python
# 1. 内置模块
import os
import sys
from pathlib import Path
from typing import Optional

# 2. 第三方模块
import numpy as np
import pandas as pd
from fastapi import FastAPI
from pydantic import BaseModel

# 3. 本地模块
from autoreport.models import User
from autoreport.services import UserService
```

## 处理可选的依赖

```python
# 如果某个库不是必需的
try:
    import spire  # 可选库
    SPIRE_AVAILABLE = True
except ImportError:
    SPIRE_AVAILABLE = False

def process_with_watermark(doc):
    if not SPIRE_AVAILABLE:
        logger.warning("Spire 库未安装，跳过水印处理")
        return doc
    # ... 使用 Spire
```

## 常用的类型注解

```python
from typing import Any, Callable, Iterable, Sequence
from collections.abc import Iterator, Awaitable

# 任意类型
value: Any = None

# 回调函数
callback: Callable[[int, str], bool]

# 可迭代对象
items: Iterable[str]

# 生成器
def read_lines() -> Iterator[str]:
    for line in file:
        yield line

# 异步可等待对象
result: Awaitable[dict]

# 联合类型
response: int | str | None

# 类型别名
UserId = int
def get_user(user_id: UserId) -> dict:
    pass
```
