编码风格¶

不可变性（重要）¶

始终创建新对象，绝不修改现有对象：

// 의사 코드
잘못된 예:  modify(original, field, value) → 원본을 직접 변경
올바른 예: update(original, field, value) → 변경 사항이 반영된 새 복사본 반환

理由：不可变数据可以防止隐藏的副作用，使调试更简单，并实现安全的并发。

文件组织¶

多个小文件 > 少数大文件：

• 高内聚、低耦合
• 通常 200-400 行，最多 800 行
• 从大模块中分离工具函数
• 按功能/领域而非类型进行组织

错误处理¶

始终全面处理错误：

• 在所有层级显式处理错误
• 在 UI 代码中提供用户友好的错误消息
• 在服务端记录详细的错误上下文
• 绝不静默忽略错误

输入验证¶

始终在系统边界进行验证：

• 在处理之前验证所有用户输入
• 尽可能使用基于模式的验证
• 以清晰的错误消息快速失败
• 绝不信任外部数据（API 响应、用户输入、文件内容）

代码质量检查清单¶

在完成工作前检查：

• [ ] 代码是否可读且命名恰当
• [ ] 函数是否短小（<50 行）
• [ ] 文件是否聚焦（<800 行）
• [ ] 没有深层嵌套（>4 层）
• [ ] 是否有适当的错误处理
• [ ] 没有硬编码值（使用常量或配置）
• [ ] 没有突变（使用不可变模式）