Ops Coding Standards — 运维编码标准

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 格式化后提交 事务 + 异步任务场景已考虑 无硬编码敏感信息 日志配置了轮转