javascript-pro

JavaScript Pro

适用场景

• 构建原生 JavaScript 应用
• 实现 async/await 模式并处理 Promise
• 使用现代模块系统（ESM/CJS）
• 优化浏览器性能和内存使用
• 开发 Node.js 后端服务
• 实现 Web Workers、Service Workers 或浏览器 API

核心工作流

1. 分析需求 — 检查 package.json、模块系统、Node 版本和浏览器目标；确认 .js/.mjs/.cjs 约定
2. 设计架构 — 规划模块、异步流程和错误处理策略
3. 实现 — 使用恰当的模式和优化方法编写 ES2023+ 代码
4. 验证 — 运行 linter（eslint --fix）；如果 linter 未通过，修复所有报告的问题并重新运行，然后再继续。使用 DevTools 或 --inspect 检查内存泄漏，并验证打包体积；如果发现泄漏，先解决再继续
5. 测试 — 使用 Jest 编写全面的测试，达到 85% 以上的覆盖率；如果覆盖率不足，补充缺失用例并重新运行。确认没有未处理的 Promise 拒绝

参考指南

根据上下文加载详细指南：

主题	参考资料	加载时机
现代语法	references/modern-syntax.md	ES2023+ 特性、可选链、私有字段
异步模式	references/async-patterns.md	Promise、async/await、错误处理、事件循环
模块	references/modules.md	ESM 与 CJS、动态导入、package.json exports
浏览器 API	references/browser-apis.md	Fetch、Web Workers、Storage、IntersectionObserver
Node 基础	references/node-essentials.md	fs/promises、流、EventEmitter、工作线程

约束

必须做到

• 仅使用 ES2023+ 特性
• 使用 X | null 或 X | undefined 模式
• 使用可选链（?.）和空值合并（??）
• 所有异步操作都使用 async/await
• 新项目使用 ESM（import/export）
• 使用 try/catch 实现适当的错误处理
• 为复杂函数添加 JSDoc 注释
• 遵循函数式编程原则

禁止事项

• 使用 var（始终使用 const 或 let）
• 使用基于回调的模式（优先使用 Promise）
• 在同一模块中混用 CommonJS 和 ESM
• 忽视内存泄漏或性能问题
• 在异步函数中跳过错误处理
• 在 Node.js 中使用同步 I/O
• 修改函数参数
• 在浏览器中创建阻塞操作

关键模式示例

Async/Await 错误处理

// ✅ Correct — always handle async errors explicitly
async function fetchUser(id) {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (err) {
    console.error("fetchUser failed:", err);
    return null;
  }
}

// ❌ Incorrect — unhandled rejection, no null guard
async function fetchUser(id) {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

可选链与空值合并

// ✅ Correct
const city = user?.address?.city ?? "Unknown";

// ❌ Incorrect — throws if address is undefined
const city = user.address.city || "Unknown";

ESM 模块结构

// ✅ Correct — named exports, no default-only exports for libraries
// utils/math.mjs
export const add = (a, b) => a + b;
export const multiply = (a, b) => a * b;

// consumer.mjs
import { add } from "./utils/math.mjs";

// ❌ Incorrect — mixing require() with ESM
const { add } = require("./utils/math.mjs");

避免使用 var / 优先使用 const

// ✅ Correct
const MAX_RETRIES = 3;
let attempts = 0;

// ❌ Incorrect
var MAX_RETRIES = 3;
var attempts = 0;

输出模板

实现 JavaScript 功能时，请提供：

1. 导出清晰的模块文件
2. 覆盖全面的测试文件
3. 面向公共 API 的 JSDoc 文档
4. 对所用模式的简要说明

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问

文档