# 日志系统

<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->

:::tip 说明
通过 Python 标准库 `logging` 实现结构化日志，Django 框架内置日志配置，支持控制台 + 文件双输出。各模块通过 `logging.getLogger(__name__)` 获取 logger 实例。
:::

## Django 日志配置

在 `application/settings.py` 中可配置 `LOGGING` 字典（项目当前使用默认配置）：

```python
# application/settings.py 中可添加自定义日志配置
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{asctime} | {levelname:<7} | {name} | {message}',
            'style': '{',
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': 'logs/app.log',
            'maxBytes': 10 * 1024 * 1024,  # 10MB
            'backupCount': 5,
            'formatter': 'verbose',
            'encoding': 'utf-8',
        },
    },
    'root': {
        'handlers': ['console', 'file'],
        'level': 'INFO',
    },
}
```

## 使用方式

在各模块中获取 logger：

```python
import logging

logger = logging.getLogger(__name__)

logger.info("操作成功")
logger.warning("配置缺失")
logger.error(f"异常信息: {str(e)}")
```

## 日志格式

```
2025-03-06 14:30:25,123 | INFO    | application.example.services | 操作成功
```

格式说明：

| 字段 | 说明 |
|------|------|
| `asctime` | 时间戳 |
| `levelname` | 日志级别（右对齐7字符） |
| `name` | 模块名称 |
| `message` | 日志内容 |

## 日志级别

| 级别 | 数值 | 说明 |
|------|------|------|
| `DEBUG` | 10 | 调试信息，生产环境通常关闭 |
| `INFO` | 20 | 一般信息，记录正常操作 |
| `WARNING` | 30 | 警告信息，不影响运行但需关注 |
| `ERROR` | 40 | 错误信息，功能异常 |
| `CRITICAL` | 50 | 严重错误，系统不可用 |

## 业务模块中的日志使用

### Service 层

```python
# application/example/services.py
import logging

logger = logging.getLogger(__name__)

def get_example_page(request):
    try:
        # 业务逻辑 ...
        return R.ok(data=page_data)
    except Exception as e:
        logging.error(f"查询案例分页数据异常: {str(e)}")
        return R.failed(msg="查询失败，请稍后重试")
```

### 视图层

```python
# application/upload/views.py
import logging

logging.info(f"上传文件的字段名称: {field_name}")
```

## 操作日志

除了应用日志外，系统通过 `@operation_log` 装饰器自动记录用户的写操作日志，存储到数据库中。详见 [操作日志](/zh/volume4/core/operation-log) 章节。

```python
from application.operation_log.decorators import operation_log
from application.operation_log.constants import LogType

class ExampleAddView(PermissionRequired, View):
    @operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
    def post(self, request):
        result = services.add_example(request)
        return result
```

## 日志轮转

当日志文件达到指定大小时自动轮转：

```
logs/app.log       ← 当前日志
logs/app.log.1     ← 最近一次轮转
logs/app.log.2     ← 倒数第二次
logs/app.log.3
logs/app.log.4
logs/app.log.5     ← 最早的备份（超过自动删除）
```

:::tip 温馨提示
生产环境建议配置日志轮转，防止日志文件无限增长撑爆磁盘。`RotatingFileHandler` 按文件大小轮转，`TimedRotatingFileHandler` 按时间轮转。
:::

## 总结

日志系统基于 Python 标准库 `logging`，通过 Django 的 `LOGGING` 配置统一管理。各模块通过 `logging.getLogger(__name__)` 获取 logger 实例，支持控制台和文件双输出。操作日志通过 `@operation_log` 装饰器自动记录到数据库。