Metadata

name: ops-coding-standards
description: 运维后台（Python/Django）编码规范与最佳实践，适用于 ops_api 等运维系统开发。当要求写ops代码、代码审查、检查编码规范、Python Django开发规范时自动激活。
triggers: ["(.*) ops (.*) 代码规范 (.*)","(.*) 运维后台 (.*) 开发规范 (.*)","(.*) django (.*) 编码规范 (.*)","(.*) python (.*) 代码审查 (.*)","(.*) celery (.*) 事务 (.*)"]
required_commands: []
required_environment_variables: []

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 违规提示）。

违规	错误	正确
运算符缺空格	`a+b`	`a + b`
逗号后缺空格	`def f(a,b)`	`def f(a, b)`
单行过长	超过120字符	换行或拆分
import 顺序错误	先 import 第三方	标准库 → 第三方 → 本地

格式化：每次完成后用 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 离线脚本

场景	推荐方式
Web 后台触发的运维动作	Django Admin 命令（management/commands/）
纯定时任务（crontab）	离线脚本
需要版本控制	Django Admin 命令

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

❌ 禁止	✅ 正确做法
硬编码密码/密钥/Secret 在代码中	使用环境变量 `${VAR}` 或配置文件读取
在日志中打印敏感字段	过滤或脱敏处理
在错误信息中暴露内部路径/接口	返回通用错误信息

示例：

# ❌ 硬编码
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")

九、不要做什么

❌ 禁止	✅ 正确做法
事务内直接调用 Celery 异步任务	事务提交后再触发
硬编码密码/密钥在代码中	环境变量或安全存储
不格式化代码就提交	Ctrl+Alt/L 格式化后提交
代码有黄色波浪线不处理	立即修复 PEP8 违规
在生产代码中暴露内部接口信息	统一错误返回值
把 `.git` 目录部署到生产	部署前删除

十、自检清单

每次提交前检查：

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

Ops Coding Standards

安装技能