# Python 注释与日志规范

本规范适用于项目内所有 Python 文件，便于维护与排查问题。

## 一、注释规范

### 1. 模块级（文件顶部）

- 保留或补充 **模块 docstring**：用一句话说明本模块职责；若逻辑复杂可加 2～3 行说明。
- 示例：
  ```python
  """
  操作日志：列表/筛选/导出、日志文件分析、tail 流式查看与下载。
  """
  ```

### 2. 类

- 每个对外类应有 **类 docstring**：说明职责、主要用法或注意点。
- 示例：`"""为每个请求生成或透传 Trace-Id，供日志与链路追踪使用。"""`

### 3. 函数/方法

- **公开接口**（view、action、公共 util）：必须写 docstring，包含用途、主要参数、返回值或异常。
- **私有方法**（单文件内使用）：若逻辑非自解释，用 1 行说明；简单 getter/setter 可省略。
- 复杂逻辑处可加 **行内注释**，说明「为什么」而不是「做什么」。

### 4. 不写注释的情况

- `__init__.py` 仅做导入时可无 docstring。
- 自解释的一行代码、标准 Django/DRF 样板可不注释。

---

## 二、日志规范

### 1. 统一使用模块 logger

- 每个需打日志的模块顶部：`logger = logging.getLogger(__name__)`
- 禁止用 `print()` 做调试输出，改为 `logger.debug()` 或 `logger.info()`。

### 2. 级别使用

| 级别     | 用途 |
|----------|------|
| `debug`  | 开发调试、详细参数/中间状态，生产可关。 |
| `info`   | 正常关键步骤：请求入口、登录/登出、重要业务完成。 |
| `warning`| 可恢复异常、校验失败、配置或数据异常。 |
| `error`  | 业务错误、外部调用失败，需关注。 |
| `exception` | 在 `except` 块中记录异常（含堆栈）。 |

### 3. 建议打日志的位置

- **View / action 入口**：`logger.info("操作简述", extra={"path": request.path, "user_id": ...})` 或简短一句。
- **异常处理**：`except` 中至少 `logger.exception(e)` 或 `logger.warning("...", exc_info=True)`。
- **关键分支**：如「跳过记录」「权限拒绝」「限流」等用 `info`/`warning`。
- **敏感信息**：不记录密码、完整 token；可记录 user_id、path、trace_id。

### 4. 格式

- 优先 **结构化**：`logger.info("msg", extra={"key": value})` 或占位：`logger.info("msg: path=%s", path)`。
- 避免在消息里做复杂运算或拼接大对象；必要时先算好再传入。

---

## 三、按文件类型建议

| 类型         | 注释重点           | 日志重点                 |
|--------------|--------------------|--------------------------|
| views/*.py   | 每个 action 用途、参数、返回 | 入口、权限/校验失败、异常 |
| utils/*.py   | 函数用途、参数、边界情况     | 异常、关键分支            |
| middleware   | 每个中间件职责、执行顺序     | 异常、跳过/生效条件       |
| models       | 模型与字段含义、约束        | 一般不打（ORM 层）        |
| conf/settings| 配置项含义、默认值、环境区分 | 可不打或仅启动时打        |

新写或大改的 py 文件按上述规范补充；存量文件在改动时顺带补齐注释与日志。
