Hex 编码/解码插件

这是一个 Yaak 插件，提供了 hex.encode 和 hex.decode 两个模板函数，用于在 Yaak 中进行 16 进制编码和解码操作。

功能特性

• hex.encode: 将字符串编码为 16 进制格式
• hex.decode: 将 16 进制字符串解码为原始字符串
• UTF-8 支持: 完全支持 UTF-8 编码，可正确处理中文等多语言字符
• 智能输入处理: 自动处理空格和 0x 前缀
• 错误处理: 提供友好的错误提示信息
• 别名支持: 提供 hexEncode 和 hexDecode 别名

安装

方法一：从源码构建

1. 克隆仓库或下载源码
2. 安装依赖：

   npm install
   

3. 构建插件：

   npm run build
   

4. 将构建后的插件目录添加到 Yaak 的插件目录中

方法二：直接使用

如果你已经获得了构建好的插件文件，直接将其放入 Yaak 的插件目录即可。

使用方法

基本语法

在 Yaak 的模板中使用以下语法：

// 编码
${[ hex.encode("要编码的字符串") ]}

// 解码
${[ hex.decode("要解码的16进制字符串") ]}

// 使用别名
${[ hexEncode("字符串") ]}
${[ hexDecode("16进制字符串") ]}

参数说明

hex.encode 函数

• 参数: 一个字符串参数
• 返回值: 16 进制编码的字符串（小写，无分隔符）
• 示例: ${[ hex.encode("hello") ]} → "68656c6c6f"

hex.decode 函数

• 参数: 一个 16 进制字符串（支持带空格和 0x 前缀）
• 返回值: 解码后的原始字符串
• 示例: ${[ hex.decode("68656c6c6f") ]} → "hello"

详细示例

示例 1：基本编码解码

// 编码英文
${[ hex.encode("hello world") ]}
// 输出: 68656c6c6f20776f726c64

// 解码英文
${[ hex.decode("68656c6c6f20776f726c64") ]}
// 输出: hello world

示例 2：中文处理

// 编码中文
${[ hex.encode("你好，世界！") ]}
// 输出: e4bda0e5a5bd239e4b896e7958c21

// 解码中文
${[ hex.decode("e4bda0e5a5bd239e4b896e7958c21") ]}
// 输出: 你好，世界！

示例 3：处理带格式的 16 进制

// 带空格的 16 进制
${[ hex.decode("68 65 6c 6c 6f") ]}
// 输出: hello

// 带 0x 前缀的 16 进制
${[ hex.decode("0x68656c6c6f") ]}
// 输出: hello

// 混合格式
${[ hex.decode("0x68 65 6c 6c 6f") ]}
// 输出: hello

示例 4：在 HTTP 请求中使用

# 在 Authorization 头中使用
GET /api/data HTTP/1.1
Host: example.com
Authorization: Basic ${[ hex.encode("admin:password123") ]}
Content-Type: application/json

# 在请求体中使用
POST /api/encode HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "data": "${[ hex.encode("敏感信息") ]}",
  "timestamp": "${[ $timestamp ]}"
}

示例 5：处理 API 响应

// 假设响应体是 16 进制编码的数据
const hexData = "${[ response.body ]}";
const decodedData = "${[ hex.decode(hexData) ]}";

// 或者直接解码
const data = "${[ hex.decode(response.body) ]}";

错误处理

插件提供了完善的错误处理机制：

常见错误场景

1. 无效的 16 进制字符串

   ${[ hex.decode("xyz123") ]}
   // 错误: 无效的16进制字符串
   

2. 奇数长度的 16 进制字符串

   ${[ hex.decode("68656c6c6") ]}
   // 错误: 16进制字符串长度必须为偶数
   

3. 空输入

   ${[ hex.encode("") ]}
   // 输出: "" (空字符串)
   
   ${[ hex.decode("") ]}
   // 输出: "" (空字符串)
   

所有错误都会通过 Yaak 的 toast 通知显示，不会中断模板的渲染流程。

技术细节

编码实现

• 使用 TextEncoder 将字符串转换为 UTF-8 字节数组
• 将每个字节转换为两位 16 进制表示（小写）
• 自动补零确保每字节都是两位表示

解码实现

1. 清理输入：
   • 移除所有空白字符
   • 移除 0x 前缀
2. 验证：
   • 检查是否为有效的 16 进制字符（0-9, a-f, A-F）
   • 检查长度是否为偶数
3. 解码：
   • 每两个字符解析为一个字节
   • 使用 TextDecoder 将字节数组解码为 UTF-8 字符串

开发指南

项目结构

hex/
├── src/
│   ├── index.ts          # 插件主文件
│   └── index.test.ts     # 单元测试
├── build/               # 构建输出目录
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript 配置
└── examples.md          # 使用示例文档

运行测试

# 运行所有测试
npm test

# 以监听模式运行测试
npx vitest

构建插件

npm run build

构建后的文件将输出到 build/ 目录。

添加新功能

要添加新的模板函数，请参考现有实现：

1. 在 src/index.ts 中添加新的 TemplateFunctionPlugin 对象
2. 实现 onRender 方法
3. 将函数添加到 plugin.templateFunctions 数组中
4. 添加相应的单元测试

常见问题

Q: 插件支持哪些字符编码？

A: 插件完全支持 UTF-8 编码，可以正确处理 ASCII、中文、日文、韩文等所有 Unicode 字符。

Q: 编码输出是大写还是小写？

A: 输出为小写 16 进制字符串，这是大多数系统的标准做法。

Q: 可以处理二进制数据吗？

A: 可以。插件可以将任意字节数据编码为 16 进制，也可以将 16 进制解码回原始数据。

Q: 性能如何？

A: 对于常规使用场景性能足够。如果需要处理大量数据（超过 1MB），建议在外部处理。

Q: 如何报告问题或请求功能？

A: 请通过项目的 Issue 页面提交问题或功能请求。

版本历史

v0.0.1 (当前版本)

• 初始版本发布
• 实现 hex.encode 和 hex.decode 函数
• 完整的 UTF-8 支持
• 完善的错误处理
• 单元测试覆盖

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件。

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

支持

如果你在使用过程中遇到任何问题，或者有改进建议，请通过以下方式联系：

• 提交 Issue
• 查看 examples.md 获取更多使用示例

---

感谢使用 Hex 编码/解码插件！希望这个插件能让你的 Yaak 使用体验更加愉快。