Chat2DB Community 前端代码规范实战ESLint 与 Stylelint 的零告警 Linting 体系解析【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DBChat2DB Community 前端chat2db-community-client是一套基于 Umi 4、React、TypeScript 与 Ant Design 5 构建的大型数据库客户端界面代码规模庞大且横跨业务、工具与样式等多个层面。为了保证多人在大规模改动下仍能维持可维护的源码质量仓库以 LINTING.md 为基准建立了一套零错误、零警告的双引擎 Linting 体系ESLint 负责 JavaScript/TypeScript 源码Stylelint 负责 CSS/Less 样式。本文将以此文档为核心结合仓库中的 package.json、.eslintrc.js、.stylelintrc.json 等真实配置完整讲解该体系的设计原则、命令用法、关键规则含义与生成的豁免清单帮助你快速理解并合规地在 Chat2DB Community 前端中编写代码。一、Linting 体系总览双引擎与统一入口1. 双引擎分工依据 LINTING.mdCommunity 前端采用两条检查链ESLint检查src下的 JavaScript 与 TypeScript 源码*.js / *.jsx / *.ts / *.tsx负责语法正确性、未使用变量/导入、React 组件书写习惯、TypeScript 类型约束等Stylelint检查 CSS 与 Less 样式文件*.css / *.less负责类名命名、keyframes 命名、媒体查询语法等样式层面的规范。两条检查链并非各自为政而是由yarn lint一键串联执行并且将告警warning视为失败——这与多数项目warning 可容忍的默认做法截然不同是理解本仓库代码规范的第一要义。2. 统一命令入口yarn lint在 package.json 的scripts中可以看到该体系的最小入口lint: yarn lint:eslint yarn lint:style, lint:eslint: eslint \src/**/*.{js,jsx,ts,tsx}\ --max-warnings0, lint:style: stylelint \src/**/*.{css,less}\ --max-warnings0三个脚本各自含义脚本实际执行的命令作用范围关键参数yarn lint依次执行下方两个脚本全部源码与样式保证串行前者失败则中断yarn lint:eslinteslint src/**/*.{js,jsx,ts,tsx} --max-warnings0所有 JS/TS 源码文件--max-warnings0出现任意一条 warning 即非零退出yarn lint:stylestylelint src/**/*.{css,less} --max-warnings0所有 CSS/Less 样式文件同上值得强调的细节是--max-warnings0它把 warning 的容忍阈值设为 0意味着即使 ESLint/Stylelint 只是输出了一条 warning命令也会以失败退出。这与 LINTING.md 中Maintained source must pass with zero errors and zero warnings受维护的源码必须以零错误、零警告通过的硬性要求完全对应。二、源码规则零容忍背后的四条铁律LINTING.md 的 Source Rules 一节给出了四条面向开发者的源码约束逐条拆解如下。规则一零错误、零警告任何受维护的源码即src下被 ESLint/Stylelint 覆盖的文件都必须同时满足零错误与零警告。这意味着提交前必须执行yarn lint或至少yarn lint:eslint yarn lint:styleCI 中对 lint 失败零容忍不允许带 warning 合并即便某个 warning 看起来无害例如多余的 import 或未使用的变量也会被拦截。规则二禁止通过降级规则来通过 CI文档明确规定Do not disable or downgrade rules to make CI pass. Fix the source or update a rule only when the project runtime or syntax contract has changed.即禁止为了通过 CI 而关闭或降级规则。只有当下述两种情况成立时才允许改动规则本身项目运行时行为发生了变化语法契约发生了变化。换句话说正常的业务迭代中遇到 lint 报错首选方案永远是修改源码本身而不是在.eslintrc.js中把对应规则从2error降为1warning或0off更不应该在代码中使用// eslint-disable注释来绕开检查。这条约定保障了规则集合长期稳定也防止了规则被悄悄稀释导致的规范退化。规则三未使用的回调参数必须以下划线开头Intentionally unused callback parameters must start with_.对于故意不使用的回调参数命名必须以_开头。这一约定的根源可以在 .eslintrc.js 中找到项目使用unused-imports插件的no-unused-vars规则并配置了unused-imports/no-unused-vars: [ 2, { args: after-used, argsIgnorePattern: ^_, caughtErrors: all, caughtErrorsIgnorePattern: ^_, destructuredArrayIgnorePattern: ^_, ignoreRestSiblings: true, vars: all, varsIgnorePattern: ^_, }, ],其中的argsIgnorePattern: ^_、caughtErrorsIgnorePattern: ^_、destructuredArrayIgnorePattern: ^_、varsIgnorePattern: ^_四个选项共同实现了以下划线开头的标识符豁免未使用检查的机制。典型场景包括// 正确显式声明本参数有意不使用 arr.forEach((item, _index) { /* 只用 item */ }); // 正确catch 子句故意不使用错误对象 try { /* ... */ } catch (_err) { /* 静默处理 */ }相反如果某个参数未使用但又没有_前缀就会被unused-imports/no-unused-vars严重级别为2即 error拦截。规则四CSS 类名命名允许 camelCase 与 kebab-caseCSS module classes may use camelCase or kebab-case. Global third-party class names may also use PascalCase.CSS Module 的类名允许 camelCase 或 kebab-case全局第三方库的类名还额外允许 PascalCase。这一规则在 .stylelintrc.json 中有对应的正则实现selector-class-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected class selector to use camelCase or kebab-case } ]该正则要求类选择器以字母开头后续只允许字母、数字与连字符从而同时覆盖dataTablecamelCase与data-tablekebab-case两种合法写法并排除掉下划线等其他字符。同文件中的keyframes-name-pattern对动画关键帧命名施加了相同约束keyframes-name-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected keyframe name to use camelCase or kebab-case } ]三、配置文件的真实面貌ESLint 规则拆解.eslintrc.js 是 ESLint 的全部依据。其组成结构如下1. 解析器与插件parser: typescript-eslint/parser, plugins: [typescript-eslint, babel, react-hooks, react, unused-imports],typescript-eslint/parser让 ESLint 能解析 TypeScript 语法react-hooks/reactReact 专属规则unused-imports专门负责未使用导入的清理是本仓库零告警目标的关键插件env声明了browser与es2021两个环境。2. 继承的规则集extends: [ eslint:recommended, plugin:typescript-eslint/recommended, plugin:react/recommended, plugin:react/jsx-runtime, ],注意到仓库有意注释掉了airbnb-base与prettier相关配置注释中说明airbnb-base 已包含 import 插件prettier 相关配置因格式化交给 Prettier 处理而禁用。这说明本仓库选择了规则检查交给 ESLint、格式化交给 Prettier的职责分离方案——.prettierrc 中printWidth: 120、singleQuote: true、trailingComma: all等即为格式化侧的真实约定。3. 值得关注的代表性规则结合 LINTING.md 与源码现状以下规则对日常开发影响最直接规则级别含义unused-imports/no-unused-imports2error未使用的 import 一律报错杜绝顺手留下的 importunused-imports/no-unused-vars2error未使用的变量报错但^_前缀可豁免max-len1warning单行超过 120 字符发出警告ignoreStrings、ignoreUrls、ignoreRegExpLiterals为 true字符串、URL、正则字面量不计入typescript-eslint/no-var-requires2禁止require()式导入统一使用 ESM 语法new-cap2构造函数名必须以大写字母开头default-case2switch语句必须包含default分支prefer-arrow-callback2尽量使用箭头函数回调no-param-reassign2props: false禁止对函数参数重新赋值max-classes-per-file2单文件最多允许 10 个类react/self-closing-comp2无子节点的组件必须使用自闭合语法react/jsx-indent-props2JSX 属性缩进为两个空格react/jsx-tag-spacing2规范 JSX 标签定界符周围的空格typescript-eslint/no-shadow1warning禁止遮蔽外部作用域变量注释标注 TODO考虑提升为 2与此同时不少在旧项目中常见、但在强类型 高版本工具链下冗余的规则被显式关闭例如no-undef交给 TypeScript 检查、no-unused-vars与typescript-eslint/no-unused-vars交给unused-imports插件统一处理、react/prop-types类型由 TypeScript 提供、typescript-eslint/explicit-function-return-type不强制显式返回类型、typescript-eslint/no-explicit-any允许显式 any等。这些关闭同样是经过权衡的工程决策与不随意降级规则的约定并不矛盾——它们是既定基线的一部分。4. 未使用变量豁免与_前缀的完整语义前面提到的四个*IgnorePattern: ^_选项合在一起保证了文档中未使用回调参数以_开头的约定在args、caughtErrors、destructuredArray、vars四种场景下均生效。同时ignoreRestSiblings: true意味着const { a, ...rest } obj中未被使用的a不会报错——这是对象解构时常用的安全模式。四、Stylelint 配置解读样式层的命名与语法约束.stylelintrc.json 结构非常精简{ extends: [stylelint-config-standard-less], rules: { media-feature-range-notation: prefix, keyframes-name-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected keyframe name to use camelCase or kebab-case } ], selector-class-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected class selector to use camelCase or kebab-case } ] } }三个要点基线stylelint-config-standard-less同时提供了 Stylelint 标准规则与 Less 语法支持因此无需在项目中单独引入 Less 解析器配置media-feature-range-notation: prefix媒体查询的范围写法要求使用前缀记法如(min-width: 768px)而非现代(width 768px)记法以兼顾更广的兼容面两条命名规则类选择器与 keyframes 名称都必须匹配^[A-Za-z][A-Za-z0-9-]*$与 LINTING.md 中camelCase 或 kebab-case 皆可的表述一一对应并允许第三方全局类使用 PascalCase该正则天然允许大写字母开头。五、生成的豁免文件为什么只有这两个例外LINTING.md 明确指出整个src下只有两个文件被豁免检查且仅限精确路径匹配src/assets/fonts/new-chat2db-colourful-iconfont.jssrc/assets/fonts/new-chat2db-iconfont.js这两个文件是阿里 Iconfont 字体图标的导出产物包含压缩过的生成式运行时代码。它们的豁免理由非常实际既然代码由图标平台生成器产出人工编辑不仅无意义还可能破坏字体图标映射。正确维护方式是回到生成器重新导出并覆盖文件而不是手改。这一豁免在 .eslintrc.js 的ignorePatterns中有完全一致的落地ignorePatterns: [ // Alibaba Iconfont exports. Regenerate these files instead of editing the minified vendor runtime. src/assets/fonts/new-chat2db-colourful-iconfont.js, src/assets/fonts/new-chat2db-iconfont.js, ],同时文档强调 No other source path is exempt from ESLint or Stylelint——除这两条精确路径外任何其他源码路径都不存在豁免包括构建产物目录、mock 数据乃至测试文件如src/**/*.test.ts也在lint:eslint的src/**/*.{js,jsx,ts,tsx}覆盖范围内。六、本地执行与工程实践1. 前置条件依据 readme.md在chat2db-community-client目录下运行 Linting 前需要Node.js18.17.0 或更高版本见 package.json 的engines字段使用 Yarn 且锁定仓库自带的 yarn.lock安装命令为yarn install --frozen-lockfile不要生成 npm/pnpm 锁文件。2. 标准执行流程# 进入前端目录 cd chat2db-community-client # 一键执行全部 lintESLint Stylelintwarning 即失败 yarn lint # 也可以单独执行某一条链 yarn lint:eslint # 仅检查 JS/TS 源码 yarn lint:style # 仅检查 CSS/Less 样式3. 与其他质量门禁的配合Linting 只是 Community 前端质量门禁的一环。在 package.json 的prebuild:web:community中可以看到正式构建前还会串行运行数十项针对性测试如test:community-boundary社区边界校验、test:data-source-identity、test:sql-execution-stream等而 readme.md 的 Checks 一节也建议配合执行yarn run lint yarn run test:i18n # i18n 键完整性校验 yarn run test:result-markdown yarn run test:sql-in-clipboard其中test:i18n与 validate-i18n.cjs 相关用于保证多语言目录src/i18n/下的en-US、es-ES、ja-JP、ko-KR、zh-CN键与占位符严格对齐test:community-boundary则由 verify-community-boundary.cjs 实现确保 Community 构建不含商业版实现路径。这三者与 Linting 一起构成了代码规范 边界纯净 国际化一致的完整质量防线。4. 结合源码约定的补充建议除了 Linting 规则readme.md 的 Source Conventions 还给出两条与本主题直接相关的编码约定建议在过 lint 时一并遵守类型命名TypeScript 接口与类型别名统一以I开头如IDataSource主题变量样式中使用var(--control-item-bg-active)这类来自window._AppThemePack的 CSS 变量而非硬编码颜色值——这保证了后续主题切换浅色/深色/暗色变体时样式仍能正确响应。七、常见问题与排查思路1. 出现 warning 但觉得无害由于--max-warnings0任何 warning 都会让yarn lint非零退出。优先做法是修复根源未使用的变量/导入删除或加_前缀行超长则换行或提取常量。除非运行时或语法契约确实变化否则不要修改规则级别。2. 需要绕过某条规则文档明确禁止通过// eslint-disable或降级规则来骗过CI。若确属特殊情况应先在团队内明确规则调整的必要性再以更新规则而非豁免代码的方式处理并保证全仓重新通过 lint。3. 修改 Iconfont 导出文件不要手工编辑src/assets/fonts/new-chat2db-colourful-iconfont.js与new-chat2db-iconfont.js。需要更新图标时回到阿里 Iconfont 生成器重新导出并整体覆盖这两个文件再执行yarn lint验证。4. 判断自己的改动是否被检查ESLint 覆盖src/**/*.{js,jsx,ts,tsx}含测试文件Stylelint 覆盖src/**/*.{css,less}。除上述两条 Iconfont 精确路径外没有豁免所以新增的任何源码与样式文件都会纳入检查范围。结语Chat2DB Community 前端的 Linting 体系是一个典型的高门槛、零容忍质量模型ESLint 与 Stylelint 双引擎通过yarn lint统一入口配合--max-warnings0把告警提升到与错误同等的失败级别LINTING.md 用四条简明规则约束了零错误零警告、禁止降级规则、_前缀豁免与类名风格.eslintrc.js 与 .stylelintrc.json 则是这些约束的完整落地最后仅有的两个 Iconfont 生成文件豁免体现了生成代码不手工改的工程理性。对任何准备为 Community 前端贡献代码的开发者而言先跑通yarn lint再遵循_前缀与类名规范就能顺畅地融入这套质量体系。【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Chat2DB Community 前端代码规范实战：ESLint 与 Stylelint 的零告警 Linting 体系解析
Chat2DB Community 前端代码规范实战ESLint 与 Stylelint 的零告警 Linting 体系解析【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DBChat2DB Community 前端chat2db-community-client是一套基于 Umi 4、React、TypeScript 与 Ant Design 5 构建的大型数据库客户端界面代码规模庞大且横跨业务、工具与样式等多个层面。为了保证多人在大规模改动下仍能维持可维护的源码质量仓库以 LINTING.md 为基准建立了一套零错误、零警告的双引擎 Linting 体系ESLint 负责 JavaScript/TypeScript 源码Stylelint 负责 CSS/Less 样式。本文将以此文档为核心结合仓库中的 package.json、.eslintrc.js、.stylelintrc.json 等真实配置完整讲解该体系的设计原则、命令用法、关键规则含义与生成的豁免清单帮助你快速理解并合规地在 Chat2DB Community 前端中编写代码。一、Linting 体系总览双引擎与统一入口1. 双引擎分工依据 LINTING.mdCommunity 前端采用两条检查链ESLint检查src下的 JavaScript 与 TypeScript 源码*.js / *.jsx / *.ts / *.tsx负责语法正确性、未使用变量/导入、React 组件书写习惯、TypeScript 类型约束等Stylelint检查 CSS 与 Less 样式文件*.css / *.less负责类名命名、keyframes 命名、媒体查询语法等样式层面的规范。两条检查链并非各自为政而是由yarn lint一键串联执行并且将告警warning视为失败——这与多数项目warning 可容忍的默认做法截然不同是理解本仓库代码规范的第一要义。2. 统一命令入口yarn lint在 package.json 的scripts中可以看到该体系的最小入口lint: yarn lint:eslint yarn lint:style, lint:eslint: eslint \src/**/*.{js,jsx,ts,tsx}\ --max-warnings0, lint:style: stylelint \src/**/*.{css,less}\ --max-warnings0三个脚本各自含义脚本实际执行的命令作用范围关键参数yarn lint依次执行下方两个脚本全部源码与样式保证串行前者失败则中断yarn lint:eslinteslint src/**/*.{js,jsx,ts,tsx} --max-warnings0所有 JS/TS 源码文件--max-warnings0出现任意一条 warning 即非零退出yarn lint:stylestylelint src/**/*.{css,less} --max-warnings0所有 CSS/Less 样式文件同上值得强调的细节是--max-warnings0它把 warning 的容忍阈值设为 0意味着即使 ESLint/Stylelint 只是输出了一条 warning命令也会以失败退出。这与 LINTING.md 中Maintained source must pass with zero errors and zero warnings受维护的源码必须以零错误、零警告通过的硬性要求完全对应。二、源码规则零容忍背后的四条铁律LINTING.md 的 Source Rules 一节给出了四条面向开发者的源码约束逐条拆解如下。规则一零错误、零警告任何受维护的源码即src下被 ESLint/Stylelint 覆盖的文件都必须同时满足零错误与零警告。这意味着提交前必须执行yarn lint或至少yarn lint:eslint yarn lint:styleCI 中对 lint 失败零容忍不允许带 warning 合并即便某个 warning 看起来无害例如多余的 import 或未使用的变量也会被拦截。规则二禁止通过降级规则来通过 CI文档明确规定Do not disable or downgrade rules to make CI pass. Fix the source or update a rule only when the project runtime or syntax contract has changed.即禁止为了通过 CI 而关闭或降级规则。只有当下述两种情况成立时才允许改动规则本身项目运行时行为发生了变化语法契约发生了变化。换句话说正常的业务迭代中遇到 lint 报错首选方案永远是修改源码本身而不是在.eslintrc.js中把对应规则从2error降为1warning或0off更不应该在代码中使用// eslint-disable注释来绕开检查。这条约定保障了规则集合长期稳定也防止了规则被悄悄稀释导致的规范退化。规则三未使用的回调参数必须以下划线开头Intentionally unused callback parameters must start with_.对于故意不使用的回调参数命名必须以_开头。这一约定的根源可以在 .eslintrc.js 中找到项目使用unused-imports插件的no-unused-vars规则并配置了unused-imports/no-unused-vars: [ 2, { args: after-used, argsIgnorePattern: ^_, caughtErrors: all, caughtErrorsIgnorePattern: ^_, destructuredArrayIgnorePattern: ^_, ignoreRestSiblings: true, vars: all, varsIgnorePattern: ^_, }, ],其中的argsIgnorePattern: ^_、caughtErrorsIgnorePattern: ^_、destructuredArrayIgnorePattern: ^_、varsIgnorePattern: ^_四个选项共同实现了以下划线开头的标识符豁免未使用检查的机制。典型场景包括// 正确显式声明本参数有意不使用 arr.forEach((item, _index) { /* 只用 item */ }); // 正确catch 子句故意不使用错误对象 try { /* ... */ } catch (_err) { /* 静默处理 */ }相反如果某个参数未使用但又没有_前缀就会被unused-imports/no-unused-vars严重级别为2即 error拦截。规则四CSS 类名命名允许 camelCase 与 kebab-caseCSS module classes may use camelCase or kebab-case. Global third-party class names may also use PascalCase.CSS Module 的类名允许 camelCase 或 kebab-case全局第三方库的类名还额外允许 PascalCase。这一规则在 .stylelintrc.json 中有对应的正则实现selector-class-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected class selector to use camelCase or kebab-case } ]该正则要求类选择器以字母开头后续只允许字母、数字与连字符从而同时覆盖dataTablecamelCase与data-tablekebab-case两种合法写法并排除掉下划线等其他字符。同文件中的keyframes-name-pattern对动画关键帧命名施加了相同约束keyframes-name-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected keyframe name to use camelCase or kebab-case } ]三、配置文件的真实面貌ESLint 规则拆解.eslintrc.js 是 ESLint 的全部依据。其组成结构如下1. 解析器与插件parser: typescript-eslint/parser, plugins: [typescript-eslint, babel, react-hooks, react, unused-imports],typescript-eslint/parser让 ESLint 能解析 TypeScript 语法react-hooks/reactReact 专属规则unused-imports专门负责未使用导入的清理是本仓库零告警目标的关键插件env声明了browser与es2021两个环境。2. 继承的规则集extends: [ eslint:recommended, plugin:typescript-eslint/recommended, plugin:react/recommended, plugin:react/jsx-runtime, ],注意到仓库有意注释掉了airbnb-base与prettier相关配置注释中说明airbnb-base 已包含 import 插件prettier 相关配置因格式化交给 Prettier 处理而禁用。这说明本仓库选择了规则检查交给 ESLint、格式化交给 Prettier的职责分离方案——.prettierrc 中printWidth: 120、singleQuote: true、trailingComma: all等即为格式化侧的真实约定。3. 值得关注的代表性规则结合 LINTING.md 与源码现状以下规则对日常开发影响最直接规则级别含义unused-imports/no-unused-imports2error未使用的 import 一律报错杜绝顺手留下的 importunused-imports/no-unused-vars2error未使用的变量报错但^_前缀可豁免max-len1warning单行超过 120 字符发出警告ignoreStrings、ignoreUrls、ignoreRegExpLiterals为 true字符串、URL、正则字面量不计入typescript-eslint/no-var-requires2禁止require()式导入统一使用 ESM 语法new-cap2构造函数名必须以大写字母开头default-case2switch语句必须包含default分支prefer-arrow-callback2尽量使用箭头函数回调no-param-reassign2props: false禁止对函数参数重新赋值max-classes-per-file2单文件最多允许 10 个类react/self-closing-comp2无子节点的组件必须使用自闭合语法react/jsx-indent-props2JSX 属性缩进为两个空格react/jsx-tag-spacing2规范 JSX 标签定界符周围的空格typescript-eslint/no-shadow1warning禁止遮蔽外部作用域变量注释标注 TODO考虑提升为 2与此同时不少在旧项目中常见、但在强类型 高版本工具链下冗余的规则被显式关闭例如no-undef交给 TypeScript 检查、no-unused-vars与typescript-eslint/no-unused-vars交给unused-imports插件统一处理、react/prop-types类型由 TypeScript 提供、typescript-eslint/explicit-function-return-type不强制显式返回类型、typescript-eslint/no-explicit-any允许显式 any等。这些关闭同样是经过权衡的工程决策与不随意降级规则的约定并不矛盾——它们是既定基线的一部分。4. 未使用变量豁免与_前缀的完整语义前面提到的四个*IgnorePattern: ^_选项合在一起保证了文档中未使用回调参数以_开头的约定在args、caughtErrors、destructuredArray、vars四种场景下均生效。同时ignoreRestSiblings: true意味着const { a, ...rest } obj中未被使用的a不会报错——这是对象解构时常用的安全模式。四、Stylelint 配置解读样式层的命名与语法约束.stylelintrc.json 结构非常精简{ extends: [stylelint-config-standard-less], rules: { media-feature-range-notation: prefix, keyframes-name-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected keyframe name to use camelCase or kebab-case } ], selector-class-pattern: [ ^[A-Za-z][A-Za-z0-9-]*$, { message: Expected class selector to use camelCase or kebab-case } ] } }三个要点基线stylelint-config-standard-less同时提供了 Stylelint 标准规则与 Less 语法支持因此无需在项目中单独引入 Less 解析器配置media-feature-range-notation: prefix媒体查询的范围写法要求使用前缀记法如(min-width: 768px)而非现代(width 768px)记法以兼顾更广的兼容面两条命名规则类选择器与 keyframes 名称都必须匹配^[A-Za-z][A-Za-z0-9-]*$与 LINTING.md 中camelCase 或 kebab-case 皆可的表述一一对应并允许第三方全局类使用 PascalCase该正则天然允许大写字母开头。五、生成的豁免文件为什么只有这两个例外LINTING.md 明确指出整个src下只有两个文件被豁免检查且仅限精确路径匹配src/assets/fonts/new-chat2db-colourful-iconfont.jssrc/assets/fonts/new-chat2db-iconfont.js这两个文件是阿里 Iconfont 字体图标的导出产物包含压缩过的生成式运行时代码。它们的豁免理由非常实际既然代码由图标平台生成器产出人工编辑不仅无意义还可能破坏字体图标映射。正确维护方式是回到生成器重新导出并覆盖文件而不是手改。这一豁免在 .eslintrc.js 的ignorePatterns中有完全一致的落地ignorePatterns: [ // Alibaba Iconfont exports. Regenerate these files instead of editing the minified vendor runtime. src/assets/fonts/new-chat2db-colourful-iconfont.js, src/assets/fonts/new-chat2db-iconfont.js, ],同时文档强调 No other source path is exempt from ESLint or Stylelint——除这两条精确路径外任何其他源码路径都不存在豁免包括构建产物目录、mock 数据乃至测试文件如src/**/*.test.ts也在lint:eslint的src/**/*.{js,jsx,ts,tsx}覆盖范围内。六、本地执行与工程实践1. 前置条件依据 readme.md在chat2db-community-client目录下运行 Linting 前需要Node.js18.17.0 或更高版本见 package.json 的engines字段使用 Yarn 且锁定仓库自带的 yarn.lock安装命令为yarn install --frozen-lockfile不要生成 npm/pnpm 锁文件。2. 标准执行流程# 进入前端目录 cd chat2db-community-client # 一键执行全部 lintESLint Stylelintwarning 即失败 yarn lint # 也可以单独执行某一条链 yarn lint:eslint # 仅检查 JS/TS 源码 yarn lint:style # 仅检查 CSS/Less 样式3. 与其他质量门禁的配合Linting 只是 Community 前端质量门禁的一环。在 package.json 的prebuild:web:community中可以看到正式构建前还会串行运行数十项针对性测试如test:community-boundary社区边界校验、test:data-source-identity、test:sql-execution-stream等而 readme.md 的 Checks 一节也建议配合执行yarn run lint yarn run test:i18n # i18n 键完整性校验 yarn run test:result-markdown yarn run test:sql-in-clipboard其中test:i18n与 validate-i18n.cjs 相关用于保证多语言目录src/i18n/下的en-US、es-ES、ja-JP、ko-KR、zh-CN键与占位符严格对齐test:community-boundary则由 verify-community-boundary.cjs 实现确保 Community 构建不含商业版实现路径。这三者与 Linting 一起构成了代码规范 边界纯净 国际化一致的完整质量防线。4. 结合源码约定的补充建议除了 Linting 规则readme.md 的 Source Conventions 还给出两条与本主题直接相关的编码约定建议在过 lint 时一并遵守类型命名TypeScript 接口与类型别名统一以I开头如IDataSource主题变量样式中使用var(--control-item-bg-active)这类来自window._AppThemePack的 CSS 变量而非硬编码颜色值——这保证了后续主题切换浅色/深色/暗色变体时样式仍能正确响应。七、常见问题与排查思路1. 出现 warning 但觉得无害由于--max-warnings0任何 warning 都会让yarn lint非零退出。优先做法是修复根源未使用的变量/导入删除或加_前缀行超长则换行或提取常量。除非运行时或语法契约确实变化否则不要修改规则级别。2. 需要绕过某条规则文档明确禁止通过// eslint-disable或降级规则来骗过CI。若确属特殊情况应先在团队内明确规则调整的必要性再以更新规则而非豁免代码的方式处理并保证全仓重新通过 lint。3. 修改 Iconfont 导出文件不要手工编辑src/assets/fonts/new-chat2db-colourful-iconfont.js与new-chat2db-iconfont.js。需要更新图标时回到阿里 Iconfont 生成器重新导出并整体覆盖这两个文件再执行yarn lint验证。4. 判断自己的改动是否被检查ESLint 覆盖src/**/*.{js,jsx,ts,tsx}含测试文件Stylelint 覆盖src/**/*.{css,less}。除上述两条 Iconfont 精确路径外没有豁免所以新增的任何源码与样式文件都会纳入检查范围。结语Chat2DB Community 前端的 Linting 体系是一个典型的高门槛、零容忍质量模型ESLint 与 Stylelint 双引擎通过yarn lint统一入口配合--max-warnings0把告警提升到与错误同等的失败级别LINTING.md 用四条简明规则约束了零错误零警告、禁止降级规则、_前缀豁免与类名风格.eslintrc.js 与 .stylelintrc.json 则是这些约束的完整落地最后仅有的两个 Iconfont 生成文件豁免体现了生成代码不手工改的工程理性。对任何准备为 Community 前端贡献代码的开发者而言先跑通yarn lint再遵循_前缀与类名规范就能顺畅地融入这套质量体系。【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考