调试的少年A
2026-11-10 17:36:10 发布当 HarmonyOS 项目只有一两名开发者时,很多开发习惯可以通过口头沟通解决。但随着团队扩大、功能模块增加,代码风格不一致、组件重复开发、命名规则混乱和文档缺失等问题就会逐渐显现。
有的开发者习惯把业务逻辑写在页面组件中,有的开发者会单独建立服务模块;有的组件命名采用统一规则,有的则直接使用临时名称。短期内,这些差异可能不会影响功能运行,但当多人共同维护一个项目时,就会增加理解成本和代码审查难度。
AI Coding 可以帮助团队整理已有代码规范、补充注释和生成项目文档。不过,规范建设不应该从一份全新的模板开始,而应该先分析当前项目实际采用的开发方式,再把团队已经认可的规则整理出来。
以一个多人协作的内容社区应用为例,项目中包含首页、文章详情、用户中心、评论和消息等模块。不同开发者负责不同模块,如果没有统一约定,可能出现相似功能使用不同命名、数据模型重复定义、异常处理方式不一致等问题。
第一步,可以让 AI 分析项目现有代码:
请分析当前 HarmonyOS 工程中的代码组织方式。
重点检查:
1. 文件和目录命名;
2. 页面和组件命名;
3. ArkTS 类型定义;
4. 状态管理方式;
5. 网络请求组织方式;
6. 异常处理方式;
7. 注释和文档习惯。
请总结当前项目已经形成的规则,
并指出不一致的地方。
本次只分析,不要修改代码。
这一步很重要,因为团队规范应该服务于实际工程,而不是为了看起来专业而引入一套完全不同的结构。如果项目已经形成稳定的组件组织方式,就应该优先保留;如果某些模块确实存在重复和混乱,再逐步统一。
第二步是把规范整理成可执行的开发约定。例如,页面文件和公共组件如何命名,业务接口放在哪里,数据模型如何定义,组件属性和事件回调如何设计,错误处理应该在哪一层完成。这些规则越具体,AI 后续生成代码时越容易遵循。
可以要求 AI 根据分析结果生成一份开发规范初稿:
请根据当前 HarmonyOS 工程的实际代码,
整理一份团队开发规范。
规范至少包括:
1. 目录和文件命名;
2. 页面与公共组件命名;
3. ArkTS 类型定义要求;
4. 页面状态管理约定;
5. 网络请求和数据访问约定;
6. 异常处理要求;
7. 注释和文档要求;
8. 代码提交前的检查项。
请区分项目当前已经采用的规则和建议新增的规则,
不要把建议写成已经执行的事实。
第三步是让 AI 在日常开发中遵循规范。开发者可以将关键约定放入项目级开发说明中,或者在每次任务开始时明确要求 AI 阅读相关文档。这样,AI 在生成新页面或组件时,就能参考团队已有的命名和结构,而不是每次采用不同写法。
例如:
开始本次开发前,请先阅读当前项目的开发规范和已有同类模块。
开发要求:
1. 优先复用已有组件和服务;
2. 遵循现有目录和命名规则;
3. 不随意新增重复的数据模型;
4. 不擅自改变公共组件接口;
5. 新增代码需要补充必要注释;
6. 修改已有模块时说明变更范围。
如果当前需求与已有规范冲突,请先指出冲突,不要自行决定。
代码注释也是团队规范的一部分,但注释并不是越多越好。AI 有时会给每一行代码都增加解释,导致注释冗长且没有实际价值。更值得补充的是复杂业务规则、特殊处理原因、关键参数约束和容易被误用的公共接口。
可以让 AI 对已有代码进行针对性注释:
请检查当前模块中的注释。
重点补充:
1. 复杂业务规则的说明;
2. 公共组件属性和回调的用途;
3. 关键数据模型的字段含义;
4. 特殊异常处理的原因;
5. 容易被误用的接口约束。
不要为简单赋值和显而易见的代码增加无意义注释。
不要改变任何业务逻辑。
第四步是生成项目文档。对于新加入团队的开发者来说,能够快速了解项目目录、主要模块职责、页面关系和数据流向,比阅读大量零散代码更有效。AI 可以根据现有工程生成模块说明、组件使用说明和开发环境配置文档,但文档内容必须与真实代码一致。
尤其要注意文档的更新机制。代码发生变化后,旧文档可能很快过期。因此,可以把文档检查纳入代码提交前的流程:新增公共组件时更新组件说明,调整接口时更新接口文档,修改模块职责时更新架构说明。
第五步是让 AI 参与代码审查。每次提交前,可以要求 AI 检查本次变更是否符合团队规范,是否存在重复组件、命名不一致、类型定义缺失和不必要的业务耦合。AI 的检查结果可以作为代码审查的辅助材料,但不能代替团队成员对业务逻辑和代码质量的最终判断。
请根据项目开发规范审查本次代码变更。
检查:
1. 是否违反现有命名和目录规则;
2. 是否重复实现已有公共能力;
3. 是否存在不必要的类型转换;
4. 是否缺少必要的异常处理;
5. 是否需要更新项目文档;
6. 是否存在与本次需求无关的代码修改。
请按问题位置、风险和修改建议输出结果。
团队规范真正的价值,不是增加开发流程,而是让多人协作时能够保持一致。AI Coding 可以帮助团队从已有代码中提炼规则、补充文档和进行日常检查,但规范是否合理,仍然需要团队共同确认。把 AI 作为规范执行的辅助工具,而不是规范制定的唯一决策者,才能让 HarmonyOS 项目在人员和功能不断增长时保持良好的工程秩序。
调试的少年A
我还没有写个人简介......
帖子
提问
粉丝
用 AI Coding 把旧项目迁移到 HarmonyOS:先分析代码资产,再决定怎么改
2026-11-10 17:37:15 发布AI Coding 如何帮团队建立 HarmonyOS 开发规范?从代码注释到项目文档
2026-11-10 17:36:10 发布



0
京公网安备:11010502051901号