# 代码风格与 Lint 规范

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

## Python 代码风格

### 基本规范（PEP 8）

```python
# ✅ 正确
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` |

### 导入规范

```python
# 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
```

### 注释规范

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

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

    Args:
        request: HttpRequest对象

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

## Ruff 配置

项目推荐使用 [Ruff](https://docs.astral.sh/ruff/) 进行 Python 代码检查和格式化：

```toml
# 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"]
```

### 使用命令

```bash
# 检查代码
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .
```

## 前端代码风格

### ESLint 配置

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

```javascript
// .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 配置

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

### Stylelint 配置

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

### 使用命令

```bash
# 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 在提交前自动检查代码：

```yaml
# .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

```bash
pip install pre-commit
pre-commit install
```

## IDE 配置推荐

### VS Code

```json
// .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 配置推荐实现保存时自动格式化。