代码风格与 Lint 规范

说明

统一的代码风格是团队协作的基础。本文档介绍项目的代码风格规范和 Lint 工具配置。

Python 代码风格

基本规范（PEP 8）

# ✅ 正确
def get_user_page(request):
    """查询用户分页数据"""
    page_no = int(request.GET.get('pageNo', 1))
    page_size = int(request.GET.get('pageSize', PAGE_SIZE))

    query = User.objects.filter(is_delete=False)
    query = query.order_by('-create_time')

    return R.ok(data=page_data)

# ❌ 错误
def GetUserPage(request):
    pageNo=int(request.GET.get('pageNo',1))
    query=User.objects.filter(is_delete=False)
    return R.ok(data=page_data)

命名规范

类型	规范	示例
文件名	snake_case	user_service.py
类名	PascalCase	UserAddView
函数名	snake_case	get_user_page
变量名	snake_case	page_no
常量名	UPPER_SNAKE_CASE	PAGE_SIZE
私有函数	_前缀	_apply_filters

导入规范

# 1. 标准库
import json
import logging
import datetime

# 2. 第三方库
from django.db import models
from django.core.paginator import Paginator

# 3. 本地模块
from application.user import forms
from utils import R
from utils.common import parse_request_body

注释规范

def add_user(request):
    """
    添加用户

    处理流程：
    1. 解析请求体中的JSON数据
    2. 表单验证
    3. 密码加密
    4. 创建数据库记录

    Args:
        request: HttpRequest对象

    Returns:
        R: 操作结果
    """
    pass

Ruff 配置

项目推荐使用 Ruff 进行 Python 代码检查和格式化：

# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort
    "N",    # pep8-naming
    "UP",   # pyupgrade
]

[tool.ruff.lint.isort]
known-first-party = ["application", "utils", "config", "middleware"]

使用命令

# 检查代码
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

前端代码风格

ESLint 配置

项目使用 ESLint 进行 TypeScript/Vue 代码检查：

// .eslintrc.cjs
module.exports = {
    extends: [
        'plugin:vue/vue3-recommended',
        '@vue/eslint-config-typescript',
        '@vue/eslint-config-prettier',
    ],
    rules: {
        'vue/multi-word-component-names': 'off',
        '@typescript-eslint/no-explicit-any': 'warn',
    },
};

Prettier 配置

// .prettierrc
{
    "printWidth": 120,
    "tabWidth": 4,
    "useTabs": false,
    "semi": true,
    "singleQuote": true,
    "trailingComma": "all",
    "bracketSpacing": true,
    "arrowParens": "always"
}

Stylelint 配置

// .stylelintrc.cjs
module.exports = {
    extends: [
        'stylelint-config-standard-scss',
        'stylelint-config-recommended-vue/scss',
    ],
    rules: {
        'selector-class-pattern': null,
    },
};

使用命令

# ESLint 检查
pnpm lint:eslint

# ESLint 自动修复
pnpm lint:eslint --fix

# Prettier 格式化
pnpm lint:prettier

# Stylelint 检查
pnpm lint:stylelint

# 全部检查
pnpm lint:eslint && pnpm lint:prettier && pnpm lint:stylelint

Pre-commit Hooks

使用 pre-commit 在提交前自动检查代码：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v9.0.0
    hooks:
      - id: eslint
        files: \.(js|ts|vue)$

  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.0.0
    hooks:
      - id: prettier
        files: \.(js|ts|vue|css|scss)$

安装 pre-commit

pip install pre-commit
pre-commit install

IDE 配置推荐

VS Code

// .vscode/settings.json
{
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": "explicit"
    },
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true
    }
}

推荐插件

Python:
- Ruff (Python linter/formatter)
- Python (Microsoft)

前端:
- ESLint
- Prettier
- Vue - Official
- TypeScript Vue Plugin (Volar)

总结

代码风格规范涵盖 Python（PEP 8 + Ruff）和前端（ESLint + Prettier + Stylelint）两个维度。通过 pre-commit hooks 在提交前自动检查，确保代码风格一致性。IDE 配置推荐实现保存时自动格式化。