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 # 推送前钩子
本规范指南确保了技术文章发布系统的代码质量、格式一致性和安全性，为项目的长期维护和团队协作提供了坚实的基础。
发表评论 取消回复