ops运维后台编码规范

通用运维后台 Python/Django 编码规范，适用于所有 ops 系统开发。

一、规范范围

• 所有新代码必须遵循 PEP8 编码规范
• PEP8 规范参考：https://pep8.org/

二、文件头注释（新建 .py 文件时必须）

# -*- coding: utf-8 -*-
"""
@File    : ${NAME}.py
@Desc    : ${DESCRIPTION}
@Author  : ${USER}
@Date    : ${DATE}
"""

三、函数 docstring 规范

3.1 代码行数多 → 必须分步说明

def sync_server_data(server_id):
    """
    同步服务器数据

    第一步：校验目标服务器状态
    第二步：执行数据导出
    第三步：数据传输到目标节点
    第四步：更新数据库记录
    第五步：发送通知

    :param server_id: 服务器ID
    :return: bool  是否成功
    """
    pass

3.2 代码行数少 → 简要注释即可

def get_server_status(server_id):
    """查询游戏服运行状态"""
    return Server.objects.get(id=server_id).status


def disable_user(uid):
    """批量禁用用户"""
    User.objects.filter(id=uid).update(is_active=False)

四、PEP8 代码规范

代码在 PyCharm / IDE 里应避免出现黄色波浪线（PEP8 违规提示）。

格式化：每次完成后用 IDE reformat（Ctrl+Alt+L / Cmd+Option+L），再提交。

五、Django + Celery 事务规范（高危！）

5.1 事务内调用异步任务的坑

transaction.atomic() 上下文内的 SQL 不会自动提交给 Celery 异步任务。异步任务在独立数据库连接中执行，不受当前事务影响。

❌ 错误：

with transaction.atomic():
    Task.objects.create(...)
    async_task.delay(...)  # 事务回滚，但任务已在独立连接执行

✅ 正确：

with transaction.atomic():
    Task.objects.create(...)
# 事务提交后再触发
async_task.delay(...)

5.2 异步任务路由

@app.task(queue='high_priority')
def critical_task():
    pass

@app.task(queue='default')
def normal_task():
    pass

六、日志轮转规范（防止磁盘撑爆）

所有 Web 服务必须配置日志轮转。

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.handlers.TimedRotatingFileHandler',
            'filename': '/var/log/ops_api/app.log',
            'when': 'midnight',
            'interval': 1,
            'backupCount': 30,
        },
    },
    'root': {
        'handlers': ['file'],
        'level': 'INFO',
    },
}

七、Django Admin 命令 vs 离线脚本

八、敏感信息过滤（必须遵守！）

示例：

# ❌ 硬编码
API_KEY = "sk-xxxxx-secret"

# ✅ 环境变量
API_KEY = os.environ.get("API_KEY", "")

# ❌ 日志打印敏感信息
logger.info(f"password={password}")

# ✅ 脱敏打印
logger.info(f"user_id={user_id}, action=login")

九、不要做什么

十、自检清单

每次提交前检查：

1. ✅ 无 PEP8 黄色/红色波浪线
2. ✅ 每个函数有 docstring
3. ✅ Ctrl+Alt+L 格式化后提交
4. ✅ 事务 + 异步任务场景已考虑
5. ✅ 无硬编码敏感信息
6. ✅ 日志配置了轮转