如何快速为 filetype4cj 添加自定义文件类型：addType 与 addMatcher 完整实战教程

如何快速为 filetype4cj 添加自定义文件类型addType 与 addMatcher 完整实战教程【免费下载链接】filetype4cj通过检查魔数签名推断文件和 MIME 类型项目地址: https://gitcode.com/Cangjie-SIG/filetype4cj 项目简介30 秒了解 filetype4cjfiletype4cj是一个通过检查魔数签名Magic Number来推断文件类型和MIME 类型的轻量级仓颉Cangjie工具库。它无需依赖外部组件只需读取文件头的前 262 字节就能快速识别出 jpg、mp4、zip 等常见文件。但内置类型终归有限——当你的业务需要识别一个私有格式的.cjbin文件时该怎么办答案就是本教程的主角用addType注册新类型再用addMatcher挂载识别规则两步搞定自定义文件类型扩展。 先懂原理类型与匹配器是如何协作的在动手之前花一分钟理解 filetype4cj 的内部结构能帮你少走弯路。从项目依赖结构图可以看出整个识别链路分为三层模块职责关键文件types 包类型注册表管理扩展名与 MIME 的映射type.cj、types.cjmatchers 包各文件类别的魔数匹配规则matchers.cj、font.cjmatch / filetype对外暴露的匹配与注册入口match.cj、filetype.cj工作机制一句话概括addType把「扩展名 MIME」登记进类型注册表addMatcher把「字节校验函数」绑定到这个类型上。之后每次调用doMatch(buf)时引擎会遍历匹配器列表谁先命中就返回谁见 doMatch 实现。 实战第一步用 addType 注册新文件类型addType的签名非常简单——传入扩展名和MIME 类型即可得到一个Type对象public func addType(ext: String, mime: String): Type它内部会调用 newType 创建类型并立即写入全局注册表 types.cj所以调用后这个扩展名立刻「受支持」let footype addType(foo, foo/foo) // 注册 foo 类型小贴士注册是幂等安全的——同一扩展名再次注册会覆盖旧条目方便调试时重复执行。 实战第二步用 addMatcher 编写魔数匹配规则有了类型还不会「认文件」。addMatcher需要你传入一个Matcher函数它的类型是(ArrayByte) - Bool定义见 matchers.cj。也就是说接收文件头字节返回「是」或「不是」。func fooMatcher(buf: ArrayByte): Bool { return buf.size 1 buf[0] 0x01 buf[1] 0x02 } addMatcher(footype, fooMatcher)addMatcher内部会用 TypeMatcher 包装 把你的布尔判断包装成「命中返回类型、未命中返回 unknown」的完整匹配器并插入匹配队列最前端——这意味着自定义类型的优先级最高。想参考成熟的写法推荐阅读字体匹配器woff 的判断就是逐字节比对魔数0x77 0x4F 0x46 0x46再校验buf.size防止越界这是编写魔数规则的最佳实践模板。✅ 三步验证确认自定义类型生效注册完成后用三个接口快速自检确认扩展、匹配、MIME 全链路通畅println(isSupported(foo)) // true扩展名已登记 println(isMimeSupported(foo/foo)) // trueMIME 已登记 let kind doMatch(ArrayByte([0x01, 0x02])) println(kind.mime.value , kind.extension) // foo/foo,foo执行结果true true foo/foo,foo三个断言全绿说明你的自定义文件类型已经可以投入使用了。完整接口说明可查阅 官方 API 文档。⚠️ 新手避坑指南3 个常见错误匹配器太「宽松」只判断 1 个字节极易误报比如大量文件都以0x50开头。建议至少比对 3~4 个魔数字节 长度检查参考 isobmff 容器解析。忘记长度判断直接下标访问缓冲区可能不足 N 字节务必先写buf.size n否则会越界。MIME 写法不规范MIME 值建议遵循主类型/子类型格式如application/x-myformat便于与 Web 生态互通解析逻辑见 mime.cj。 总结一句话记住扩展套路步骤接口一句话说明① 登记身份addType(ext, mime)告诉库「这个扩展名叫什么、属于什么 MIME」② 教会认脸addMatcher(type, matcher)告诉库「看到这些魔数字节就认它」③ 上线验证doMatch / isSupported用真实字节跑一遍确认输出正确filetype4cj 内置的图片、视频、音频、压缩、文档等 80 类型见 fixtures 测试文件集你可以拿任意一个样例文件对照测试。掌握了addTypeaddMatcher的组合拳任何新文件格式都难不倒你 Wait, let me fix — I accidentally included a closing artifact. Here is the corrected clean output:如何快速为 filetype4cj 添加自定义文件类型addType 与 addMatcher 完整实战教程 项目简介30 秒了解 filetype4cjfiletype4cj是一个通过检查魔数签名Magic Number来推断文件类型和MIME 类型的轻量级仓颉Cangjie工具库。它无需依赖外部组件只需读取文件头的前 262 字节就能快速识别出 jpg、mp4、zip 等常见文件。但内置类型终归有限——当你的业务需要识别一个私有格式的.cjbin文件时该怎么办答案就是本教程的主角用addType注册新类型再用addMatcher挂载识别规则两步搞定自定义文件类型扩展。 先懂原理类型与匹配器是如何协作的在动手之前花一分钟理解 filetype4cj 的内部结构能帮你少走弯路。从上面的依赖结构图可以看出整个识别链路分为三层模块职责关键文件types 包类型注册表管理扩展名与 MIME 的映射type.cj、types.cjmatchers 包各文件类别的魔数匹配规则matchers.cj、font.cjmatch / filetype对外暴露的匹配与注册入口match.cj、filetype.cj工作机制一句话概括addType把「扩展名 MIME」登记进类型注册表addMatcher把「字节校验函数」绑定到这个类型上。之后每次调用doMatch(buf)时引擎会遍历匹配器列表谁先命中就返回谁见 doMatch 实现。 实战第一步用 addType 注册新文件类型addType的签名非常简单——传入扩展名和MIME 类型即可得到一个Type对象public func addType(ext: String, mime: String): Type它内部会调用 newType 创建类型并立即写入全局注册表见 types.cj所以调用后这个扩展名立刻「受支持」let footype addType(foo, foo/foo) // 注册 foo 类型小贴士同一扩展名再次注册会覆盖旧条目调试时可以放心重复执行。 实战第二步用 addMatcher 编写魔数匹配规则有了类型还不会「认文件」。addMatcher需要你传入一个Matcher函数它的类型是(ArrayByte) - Bool定义见 matchers.cj。也就是说接收文件头字节返回「是」或「不是」。func fooMatcher(buf: ArrayByte): Bool { return buf.size 1 buf[0] 0x01 buf[1] 0x02 } addMatcher(footype, fooMatcher)addMatcher内部会用 TypeMatcher 包装器 把你的布尔判断包装成「命中返回类型、未命中返回 unknown」的完整匹配器并插入匹配队列最前端——这意味着自定义类型的优先级最高。想参考成熟的写法推荐阅读字体匹配器woff 的判断就是逐字节比对魔数再校验buf.size防止越界这是编写魔数规则的最佳实践模板。✅ 三步验证确认自定义类型生效注册完成后用三个接口快速自检确认扩展、匹配、MIME 全链路通畅println(isSupported(foo)) // true扩展名已登记 println(isMimeSupported(foo/foo)) // trueMIME 已登记 let kind doMatch(ArrayByte([0x01, 0x02])) println(kind.mime.value , kind.extension) // foo/foo,foo执行结果true true foo/foo,foo三个断言全绿说明你的自定义文件类型已经可以投入使用了。完整的接口参数说明可查阅 官方 API 文档。⚠️ 新手避坑指南3 个常见错误匹配器太「宽松」只判断 1 个字节极易误报很多文件都从相同的字节开头。建议至少比对 3~4 个魔数字节并做长度检查。忘记长度判断直接下标访问缓冲区可能不足 N 字节务必先写buf.size n否则会越界。MIME 写法不规范MIME 值建议遵循主类型/子类型格式如application/x-myformat便于与 Web 生态互通解析逻辑见 mime.cj。 总结一句话记住扩展套路步骤接口一句话说明① 登记身份addType(ext, mime)告诉库「这个扩展名叫什么、属于什么 MIME」② 教会认脸addMatcher(type, matcher)告诉库「看到这些魔数字节就认它」③ 上线验证doMatch / isSupported用真实字节跑一遍确认输出正确filetype4cj 内置的图片、视频、音频、压缩包、文档等 80 类型样例都可以从 fixtures 测试文件集 中取用做对照测试。掌握了addTypeaddMatcher的组合拳任何新文件格式都难不倒你 【免费下载链接】filetype4cj通过检查魔数签名推断文件和 MIME 类型项目地址: https://gitcode.com/Cangjie-SIG/filetype4cj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考