Auto-sync: 2026-04-27 04:02

wiki/sources/开发经验与项目规范整理文档.md

@@ -1,62 +1,70 @@
----
-title: "开发经验与项目规范整理文档"
-type: source
-tags: [vibe-coding, software-engineering, best-practices, coding-standards]
-sources: []
-last_updated: 2025-12-30
----
-
-## Source File
-- [[Vibe Coding/开发经验与项目规范整理文档]]
-
-## Summary（用中文描述）
-- 核心主题：Vibe Coding 环境下的开发经验与项目规范最佳实践，涵盖编码规范、系统架构原则、程序设计思想及基础设施（微服务、Redis、消息队列）
-- 问题域：如何建立可持续维护的 AI 辅助开发项目；如何制定团队编码规范；如何通过规范提升 AI 生成的代码质量
-- 方法/机制：
-  - 变量名维护方案（统一变量索引文件）
-  - 文件结构与命名规范（小写英文 + 下划线/小驼峰）
-  - 编码规范（单一职责、DRY、模块化）
-  - 系统架构原则（先梳理架构、小步迭代）
-  - 程序设计核心思想（从问题出发、清晰命名、测试优先）
-  - 微服务拆分原则（独立开发/部署/扩容）
-  - Redis 缓存策略（提升读性能、降低 DB 压力）
-  - 消息队列异步通信（解耦、削峰、异步任务）
-- 结论/价值：为 AI 辅助开发项目提供系统化规范框架，强调从问题出发而非代码出发，提升代码可维护性和团队协作效率
-
-## Key Claims（用中文描述）
-- 统一变量索引文件能降低命名冲突和语义不清晰带来的风险
-- 编码规范中的「消费端 → 生产端 → 状态 → 变换」模型能清晰划分系统行为边界
-- 系统开发应遵循「先理解需求 → 保持简单 → 测试驱动 → 小步迭代」的严谨流程
-- 编程第一步永远是「你要解决什么问题」，而非直接写代码
-- 注释解释「为什么」，而非「怎么做」
-
-## Key Quotes
-> "编程的第一步永远是：你要解决什么问题？" — 从问题出发而非代码
-> "你写的代码是给别人理解的，不是来炫技的。" — 代码可读性优先
-> "注释解释'为什么'，不是'怎么做'。" — 合理注释原则
-> "未测试的代码迟早会出问题。" — 测试优先
-
-## Key Concepts
-- [[单一职责原则]]：每个文件、类、函数应只负责一件事
-- [[DRY原则]]：Don't Repeat Yourself，避免重复代码，提炼公共逻辑
-- [[模块化编程]]：将系统分解为独立模块，提高复用价值
-- [[微服务架构]]：将系统拆解为独立开发、部署、扩容的服务
-- [[Redis缓存]]：作为缓存提升系统读性能，降低数据库压力
-- [[消息队列]]：用于服务之间的异步通信，实现解耦和削峰填谷
-- [[输入-处理-输出模型]]：明确区分消费端（接收数据）、生产端（生成数据）、状态（存储信息）、变换（处理逻辑）
-- [[并发编程]]：区分共享资源、数据竞争、锁机制与异步处理的差异
-
-## Key Entities
-- 无特定实体提及，本文档为方法论文档
-
-## Connections
-- [[Vibe Coding]] ← 相关领域 ← 本文：提供 AI 辅助开发的项目规范框架
-- [[单一职责原则]] ← 编码规范核心 ← [[DRY原则]] ← 模块化基础
-- [[微服务架构]] ← 服务拆分原则 ← [[Redis缓存]] ← 性能优化手段
-- [[消息队列]] ← 异步通信基础设施 ← 微服务间通信机制
-
-## Contradictions
-- 与传统软件开发方法冲突：
-  - 冲突点：传统强调"先理解代码再修改"，本文强调"从问题出发而非代码出发"
-  - 当前观点：Vibe Coding 环境下，AI 生成代码量大，应先明确问题再让 AI 生成，而非逐步理解 AI 生成的代码
-  - 对方观点：传统软件工程强调对代码的深度理解是维护和修改的前提
+---
+title: "开发经验与项目规范整理文档"
+type: source
+tags: [vibe-coding, software-engineering, best-practices, coding-standards, microservices, redis, message-queue]
+sources: []
+last_updated: 2025-12-30
+---
+
+## Source File
+- [[Vibe Coding/开发经验与项目规范整理文档]]
+
+## Summary（用中文描述）
+- 核心主题：Vibe Coding 环境下的开发经验与项目规范最佳实践，涵盖编码规范、系统架构原则、程序设计思想及基础设施（微服务、Redis、消息队列）
+- 问题域：如何建立可持续维护的 AI 辅助开发项目；如何制定团队编码规范；如何通过规范提升 AI 生成的代码质量
+- 方法/机制：
+  - 变量名维护方案（统一变量索引文件，格式：变量名 | 变量注释 | 出现位置 | 出现频率）
+  - 文件结构与命名规范（子文件夹含 agents + claude.md；文件命名小写英文 + 下划线/小驼峰）
+  - 编码规范（单一职责、DRY、模块化；消费端/生产端/状态/变换模型）
+  - 并发编程规范（共享资源、数据竞争、锁机制、并发 vs 异步区分）
+  - 系统架构原则（先梳理架构 → 理解需求 → 保持简单 → 自动化测试 → 小步迭代）
+  - 程序设计核心思想（从问题出发、清晰命名、单一职责、可读性优先、合理注释、测试优先）
+  - 微服务拆分原则（独立开发/部署/扩容，服务间通过 API 通信）
+  - Redis 缓存策略（提升读性能、降低 DB 压力、提供计数/锁/队列/Session 能力）
+  - 消息队列异步通信（解耦、削峰填谷、异步任务处理）
+- 结论/价值：为 AI 辅助开发项目提供系统化规范框架，强调从问题出发而非代码出发，提升代码可维护性和团队协作效率
+
+## Key Claims（用中文描述）
+- 统一变量索引文件能降低命名冲突和语义不清晰带来的风险，实现 AI 与团队全局命名一致性管理
+- 编码规范中的「消费端 → 生产端 → 状态 → 变换」模型能清晰划分系统行为边界，明确输入→处理→输出各环节
+- 系统开发应遵循「先理解需求 → 保持架构与代码简单 → 写可维护的自动化测试 → 小步迭代，不做大爆炸开发」的严谨流程
+- 编程第一步永远是「你要解决什么问题」，复杂问题拆解为可独立完成的小单元，减少复杂度、魔法代码、晦涩技巧
+- 注释解释「为什么」，而非「怎么做」；代码可读性优先，写的代码是给别人理解的，不是来炫技的
+- 未测试的代码迟早会出问题，调试是程序员核心技能，永远不要把代码只放本地
+- 微服务将系统拆解为多个独立开发、独立部署、独立扩容的服务，服务间通过 API 通信（HTTP、RPC、MQ 等）
+- Redis 通过缓存提升系统读性能、降低数据库压力，并提供计数、锁、队列、Session 等扩展能力
+- 消息队列实现服务间的异步通信，带来解耦、削峰填谷、异步任务处理等系统稳定性与吞吐收益
+
+## Key Quotes
+> "编程的第一步永远是：你要解决什么问题？" — 从问题出发而非代码
+> "你写的代码是给别人理解的，不是来炫技的。" — 代码可读性优先
+> "注释解释'为什么'，不是'怎么做'。" — 合理注释原则
+> "未测试的代码迟早会出问题。" — 测试优先
+> "永远不要把代码只放本地。" — 调试是必修课
+
+## Key Concepts
+- [[单一职责原则]]：每个文件、类、函数应只负责一件事，提炼公共逻辑，避免重复代码（DRY）
+- [[DRY原则]]：Don't Repeat Yourself，避免重复代码，提高复用价值
+- [[模块化编程]]：将系统分解为独立模块，提高复用价值，函数化、类化、模块化
+- [[输入-处理-输出模型]]：明确区分消费端（接收外部数据）、生产端（生成数据/输出结果）、状态（存储当前系统信息）、变换（处理状态/改变数据的逻辑）
+- [[并发编程]]：区分共享资源、数据竞争、必要时加锁或使用线程安全结构，区分"并发处理"和"异步处理"的差异
+- [[微服务架构]]：将系统拆解为独立开发、部署、扩容的服务，服务间通过 API 通信
+- [[Redis缓存]]：作为缓存提升系统读性能，降低数据库压力，提供计数/锁/队列/Session 能力
+- [[消息队列]]：用于服务之间的异步通信，实现解耦、削峰填谷、异步任务处理
+- [[系统架构梳理]]：模块划分、输入输出、数据流向、服务边界、技术栈、依赖关系在写代码前先明确
+
+## Key Entities
+- 无特定商业实体提及，本文档为方法论文档，涵盖软件工程通用规范框架
+
+## Connections
+- [[Vibe Coding]] ← 相关领域 ← 本文：提供 AI 辅助开发的项目规范框架
+- [[单一职责原则]] ← 编码规范核心 ← [[DRY原则]] ← 模块化基础
+- [[微服务架构]] ← 服务拆分原则 ← [[Redis缓存]] ← 性能优化手段
+- [[消息队列]] ← 异步通信基础设施 ← 微服务间通信机制
+- [[输入-处理-输出模型]] ← 系统行为划分 ← [[系统架构梳理]] ← 开发前置工作
+
+## Contradictions
+- 与传统软件开发方法冲突：
+  - 冲突点：传统强调"先理解代码再修改"，本文强调"从问题出发而非代码出发"
+  - 当前观点：Vibe Coding 环境下，AI 生成代码量大，应先明确问题再让 AI 生成，而非逐步理解 AI 生成的代码
+  - 对方观点：传统软件工程强调对代码的深度理解是维护和修改的前提