最佳实践

AI编程操作指南

#AI编程 #编程规范 #Git Flow #架构设计 #开发流程

第一章：版本控制与协作 (Git Flow)

1. 提交频率 (Commit Frequency)

  • 原子化提交： 任何一个独立的、最小化的功能点在本地测试通过后，都必须立即进行一次git commit。严禁将多个无关的功能，混在一个commit中。

  • 模块化整合： 当一个完整的“业务模块”开发完毕，并通过集成测试后，可以进行一次git push到远程仓库。

2. 提交信息规范 (Commit Message Convention)

  • 严格遵循“Conventional Commits”规范。 格式为：<type>(<scope>): <subject>

    • feat: 新功能
    • fix: Bug修复
    • docs: 文档变更
    • style: 代码风格（不影响代码运行）
    • refactor: 重构（非bug修复，也非新功能）
    • test: 增加或修改测试

  • 目的： 确保提交历史极度清晰、可读、可追溯，并为未来的自动化“更新日志”（Changelog）生成，打下基础。

3. 文档同步 (Documentation Sync)

  • 任何对“模块功能”或“公共API”的重大修改，都必须在同一次commit中，包含对相关文档的更新。代码与文档，必须永远同步。

第二章：编程模式 (The Cathedral Model)

4. 开发顺序

  1. 第一步：数据建模 (Model First)：在写任何业务代码前，必须先在数据库层面，清晰地定义数据表结构、字段、以及表与表之间的关系。数据结构，是整个系统的“地基”。

  2. 第二步：类型定义 (Type Definition)：基于数据模型，在代码中（如types/目录），定义所有可被全局共用的“类型”与“接口”。确保前后端，使用同一套“语言”进行对话。

  3. 第三步：测试驱动 (Test Driven TDD)：

    • 后端：在编写具体业务逻辑前，先为其编写接口测试用例 (API Test Case)。定义清楚：输入什么，应该输出什么，边界条件是什么。
    • 前端：在编写复杂组件前，先思考并罗列出它的所有核心“状态” (States)。

  4. 第四步：编码实现 (Implementation)：在以上“地基”和“脚手架”都搭建完毕后，才开始进行具体的“后端 -> 前端”编码实现。

5. 自我代码审查 (Self Code Review)

  • 在执行git commit之前，必须启动**“陌生人模式”，对自己将要提交的代码，进行一次强制的、至少5分钟的“自我审查”**。

  • 审查清单：

    • 命名是否清晰、无歧义？
    • 注释是否解释了“为什么”，而非“是什么”？
    • 逻辑是否可以更简化？
    • 一年后的我，还能看懂这段代码吗？

第三章：架构的原则 (Architectural Principles)

6. 配置驱动的审慎应用

  • 原则： “配置驱动”主要用于高度标准化、低自定义需求的CRUD模块。

  • 决策记录： （见附录《决策日志》）曾尝试过“动态代码生成”，但因其极大地牺牲了“自定义灵活性”和“长期可维护性”，现已废弃。当前策略是：**以后端配置驱动前端UI生成，但前后端的业务逻辑，均采用“模板代码”而非“动态生成”。

7. 公共模块

  • 已建立的公共模块：common/auth(认证),common/user (用户), common/permission (权限), shared/crud-template (CRUD模板), shared/uploader (上传), shared/errors (错误处理), shared/logger (日志 - 待完成)。

  • 原则： 任何一个，可能在两个或以上模块中被重复使用的功能，都必须被抽象并沉淀到“公共模块”中。 严禁在业务模块之间，出现“复制粘贴”的代码。

8. 注释的规范

  • 函数级注释：所有非简单的公共函数/方法，都必须有函数级注释，说明其功能、参数、和返回值。

  • 块级注释：对于复杂的业务逻辑块，必须使用// #region [描述] 和 // #endregion 进行包裹。

    • 目的：确保在IDE中，复杂的逻辑可以被折叠，让代码的宏观结构，一目了然。

  • 颗粒度原则：在业务模块中，务必按照“单一职责原则”，将复杂的业务流，拆解成多个功能独立的、可被清晰命名的“私有函数”。用“函数名”代替大部分的“注释”。

附录：《决策日志 (Decision Log)》

  • [2025-08-XX] 决策 001：关于“配置驱动”的技术选型
    • 问题：如何高效地处理项目中大量的CRUD操作。
    • 方案评估：
      • A. 动态代码生成：PROS (开发快), CONS (难维护, 难自定义, IDE不友好)。
      • B. 模板代码 + 配置驱动UI：PROS (灵活性高, 易维护), CONS (前期需要搭建模板)。
    • 最终决议：选择方案B。 核心理由：本项目的长期目标，是成为一个可灵活适应不同客户需求的“解决方案”，而非一个僵化的“内部系统”。因此，“长期可维护性”和“自定义灵活性”的优先级，高于“初期的开发速度”。