技术文章发布系统 - Lint规则与代码规范指南

1. 代码规范概览1.1 规范目标一致性: 确保代码风格统一，提高可读性可维护性: 降低代码复杂度，便于长期维护可靠性: 通过静态检查提前发现潜在错误性能: 优化代码性能，提升用户体验1.2 规范层级强制执行 (Error) ← 必须修复，否则无法构建 警告级别 (Warning) ← 强烈建议修复 建议级别 (Info) ← 可选修复，但推荐 关闭规则 (Off) ← 不适用当前项目 2. ESLint配置规则2.1 TypeScript项目配置 (.eslintrc.json){ "root": true, "parser": "@typescript-eslint/parser", "parserOptions": { "ecmaVersion": 2022, "sourceType": "module", "project": "./tsconfig.json" }, "plugins": [ "@typescript-eslint", "react", "react-hooks", "import", "jsx-a11y", "prettier" ], "extends": [ "eslint:recommended", "@typescript-eslint/recommended", "@typescript-eslint/recommended-requiring-type-checking", "plugin:react/recommended", "plugin:react-hooks/recommended", "plugin:import/recommended", "plugin:import/typescript", "plugin:jsx-a11y/recommended", "prettier" ], "rules": { // TypeScript特定规则 "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }], "@typescript-eslint/explicit-function-return-type": ["warn", { "allowExpressions": true, "allowTypedFunctionExpressions": true }], "@typescript-eslint/no-explicit-any": "error", "@typescript-eslint/no-non-null-assertion": "warn", "@typescript-eslint/prefer-nullish-coalescing": "error", "@typescript-eslint/prefer-optional-chain": "error", "@typescript-eslint/no-floating-promises": "error", "@typescript-eslint/await-thenable": "error", "@typescript-eslint/no-misused-promises": "error", // React规则 "react/react-in-jsx-scope": "off", "react/prop-types": "off", "react/jsx-uses-react": "off", "react/jsx-uses-vars": "error", "react/jsx-key": "error", "react/jsx-no-target-blank": "error", "react/jsx-curly-brace-presence": ["warn", "never"], "react/self-closing-comp": "error", "react/jsx-boolean-value": ["error", "never"], // Import规则 "import/order": ["error", { "groups": [ "builtin", "external", "internal", ["parent", "sibling"], "index" ], "newlines-between": "always", "alphabetize": { "order": "asc", "caseInsensitive": true } }], "import/no-duplicates": "error", "import/no-unresolved": "off", // 通用代码规则 "no-console": ["warn", { "allow": ["warn", "error"] }], "no-debugger": "error", "no-duplicate-imports": "error", "no-unused-expressions": "error", "no-useless-return": "error", "prefer-const": "error", "prefer-template": "error", "template-curly-spacing": "error", "object-shorthand": "error", "prefer-arrow-callback": "error", "arrow-spacing": "error", "no-var": "error", "eqeqeq": ["error", "always"], "curly": ["error", "all"], "brace-style": ["error", "1tbs"], "comma-dangle": ["error", "never"], "semi": ["error", "always"], "quotes": ["error", "single"], "indent": ["error", 2], "max-len": ["warn", { "code": 120 }], "max-lines": ["warn", { "max": 300 }], "complexity": ["warn", 10], "max-depth": ["warn", 3], "max-params": ["warn", 4] }, "settings": { "react": { "version": "detect" }, "import/resolver": { "typescript": {} } } } 2.2 React Hooks规则{ "rules": { "react-hooks/rules-of-hooks": "error", "react-hooks/exhaustive-deps": "warn" } } 2.3 性能相关规则{ "rules": { "react/jsx-no-constructed-context-values": "error", "react/jsx-no-useless-fragment": "error", "react/no-unused-prop-types": "error", "react/no-unused-state": "error", "react/prefer-stateless-function": "warn" } } 3. Markdown Lint配置3.1 基础配置 (.markdownlint.json){ "default": true, "MD001": true, // 标题层级必须递增 "MD003": { "style": "atx" // 使用#风格的标题 }, "MD004": { "style": "dash" // 无序列表使用- }, "MD005": true, // 同一层级列表的缩进必须一致 "MD006": true, // 一级标题不能缩进 "MD007": { "indent": 2 // 无序列表缩进2个空格 }, "MD009": { "br_spaces": 2 // 行末空格不超过2个 }, "MD010": { "code_blocks": false // 代码块中允许制表符 }, "MD011": true, // 禁止反向链接语法 "MD012": { "maximum": 2 // 连续空行不超过2行 }, "MD013": { "line_length": 120, // 行长度限制 "heading_line_length": 120, "code_block_line_length": 120, "tables": false // 表格不受行长度限制 }, "MD014": true, // 代码块中美元符号提示符 "MD018": true, // 列表标记后必须有空格 "MD019": true, // 列表标记后不能有多个空格 "MD020": true, // 列表标记后必须有空格 "MD021": true, // 列表标记后不能有多个空格 "MD022": true, // 标题上下必须有空行 "MD023": true, // 标题开头不能有空格 "MD024": { "siblings_only": true // 允许非兄弟标题重复 }, "MD025": { "level": 1, // 一级标题只能出现一次 "front_matter_title": "" }, "MD026": { "punctuation": ".,;:!?" // 标题末尾不能有的标点 }, "MD027": true, // 引用标记后必须有空格 "MD028": true, // 引用块不能空行 "MD029": { "style": "one_or_two" // 有序列表样式 }, "MD030": { "ul_single": 1, // 无序列表单级空格数 "ol_single": 1, // 有序列表单级空格数 "ul_multi": 1, // 无序列表多级空格数 "ol_multi": 1 // 有序列表多级空格数 }, "MD031": true, // 代码块上下必须有空行 "MD032": true, // 列表上下必须有空行 "MD033": { "allowed_elements": ["table", "thead", "tbody", "tr", "th", "td", "br", "img", "a"] }, "MD034": true, // 裸URL必须用尖括号包裹 "MD035": { "style": "---" // 水平线样式 }, "MD036": { "punctuation": ".,;:!?" // 强调标记不能包含的标点 }, "MD037": true, // 强调标记内不能有空格 "MD038": true, // 代码块内空格一致性 "MD039": true, // 链接文本空格一致性 "MD040": true, // 代码块必须标明语言 "MD041": false, // 文档开头可以不是一级标题 "MD042": true, // 空链接检查 "MD043": false, // 不强制要求特定标题结构 "MD044": { "names": [], // 专有名词检查 "code_blocks": false }, "MD045": true, // 图片必须有alt文本 "MD046": { "style": "fenced" // 代码块风格 }, "MD047": true, // 文件末尾需要空行 "MD048": { "style": "backtick" // 代码块分隔符风格 } } 3.2 技术文章专用规则{ "tech_article_rules": { "MD013": { "line_length": 120, "exceptions": ["table", "code_block"] }, "MD024": { "allow_duplicates": ["简介", "概述", "总结", "结论"] }, "MD033": { "allowed_elements": [ "table", "thead", "tbody", "tr", "th", "td", "img", "br", "a", "sup", "sub", "code" ] }, "MD041": false, "first_line_heading": false } } 4. Prettier代码格式化4.1 基础配置 (.prettierrc.json){ "semi": true, "trailingComma": "none", "singleQuote": true, "printWidth": 120, "tabWidth": 2, "useTabs": false, "bracketSpacing": true, "bracketSameLine": false, "arrowParens": "avoid", "endOfLine": "lf", "quoteProps": "as-needed", "jsxSingleQuote": true, "proseWrap": "preserve" } 4.2 忽略配置 (.prettierignore)# 构建产物 dist/ build/ *.min.js *.min.css # 依赖目录 node_modules/ # 日志文件 *.log logs/ # 环境配置 .env* # 锁文件 package-lock.json yarn.lock # 文档输出 output/ reports/ # 临时文件 .tmp/ tmp/ 5. StyleLint CSS规则5.1 Tailwind CSS配置 (.stylelintrc.json){ "extends": [ "stylelint-config-standard", "stylelint-config-tailwindcss" ], "rules": { "at-rule-no-unknown": [true, { "ignoreAtRules": ["tailwind", "apply", "layer", "variants", "responsive", "screen"] }], "function-no-unknown": [true, { "ignoreFunctions": ["theme", "screen"] }], "selector-class-pattern": null, "custom-property-pattern": null, "property-no-unknown": [true, { "ignoreProperties": ["theme", "screen"] }] } } 6. Git提交规范6.1 Commit Message格式<type>(<scope>): <subject> <body> <footer> 6.2 提交类型 (Commit Types)types: feat: "新功能" fix: "Bug修复" docs: "文档更新" style: "代码格式调整" refactor: "代码重构" test: "测试相关" chore: "构建/工具" perf: "性能优化" ci: "CI/CD相关" build: "构建系统" revert: "代码回退" scopes: - api # API接口 - ui # 用户界面 - articles # 文章管理 - review # 审核系统 - build # 构建系统 - config # 配置文件 - docs # 文档 - i18n # 国际化 6.3 提交示例feat(articles): 添加文章批量导入功能 - 支持Markdown文件批量上传 - 自动提取文章元数据 - 验证文章格式规范性 Closes #123 7. 代码审查规范7.1 审查清单code_review_checklist: functionality: - "功能是否按预期工作" - "边界条件是否处理" - "错误处理是否完善" - "性能是否优化" readability: - "代码是否易于理解" - "命名是否清晰" - "注释是否充分" - "复杂度是否适中" maintainability: - "是否遵循设计模式" - "是否可测试" - "是否可扩展" - "是否解耦" security: - "是否存在安全漏洞" - "输入是否验证" - "敏感信息是否保护" - "权限是否正确" 7.2 Pull Request模板## 变更描述 简要描述这次变更的内容和目的 ## 变更类型 - [ ] Bug修复 - [ ] 新功能 - [ ] 代码重构 - [ ] 文档更新 - [ ] 性能优化 ## 测试情况 - [ ] 单元测试通过 - [ ] 集成测试通过 - [ ] 手动测试验证 ## 质量检查 - [ ] 代码遵循项目规范 - [ ] 通过ESLint检查 - [ ] 通过TypeScript类型检查 - [ ] 更新相关文档 ## 关联Issue Fixes #(issue编号) ## 截图（如适用） 添加相关的截图或GIF 8. 性能规范8.1 前端性能指标interface PerformanceMetrics { // 核心指标 first_contentful_paint: "< 1.8s"; // 首次内容绘制 largest_contentful_paint: "< 2.5s"; // 最大内容绘制 first_input_delay: "< 100ms"; // 首次输入延迟 cumulative_layout_shift: "< 0.1"; // 累积布局偏移 // 构建指标 build_time: "< 5min"; // 构建时间 bundle_size: "< 500KB"; // 包大小 chunk_count: "< 10"; // 代码块数量 // 运行时指标 memory_usage: "< 100MB"; // 内存使用 cpu_usage: "< 50%"; // CPU使用 network_requests: "< 50"; // 网络请求数 } 8.2 代码复杂度限制{ "complexity_rules": { "max_function_length": 50, "max_file_length": 300, "max_class_methods": 20, "max_nested_depth": 3, "max_cyclomatic_complexity": 10, "max_cognitive_complexity": 15 } } 9. 安全检查规范9.1 安全编码规则const securityRules = { // 输入验证 input_validation: { "no-eval": "error", "no-implied-eval": "error", "no-script-url": "error" }, // 敏感信息 sensitive_data: { "no-hardcoded-credentials": "error", "no-hardcoded-keys": "error", "no-hardcoded-secrets": "error" }, // 代码注入 injection_prevention: { "no-inner-html": "warn", "no-document-write": "error", "no-dangerously-set-inner-html": "error" } }; 9.2 依赖安全检查{ "dependency_scanning": { "enabled": true, "severity_threshold": "high", "auto_fix": true, "whitelist": [], "blacklist": [] } } 10. 可执行检查命令10.1 代码质量检查# 运行所有lint检查 npm run lint # 单独运行ESLint npm run lint:eslint # 单独运行Prettier检查 npm run lint:prettier # 运行TypeScript类型检查 npm run lint:typescript # 运行Markdown格式检查 npm run lint:markdown # 运行CSS样式检查 npm run lint:style 10.2 自动修复# 自动修复所有可修复问题 npm run lint:fix # 自动修复ESLint问题 npm run lint:eslint:fix # 自动修复Prettier格式 npm run lint:prettier:fix # 自动修复Markdown格式 npm run lint:markdown:fix 10.3 代码质量报告# 生成完整质量报告 npm run quality:report # 生成代码复杂度报告 npm run complexity:report # 生成测试覆盖率报告 npm run coverage:report # 生成安全扫描报告 npm run security:report 10.4 Git提交检查# 提交前检查 npm run pre-commit # 提交信息格式验证 npm run commitlint # 分支命名规范检查 npm run branchlint 11. 配置文件位置Lint配置文件: ├── .eslintrc.json # ESLint规则配置 ├── .prettierrc.json # Prettier格式配置 ├── .prettierignore # Prettier忽略文件 ├── .markdownlint.json # Markdown格式规则 ├── .markdownlintignore # Markdown忽略文件 ├── .stylelintrc.json # CSS样式规则 ├── commitlint.config.js # 提交信息规范 ├── .gitignore # Git忽略文件 ├── .eslintignore # ESLint忽略文件 ├── tsconfig.json # TypeScript配置 └── package.json # 脚本命令配置 脚本文件: ├── scripts/ │ ├── lint/ │ │ ├── eslint.js # ESLint执行脚本 │ │ ├── prettier.js # Prettier执行脚本 │ │ ├── markdownlint.js # Markdown检查脚本 │ │ └── fix-all.js # 自动修复脚本 │ └── quality/ │ ├── complexity.js # 复杂度分析 │ ├── security.js # 安全扫描 │ └── report.js # 质量报告生成 └── hooks/ ├── pre-commit # 提交前钩子 ├── commit-msg # 提交信息钩子 └── pre-push # 推送前钩子 本规范指南确保了技术文章发布系统的代码质量、格式一致性和安全性，为项目的长期维护和团队协作提供了坚实的基础。