签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,146 @@
+# 日志系统
+
+<!-- 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` 装饰器自动记录到数据库。