开发工具IDE调试器代码质量【免费下载链接】cangjie_deveco_plugins项目地址https://gitcode.com/Cangjie/cangjie_deveco_plugins点击查看免费下载本文围绕 cangjie_deveco_plugins 仓库中 cjlint 规则文档G_SER_03.md展开完整讲解这条保证序列化和反序列化的变量类型一致的仓颉语言静态检查规则它的检查级别、风险成因、官方正例与反例并结合本仓库 cjlint 插件的源码说明该规则如何从 SDK 的 cjlint 引擎一路传递到 IDE 的缺陷报告以及如何在工程中配置、忽略这条规则。读完后你将掌握仓颉Serializable序列化代码中写出类型 读回类型的实现要点与自检方法并了解该规则在 Devec 生态 IDE 插件中的落地链路。规则概览G.SER.03 的级别与定位G.SER.03 是仓颉语言静态检查lint规则集中的一条序列化类规则其文档在仓库中的位置是 G_SER_03.md核心内容如下规则编号G.SER.03规则名称保证序列化和反序列化的变量类型一致级别要求描述仓颉不会对序列化和反序列化使用的数据进行类型检查。如果反序列化时使用的数据类型和序列化时传入的数据类型不一致则可能会造成数据错误。开发者需要保证序列化和反序列化时传入数据和接收数据的变量类型一致。这条规则与同目录下的 G_SER_01.md禁止序列化未加密的敏感数据、G_SER_02.md防止反序列化绕过构造函数中的安全操作共同构成G_SER序列化子系列分别对应安全、行为一致性、数据完整性三个维度。G.SER.03 聚焦的是其中最容易被忽视的一类问题读写两端类型契约不一致导致的数据错误。要求级别的含义在 cjlint 插件的结果解析逻辑中引擎输出的缺陷级别会被映射为 IDE 展示的严重程度。从源码 CjlintCodeCheckCmd.getInfo 可以看到if (originDefectInfo.getDefectLevel().equalsIgnoreCase(SUGGESTIONS)) { defectInfo.setSeverity(SUGGESTIONS_SEVERITY); // 1 } else if (originDefectInfo.getDefectLevel().equalsIgnoreCase(MANDATORY)) { defectInfo.setSeverity(MANDATORY_SEVERITY); // 2 }即suggestions建议映射为严重程度1mandatory要求/强制映射为严重程度2。G.SER.03 标注为【要求】级别意味着它属于强制项mandatory在代码检查报告中会以更高的严重度呈现通常应在提交前修复。规则核心为什么序列化与反序列化必须类型一致规则的出发点是一句关键描述仓颉不会对序列化和反序列化使用的数据进行类型检查。结合文档中的代码示例可以梳理出仓颉序列化机制中涉及的几个核心要素SerializableT类通过class Xxx : SerializableXxx声明自身可序列化T指定该类型本身serialize(): DataModel实例方法负责把字段写入数据模型DataModelStruct().add(fieldT(key, value))以泛型T声明某个字段以何种类型写入DataModelT.deserialize(data)静态方法以类型T从DataModel中读回字段private init(s: DataModelStruct)私有的反序列化构造入口通常由public static func deserialize(s: DataModel)调用。fieldT写入时的类型参数T与读取时的T.deserialize构成一对类型契约。由于运行时不做类型检查这个契约完全依赖开发者自觉遵守写入端声明fieldInt64读取端就必须用Int64.deserialize写入Int64却用Int32.deserialize读取数据就会出错。G.SER.03 正是针对这一风险提出的强制要求。正例类型一致的序列化实现官方正例完整代码如下class MySerializeDemo : SerializableMySerializeDemo { var value: Int64 var msg: String init(v: Int64) { value v msg match (value) { case 0x0 zero case 0x7fffffff BIG INT case _ DEFAULT } } public func serialize(): DataModel { DataModelStruct().add(fieldInt64(value, value)) } private init(s: DataModelStruct) { let v Int64.deserialize(s.get(value)) value v msg match (v) { case 0x0 zero case 0x7fffffff BIG INT case _ DEFAULT } } public static func deserialize(s: DataModel): MySerializeDemo { let d (s as DataModelStruct).getOrThrow() MySerializeDemo(d) } }逐点解析正例中的关键做法写入与读取类型严格配对serialize()中以fieldInt64(value, value)写入private init(s: DataModelStruct)中以Int64.deserialize(s.get(value))读回两端都是Int64契约一致。派生字段随原始字段重建msg不是被序列化的字段而是在反序列化入口中基于恢复出来的v重新计算其match分支与公开构造函数init(v: Int64)中的逻辑保持完全一致保证反序列化对象的派生状态与正常构造的对象无差异。反序列化入口受控private init(s: DataModelStruct)为私有构造外部只能经由public static func deserialize(s: DataModel)进入其中通过(s as DataModelStruct).getOrThrow()取出结构后再调用私有构造形成完整的反序列化入口链。正确示例中序列化和反序列化使用的变量类型一致保证了反序列化后得到的对象数据符合预期。反例Int64 写出、Int32 读回导致数据截断官方反例与正例仅有一处差异完整代码如下class MySerializeDemo : SerializableMySerializeDemo { var value: Int64 var msg: String init(v: Int64) { value v msg match (value) { case 0x0 zero case 0x7fffffff BIG INT case _ DEFAULT } } public func serialize() : DataModel { DataModelStruct().add(fieldInt64(value, value)) } private init(s: DataModelStruct) { let v Int32.deserialize(s.get(value)) value Int64(v) msg match (v) { case 0x0 zero case 0x7fffffff BIG INT case _ DEFAULT } } public static func deserialize(s: DataModel): MySerializeDemo { let d (s as DataModelStruct).getOrThrow() MySerializeDemo(d) } }错误点精确定位在反序列化构造中这一行let v Int32.deserialize(s.get(value)) value Int64(v)错误示例中序列化时传入的参数value是Int64类型但接收时使用的是Int32类型的变量因此会造成数据截断导致反序列化后的对象数据与预期不一致。这里有两个值得注意的细节截断发生在读取瞬间错误不在后续的Int64(v)宽化转换而在Int32.deserialize这一步——当被序列化的原始值超出Int32可表示的范围时高 32 位的信息在读回阶段就已经丢失或引发数值错误之后再转回Int64也无法恢复原始值match分支依赖读回值msg是基于被截断后的v计算的因此连派生字段也会偏离正例中同样的Int64路径所算出的结果错误会沿着对象状态继续扩散。正/反例对比与类型一致性自查清单对比项正例反例写入类型fieldInt64(value, value)fieldInt64(value, value)读取类型Int64.deserialize(s.get(value))Int32.deserialize(s.get(value))字段声明value: Int64value: Int64结果数据符合预期数据截断对象状态偏离预期据此可以整理出一份序列化代码的类型一致性自查清单对每一个被序列化的字段核对其在fieldT中的类型参数T与T.deserialize的类型完全一致并与字段声明类型如value: Int64三者对齐反序列化入口中恢复出的原始字段值应作为派生字段如msg重算的唯一输入且重算逻辑与公开构造函数保持一致这一点与 G_SER_02.md 中反序列化行为应与公开构造函数一致的要求互为补充若字段存在有符号/无符号或不同位宽的整数变体特别容易在写出宽类型、读回窄类型的模式上出错这正是 G.SER.03 反例刻意演示的陷阱。规则如何进入 IDE 检查结果cjlint 插件链路在 cangjie_deveco_plugins 仓库中G.SER.03 这类规则文档本身并不直接参与检查而是随插件分发、供 IDE 在用户点击某条缺陷时展示规则说明。从源码结构看这条规则 → 文档的链路如下。1. 引擎注册与可执行文件定位插件描述符 cjlint.xml 将 CjlintEngine 注册为engineProvider。CjlintEngine.buildCommandLine负责定位真正的 cjlint 可执行文件private static OptionalString getCjlintExe(NotNull Project project) { OptionalString compilerPathOptional PathUtils.getCompilerPath(project); if (SystemInfo.isWindows) { return compilerPathOptional.map(s - s SEPARATOR TOOLS SEPARATOR BIN SEPARATOR CJLINT_WINDOWS); } else { return compilerPathOptional.map(s - s SEPARATOR TOOLS SEPARATOR BIN SEPARATOR CJLINT_MAC); } }即从仓颉 SDK 的 build-tools 路径下取tools/bin/cjlintWindows 为tools/bin/cjlint.exe并把检查结果输出到项目缓存目录.idea/.deveco/cangjie/cjlint/cjoutput.json。2. 命令行组装与结果解析检查命令在 CjlintCodeCheckCmd.checkCode 中组装形如cjlint -f 仓颉模块源码目录 -o cjoutput.json [--import-path cjo依赖路径] [-c 配置目录]其中-f指向模块的仓颉源码目录插件会按cjpm.toml所在目录推导--import-path携带从cjpm.toml的target.aarch64-linux-ohos.bin-dependencies中解析出的path/package依赖见 getCjoDepends保证 cjlint 能解析到跨模块类型-c仅在工程存在自定义规则配置时才追加见下文项目级配置一节。参数常量定义在 CommonConstants.javaFILE_PATH_TERMINAL -f、OUTPUT_TERMINAL -o、IMPORT_PATH --import-path。cjlint 执行结束后editCheckResult()读取cjoutput.json其中每条缺陷对应 DefectInfo 的结构defectLevel级别、file文件、description描述、defectType规则编号、language、line、column。defectType会被设置为缺陷的ruleId也就是G.SER.03这样的编号。3. 缺陷如何关联到 G_SER_03.md 文档这正是本篇文档存在的意义所在。CjlintCodeCheckCmd.getRuleDocPath 的映射逻辑是docPath.append(plugin.getPluginPath()).append(File.separator).append(LIB_PATH) .append(File.separator).append(ENGINE_NAME).append(File.separator); String result description.substring(ZERO, description.indexOf(COLON)).replace(POINT, UNDER_LINE); docPath.append(DOCS).append(File.separator).append(result).append(MD_TYPE);即取description冒号之前的规则编号G.SER.03把点号替换为下划线得到G_SER_03拼成插件目录下lib/cjlint/docs/G_SER_03.md的路径。因此规则文档的文件命名下划线形式与规则编号点号形式之间是通过这套转换规则关联的——仓库中 docs 目录 下的G_SER_01.md、G_SER_02.md、G_SER_03.md等文件与规则一一对应。项目级规则配置与忽略机制结合本仓库源码开发者在工程中可以有三层手段控制 G.SER.03 等规则的检查行为。1. 自定义规则清单cjlint_rule_list.json 与 exclude_lists.json从 processCustomizedCJLintConfigs 的实现看插件会检查工程根目录下是否存在cjlint_rule_list.json与exclude_lists.json若存在则复制到项目缓存配置目录并把 SDK 默认配置目录tools/config中未被项目覆盖的文件补齐最终通过-c参数把该缓存目录传给 cjlint实现自定义规则替换默认规则。cjlint_rule_list.json 对应的映射类结构非常简单Data public class CjlintRuleListConfig { private ListString ruleList; }即一个规则编号字符串数组规则编号需符合 CodeCheckConstantUtil.REGEX 定义的形态[A-Z_]{1,10}_\d{1,5}如G_SER_03。若该文件存在但解析失败或取不到RuleList字段插件会直接返回空检查结果属于配置即契约的严格处理。2. 文件范围过滤code-linter.json5filterResultListByCodeLinterJson5 读取工程根目录的code-linter.json5按 CodeLinterJson5Config 中的两个数组做结果过滤filesglob 模式数组限定检查适用的文件范围不匹配的文件缺陷被剔除ignore相对工程根目录的 glob 模式匹配到的文件缺陷被剔除。这意味着对于不希望在 G.SER.03 约束范围内的生成代码目录可以通过ignore从结果层面排除。3. 单行/整文件忽略注释cjlint-ignore插件支持在代码中直接写忽略注释规则编号会由G_SER_03形式转换为点号形式CjLintManager.getIgnoreRule 将匹配到的编号做replaceAll(_, .)并加!前缀得到!G.SER.03。结合 PsiHandler 的注释创建逻辑忽略注释的两种形态为// 忽略单条缺陷行 // cjlint-ignore !G.SER.03 // 整文件屏蔽首行 -start 与 -end 配对 // cjlint-ignore -start !G.SER.03 ... // cjlint-ignore -end在 IDE 中屏蔽某条缺陷时插件会定位到对应PsiElement并在其前插入/合并这类注释见 CjlintEngine.changeOrAddComment已有同位置的cjlint-ignore注释会被合并而非重复新增。适用前提与限制规则文档与检查能力随仓颉 SDKcjlint 工具位于 SDK build-tools 的tools/bin下和com.huawei.cangjie-support-plugin插件分发从源码结构看若未安装 SDK插件在解析规则文档路径时会记录 Install cangjie sdk failed. 告警并返回空路径检查对象为仓颉模块cangjie module的源码目录插件依赖cjpm.toml定位模块并解析--import-path依赖文中Serializable、DataModelStruct、fieldT等 API 属于仓颉语言 SDK 的序列化能力本文示例以规则文档中的正/反例为准G.SER.03 属于要求mandatory级别若工程通过cjlint_rule_list.json自定义了规则清单需确认其中对G_SER_03的取舍符合团队规范。小结G.SER.03 用一条简洁的约束守住了仓颉序列化机制中最脆弱的一环写出端fieldT与读回端T.deserialize必须使用同一类型。正例展示了Int64两端配对、派生字段同步重算的完整写法反例则用一行Int32.deserialize演示了写出 64 位、读回 32 位造成的数据截断。在 cangjie_deveco_plugins 仓库中这条规则以 G_SER_03.md 的形式随插件分发由 cjlint 引擎在命令行检查中产出缺陷再经 CjlintCodeCheckCmd 解析、定级并关联回本篇文档配合cjlint_rule_list.json、code-linter.json5与cjlint-ignore注释共同构成完整的规则治理链路。赞分享开发工具IDE调试器代码质量【免费下载链接】cangjie_deveco_plugins项目地址https://gitcode.com/Cangjie/cangjie_deveco_plugins点击查看免费下载相关推荐仓颉 CjLint 静态检查规则 G.SER.01在序列化中防止未加密敏感数据泄露仓颉 CjLint 静态检查规则 G.SER.01在序列化中防止未加密敏感数据泄露 本篇围绕 cangjie_deveco_plugins 仓库中 CjLin开发工具IDE调试器代码质量Location类序列化与反序列化ReflectionCommon中的状态保存Location类序列化与反序列化ReflectionCommon中的状态保存 你是否在PHP项目中遇到过对象状态持久化的难题当需要保存代码元素位置信息时静态分析仓颉安全编码规范 G.SER.02 详解防止反序列化绕过构造函数安全校验与 cjlint 静态检查实践仓颉安全编码规范 G.SER.02 详解防止反序列化绕过构造函数安全校验与 cjlint 静态检查实践 本文基于 cangjie_deveco_plugins开发工具IDE调试器代码质量上一篇微信聊天记录怎么永久保存免费开源WeChatMsg三步导出HTML、Word、CSV还能生成专属年度报告下一篇RxJava 操作符矩阵五大响应式类型的 237 个操作符覆盖与选用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考