259 lines
4.7 KiB
Markdown
259 lines
4.7 KiB
Markdown
# 代码风格与 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 配置推荐实现保存时自动格式化。
|