back
loading skill details...
运维后台（Python/Django）编码规范与最佳实践，适用于 ops_api 等运维系统开发。当要求写ops代码、代码审查、检查编码规范、Python Django开发规范时自动激活。
---
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
# ❌ 硬编码
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` 目录部署到生产 | 部署前删除 |
---
## 十、自检清单
每次提交前检查：
1. ✅ 无 PEP8 黄色/红色波浪线
2. ✅ 每个函数有 docstring
3. ✅ Ctrl+Alt+L 格式化后提交
4. ✅ 事务 + 异步任务场景已考虑
5. ✅ 无硬编码敏感信息
6. ✅ 日志配置了轮转don't have the plugin yet? install it then click "run inline in claude" again.