用途
本技能面向使用 TypeScript 构建生产级应用的工程实践,围绕类型安全、测试方法论与构建工具链展开,适合前端或全栈 TypeScript 项目在编码规范、质量保障与性能优化上统一标准。
主要能力
1. TypeScript 严格性
- 在 tsconfig.json 中开启最大严格度,示例配置包含:strict、noUncheckedIndexedAccess、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature、noFallthroughCasesInSwitch、verbatimModuleSyntax。
- noUncheckedIndexedAccess 会为数组/对象索引访问加上 | undefined,迫使对 arr[0] 与 Record 查找做收窄。
- exactOptionalPropertyTypes 区分“属性缺失”与“属性为 undefined”。
- noPropertyAccessFromIndexSignature 强制索引签名使用方括号访问。
- verbatimModuleSyntax 保留 ES 模块语法,对 Vite/Rollup 摇树优化很关键。
- 使用 satisfies 在验证类型的同时保留字面量推断。
- 使用品牌类型(branded types)防止共享同一原始类型的语义不同值混用,示例以 UserId、OrderId 说明。
- 使用可辨识联合(discriminated unions)表达状态机,消除不可能状态,如 FetchState<T> 的 idle/loading/success/error 分支。
- 反模式:不用 any(改用 unknown 并收窄或泛型)、不滥用 as、不用 // @ts-ignore(必要时用 // @ts-expect-error 并附说明)、不用 enum(改用 as const 对象或字符串字面量联合)。
2. 测试
- 分层策略:单元测试(Vitest,纯函数、hooks、校验 schema)、组件测试(Vitest + Testing Library,配合 userEvent)、集成测试(Vitest + MSW,模拟 API 响应)、E2E(Playwright,关键用户旅程,每个 spec 聚焦一条旅程)。
- 选层原则:把测试尽量下压到能提供信心的最低层;不在多层重复证明同一行为;静态分析是基础;E2E 测旅程而非功能;集成测试投资回报最高。
- 测用户行为而非实现细节,示例给出点击“open menu”按钮并断言菜单可见。
- 优先 userEvent 而非 fireEvent。
- 用 MSW 在网络层而非模块层模拟,handler 可在 Vitest 与 Playwright 间复用,示例给出 http.get("/api/resources")。
- 停止使用快照测试,改用显式断言。
- Playwright 最佳实践:使用 locator(如 page.getByRole)、启用重试、用 page.waitForResponse 处理依赖 API 的断言、只测关键流程。
3. 性能
- React Compiler(React 19 中稳定)在构建时自动记忆化:新代码可移除 useMemo、useCallback、React.memo;仅对身份敏感路径保留手动记忆化。示例给出通过 babel-plugin-react-compiler 启用。
- 按路由代码分割,示例用 React.lazy 引入路由组件,可显著减少初始包体积。
- 打包分析:使用 rollup-plugin-visualizer;在 CI 中设置体积预算(示例 build.chunkSizeWarningLimit 为 250 KB)。
- 图片优化:对首屏外图片使用 loading="lazy",提供 WebP/AVIF,设置显式宽高避免 CLS。
- 避免不必要重渲染:状态管理使用选择器(如 useStore((s) => s.theme)),状态尽量靠近使用处,拆分大 Context。
4. 安全
- XSS 防护:React 默认转义 JSX 花括号中的值;风险点为 dangerouslySetInnerHTML(必须用 DOMPurify 清洗并封装为 SafeHTML 组件)、href 属性(校验以 https:// 或 / 开头,防止 javascript: URL)、服务端渲染 HTML(应用 CSP)。
- CSP:为所有响应设置 Content-Security-Policy;脚本避免 'unsafe-inline',改用 nonce 或 hash。
- 依赖扫描:CI 中每个 PR 运行 npm audit/yarn audit,使用 Dependabot 或 Renovate 自动更新,审查传递依赖。
- CSRF 防护:对 cookie 认证的状态变更请求,要求与用户/会话绑定的不可猜测 anti-CSRF token 并在每个非幂等请求校验;SameSite=Lax 作为默认,SameSite 只是加固层,仍需 token。
5. 代码检查与格式化
- 迁移到 ESLint 扁平配置 eslint.config.js;示例使用 typescript-eslint 的 strictTypeChecked、stylisticTypeChecked 与 projectService,类型感知规则可捕获浮动 Promise、不安全 any、错误类型断言。
- ESLint 不是格式化器,使用 Prettier 配合 eslint-config-prettier,或使用 Biome(更快、单二进制)。
- CI 中以 --check 运行,自动修复留给本地与 pre-commit。
6. 模块模式
- 应用代码避免 barrel 导出(index.ts 重导出全部),会破坏摇树、隐藏循环依赖、拖慢编译器;仅公共库 API 可接受。
- 使用 ~ 或 @ 路径别名替代脆弱的相对路径。
- 用 madge 或 eslint-plugin-import 的 no-cycle 检测循环依赖。
- 启用 verbatimModuleSyntax,类型导入用 import type。
7. 构建工具
- Vite 配置示例包含 chunkSizeWarningLimit(体积预算)、sourcemap: true、target: es2022。
- 使用 rollup-plugin-visualizer 定位大依赖,在 CI 中设置体积阈值。
- 依赖管理:用 npm ls <package> 检查重复依赖,优先支持摇树的 ESM 包,定期审查 node_modules 体积。
- Lightning CSS 可作为 Vite 中替代 CSS 压缩器,比 esbuild CSS 压缩更快。
8. 提交前检查清单
- 运行 tsc --noEmit、eslint --max-warnings 0 .、prettier --check .、vitest run。
- 阻断问题:TypeScript 错误或无理由的 any、ESLint 警告(零警告策略)、测试失败、无说明的 // @ts-ignore、未用 DOMPurify 的 dangerouslySetInnerHTML、快照测试、应用代码中的 barrel 导出、遗留 console.log、事件处理器中未处理的 Promise 拒绝。
9. 快速参考
- 类型检查:tsc --noEmit,每次提交前。
- Lint:eslint .,每次提交前。
- 格式检查:prettier --check .,每次提交前。
- 运行单元测试:vitest run,每次改动后。
- 运行 E2E:playwright test,PR 前。
- 打包分析:npx vite-bundle-visualizer,新增依赖时。
- 依赖审计:npm audit / yarn audit,CI 每个 PR。
- 更新依赖:npx npm-check-updates,每月。
- 循环依赖检查:npx madge --circular src/,周期性。
适用场景
适用于采用 TypeScript 的 Web 应用(尤其是 React 生态)的日常开发、代码评审、CI 质量门禁与性能优化,也适合作为团队编码规范与工具链配置的参考。
限制
本技能主要围绕 TypeScript 及 React/Vite 相关工具链,React 特定模式、React Router、UX 设计、CSS 响应式、Web 安全、领域设计、API 设计等由其他技能覆盖(文档中通过 /react、/react-router、/ux-design、/css-responsive、/web-security、/domain-design、API Design 等交叉引用指向)。其他语言、框架或平台的具体用法暂未提供。