从需求到可用：零依赖单页开发者工具箱的设计与实现

在日常开发中，我们经常要处理一些“小而高频”的任务：格式化 JSON、转换时间戳、编解码 Base64、测试正则表达式、生成 UUID 或随机密码。每个功能都不复杂，但频繁切换网站或安装工具会打断思路。

因此，我做了一个面向开发者与编程学习者的单页工具箱。它采用原生 HTML、CSS 和 JavaScript 实现，无需构建工具或后端服务，打开页面即可使用。本文记录这个项目从需求拆解到边界处理的完整思路，也总结几个容易被忽略的实现细节。

一、先把需求变成可验收的功能

“做一个开发者工具箱”还不够具体。为了避免做完后只能看、不能用，我将需求拆成六组可直接验证的能力：

1. JSON 格式化与校验：支持格式化、压缩和语法错误提示；错误输入不能导致页面白屏。
2. Unix 时间戳转换：支持时间戳与日期时间双向转换，并明确显示时区。
3. Base64 编解码：正确处理中文、特殊字符和空输入。
4. URL 编解码：基于 URI 组件进行转换，避免破坏查询参数中的特殊字符。
5. 正则表达式测试：实时展示匹配结果、捕获组和语法错误。
6. UUID 与密码生成：提供刷新、复制、长度设置和字符类型选择。

界面采用深色开发者风格，通过标签页切换不同工具。所有工具都在同一页面中，切换标签时不刷新页面，也不清空已经输入的内容。

二、为什么选择“单页、零依赖”

这个项目的核心目标不是展示复杂技术栈，而是降低使用成本。原生前端方案有几个明显优势：

• 启动简单：静态服务器即可运行，也可以直接部署到对象存储或静态站点托管服务。
• 数据不出浏览器：文本转换在本地完成，适合处理不方便上传到第三方服务的内容。
• 维护成本低：没有依赖升级、打包失败或框架版本冲突。
• 迁移方便：项目只有页面、样式和脚本文件，任何常见 Web 环境都能承载。

当然，零依赖不等于把所有代码堆进一个函数。我的做法是按功能划分事件绑定、输入校验、核心算法和结果渲染，让每个工具保持独立。

整体数据流可以概括为：

用户输入
   ↓
输入校验
   ↓
核心转换逻辑
   ↓
结果渲染或错误提示
   ↓
复制 / 清空 / 再次转换

三、JSON 工具：错误提示比格式化更重要

格式化 JSON 的核心代码很短：

function formatJson(source) {
  const value = JSON.parse(source);
  return JSON.stringify(value, null, 2);
}

真正影响体验的是异常处理。JSON.parse() 遇到非法输入会抛出异常，因此必须在界面层捕获错误，并把错误展示在固定区域，而不是让异常中断后续脚本。

function safeFormat(source) {
  if (!source.trim()) {
    return { ok: false, message: "请输入 JSON 内容" };
  }

  try {
    return { ok: true, value: formatJson(source) };
  } catch (error) {
    return { ok: false, message: `JSON 解析失败：${error.message}` };
  }
}

对于较大的 JSON，除了关注解析速度，还要关注结果写入文本框时的渲染开销。可采用延迟执行或分片更新，让浏览器先完成一次界面刷新，再开始处理：

status.textContent = "正在处理…";

requestAnimationFrame(() => {
  const result = safeFormat(input.value);
  renderResult(result);
});

这不是万能的性能方案，但能避免点击按钮后界面完全没有反馈。若要处理更大数据，可进一步使用 Web Worker，把解析工作移出主线程。

四、时间戳转换：秒、毫秒和时区要说清楚

时间戳工具最常见的问题不是“算错”，而是单位和时区不明确。Unix 时间戳可能以秒表示，也可能以毫秒表示。可以根据位数或数值范围进行识别：

function normalizeTimestamp(value) {
  const number = Number(value);
  if (!Number.isFinite(number)) throw new Error("时间戳必须是数字");
  return Math.abs(number) < 1e12 ? number * 1000 : number;
}

转换结果建议同时给出：

• ISO 8601 时间，例如 2026-09-26T08:00:00.000Z；
• 浏览器本地时间；
• 当前时区标识或 UTC 偏移；
• 识别出的输入单位（秒或毫秒）。

日期时间转时间戳时，也要提醒用户：不带时区的日期字符串通常会按浏览器本地时区解析。为了让结果可复核，界面上应保留原始输入和转换后的秒、毫秒两种结果。

五、Base64：中文乱码的根源是字符编码

浏览器的 btoa() 和 atob() 主要面向字节字符串，直接传入中文通常会报错或乱码。正确思路是先使用 UTF-8 在“字符串”和“字节数组”之间转换。

function encodeBase64(text) {
  const bytes = new TextEncoder().encode(text);
  let binary = "";
  bytes.forEach(byte => binary += String.fromCharCode(byte));
  return btoa(binary);
}

function decodeBase64(base64) {
  const binary = atob(base64);
  const bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

解码时同样需要捕获异常，因为用户可能输入了非法 Base64 文本。空输入也应该单独判断，给出明确提示，而不是显示难以理解的底层错误。

URL 编解码则适合使用 encodeURIComponent() 和 decodeURIComponent()。这里要区分完整 URL 与 URL 组件：如果输入的是查询参数值，应编码组件；如果把完整地址整体编码，斜杠、冒号等也会被转换，结果往往不是用户想要的。

六、正则测试：防止零宽匹配造成死循环

正则工具除了显示“是否匹配”，还应该展示：

• 每个匹配项的内容和位置；
• 完整匹配与捕获组；
• 当前 flags，如 g、i、m；
• 正则语法错误。

实时高亮时需要特别留意零宽匹配。例如 /^/gm 可以匹配空字符串。如果循环中每次都调用 exec()，却没有手动推进索引，就可能无限循环。

const regex = new RegExp(pattern, flags.includes("g") ? flags : flags + "g");
let match;

while ((match = regex.exec(text)) !== null) {
  collectMatch(match);
  if (match[0] === "") regex.lastIndex += 1;
}

高亮输出不要直接拼接未经处理的原文到 innerHTML，否则用户输入的 <script>、<img> 等内容可能被浏览器解释为标签。更安全的方式是创建文本节点，或者先对 &、<、>、引号等字符进行 HTML 转义。

七、密码生成：随机性和可用性要同时考虑

密码生成不能依赖 Math.random()，因为它不适合安全用途。浏览器提供的 crypto.getRandomValues() 更合适：

function randomIndex(max) {
  const array = new Uint32Array(1);
  crypto.getRandomValues(array);
  return array[0] % max;
}

如果用户选择了大写、小写、数字和符号四类字符，只从合并后的字符池随机抽取，理论上仍可能漏掉某一类。更稳妥的实现是：先从每个已选字符集至少取一个字符，再补足剩余长度，最后用安全随机数打乱顺序。

还需要处理两个边界：

1. 未选择任何字符类型时，阻止生成并提示用户；
2. 密码长度小于已选字符类型数量时，提高最小长度或要求用户调整设置。

UUID v4 可以优先调用 crypto.randomUUID()。对于不支持该接口的环境，再使用 crypto.getRandomValues() 实现兼容方案。

八、标签页设计：切换不丢状态

标签切换只负责改变可见性，不应该重新创建整个工具面板。每个面板保留在 DOM 中，通过类名控制显示与隐藏：

tabs.forEach(tab => {
  tab.addEventListener("click", () => {
    tabs.forEach(item => item.classList.remove("active"));
    panels.forEach(panel => panel.hidden = true);

    tab.classList.add("active");
    document.querySelector(tab.dataset.target).hidden = false;
  });
});

这样用户从 JSON 切换到正则工具，再切回来时，原输入仍然存在。为了提升键盘和读屏体验，还可以加入 role="tab"、aria-selected、方向键切换及清晰的焦点样式。

九、验收清单

功能完成后，我没有只看“页面能打开”，而是按真实使用场景检查：

• JSON：正常对象、非法 JSON、空输入、较大数据；
• 时间戳：秒、毫秒、负数、非法字符、时区展示；
• Base64：中文、表情、特殊字符、空输入、非法编码；
• URL：中文参数、空格、&、=、#；
• 正则：捕获组、忽略大小写、多行、零宽匹配、非法表达式；
• 生成器：复制、刷新、长度边界、字符类型组合；
• 交互：标签切换不刷新、不丢状态，错误提示后仍可继续操作。

我还会把浏览器控制台错误作为验收项。页面看似正常但控制台持续报错，通常意味着某个边界条件没有真正处理好。

十、总结

这个工具箱的代码并不复杂，但它体现了一个重要原则：工具是否好用，取决于异常输入、编码、时区、性能反馈和交互连续性，而不仅仅是“主流程能运行”。

从开发实践看，先写可验证的功能清单，再逐项处理边界，比一开始追求复杂框架更有效。后续还可以加入哈希计算、颜色转换、JWT 解析、文本差异比较等功能；如果工具数量继续增长，则可以把各模块拆分为独立脚本，并使用 Web Worker 承担大文本处理。

一个真正实用的开发者工具，不需要炫技，但必须在用户粘贴错误内容、中文内容或大段数据时，依然给出稳定、明确、可恢复的反馈。