Skill: freepengyang/ops-coding-standards (version 1.0.0)

--- 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 文件时必须） ```python # -*- coding: utf-8 -*- """ @File : ${NAME}.py @Desc : ${DESCRIPTION} @Author : ${USER} @Date : ${DATE} """ ``` --- ## 三、函数 docstring 规范 ### 3.1 代码行数多 → 必须分步说明 ```python def sync_server_data(server_id): """ 同步服务器数据 第一步：校验目标服务器状态 第二步：执行数据导出 第三步：数据传输到目标节点 第四步：更新数据库记录 第五步：发送通知 :param server_id: 服务器ID :return: bool 是否成功 """ pass ``` ### 3.2 代码行数少 → 简要注释即可 ```python 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 异步任务。异步任务在独立数据库连接中执行，不受当前事务影响。 **❌ 错误**： ```python with transaction.atomic(): Task.objects.create(...) async_task.delay(...) # 事务回滚，但任务已在独立连接执行 ``` **✅ 正确**： ```python with transaction.atomic(): Task.objects.create(...) # 事务提交后再触发 async_task.delay(...) ``` ### 5.2 异步任务路由 ```python @app.task(queue='high_priority') def critical_task(): pass @app.task(queue='default') def normal_task(): pass ``` --- ## 六、日志轮转规范（防止磁盘撑爆） 所有 Web 服务必须配置日志轮转。 ```python 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}` 或配置文件读取 | | 在日志中打印敏感字段 | 过滤或脱敏处理 | | 在错误信息中暴露内部路径/接口 | 返回通用错误信息 | **示例**： ```python # ❌ 硬编码 [REDACTED_SECRET]" # ✅ 环境变量 [REDACTED_SECRET]"API_KEY", "") # ❌ 日志打印敏感信息 logger.info(f"[REDACTED_SECRET]") # ✅ 脱敏打印 logger.info(f"user_id={user_id}, action=login") ``` --- ## 九、不要做什么 | ❌ 禁止 | ✅ 正确做法 | |--------|-----------| | 事务内直接调用 Celery 异步任务 | 事务提交后再触发 | | 硬编码密码/密钥在代码中 | 环境变量或安全存储 | | 不格式化代码就提交 | Ctrl+Alt/L 格式化后提交 | | 代码有黄色波浪线不处理 | 立即修复 PEP8 违规 | | 在生产代码中暴露内部接口信息 | 统一错误返回值 | | 把 `.git` 目录部署到生产 | 部署前删除 | --- ## 十、自检清单 每次提交前检查： 1. ✅ 无 PEP8 黄色/红色波浪线 2. ✅ 每个函数有 docstring 3. ✅ Ctrl+Alt+L 格式化后提交 4. ✅ 事务 + 异步任务场景已考虑 5. ✅ 无硬编码敏感信息 6. ✅ 日志配置了轮转


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)