代码规范与静态检查

规范的意义不是统一审美，而是把「这类争论」一次性解决掉，让代码评审聚焦逻辑而不是分号。

一、规范分层：哪些该管，哪些别管

一条实用原则：能用工具自动修的，绝不写进评审意见。评审意见里出现「这里多了一个空格」，说明工具链没配好。

二、Node / TypeScript 项目的推荐工具链

// package.json（片段）
{
  "scripts": {
    "lint": "eslint . --max-warnings=0",
    "format": "prettier --write .",
    "typecheck": "tsc --noEmit"
  },
  "lint-staged": {
    "*.{ts,tsx,vue,js}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

// .eslintrc.cjs 关键规则思路（示意）
module.exports = {
  rules: {
    'no-console': ['warn', { allow: ['warn', 'error'] }],
    'eqeqeq': ['error', 'always', { null: 'ignore' }],
    '@typescript-eslint/no-floating-promises': 'error',
    '@typescript-eslint/no-explicit-any': 'warn'
  }
};

@typescript-eslint/no-floating-promises 这类规则的价值远高于「缩进 2 还是 4」：它能直接拦住未 await 的异步调用这类真实线上故障源。

三、四道门禁

提交前钩子用 husky + lint-staged 即可，只检查暂存文件，否则大仓库里每次提交格式化全项目会让人抓狂。

四、命名与组织的实用约定

• 布尔值用 is / has / should 开头：isExpired、hasPermission。
• 函数名体现动作与对象：fetchUserOrders 而非 getData。
• 常量替代魔法值：ORDER_EXPIRE_MINUTES = 30，别在代码里散落 30。
• 一个文件一个主要职责；工具函数放 utils/，且不要造万能 common.ts 垃圾抽屉。
• 目录按业务域划分优先于按技术类型划分：orders/ 下放自己的 service、dto、test，胜过全局 services/ 堆 200 个文件。
• 注释写「为什么」，不写「是什么」：// 兼容旧客户端未传时区，默认按 UTC+8 处理 有价值，// 循环订单 没有。

五、错误处理里最该被 lint 拦住的写法

// ❌ 吞掉异常，线上出问题时毫无痕迹
try { await save(order); } catch (e) {}

// ❌ 空 catch + 只有 console.log，日志进不了采集系统
catch (e) { console.log(e); }

// ✅ 保留上下文、交给统一错误处理
catch (e) {
  logger.error('order.save_failed', { orderId: order.id, err: e });
  throw new BizError('ORDER_SAVE_FAILED', { cause: e });
}

建议把「空 catch 块」「Promise 未处理拒绝」「直接对 any 取属性」列为 error 级规则。

六、常见坑与对策

七、落地检查清单

• [ ] 保存即格式化，提交即 lint，CI 即全量检查
• [ ] 格式类规则与逻辑类规则分开，不互相覆盖
• [ ] 开启类型检查（tsc --noEmit）并纳入 CI
• [ ] 有密钥 / 敏感信息提交扫描
• [ ] 规范文档只有一页，且链接到可执行的配置文件

八、小结

好的规范让人几乎感觉不到它的存在：写完代码保存，格式自动好了；提交时两条真正危险的规则拦住了隐患；评审会上大家只在讨论「这个抽象合不合理」。反过来，如果团队每周都在争论引号，那不是人的问题，是工具链缺位。