签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,258 @@
+# 代码风格与 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 配置推荐实现保存时自动格式化。