modular-go

modular-go

关于 Go 包设计的简明指南，助你构建精简、聚焦且易于演进的包。

目的与适用场景

• 用于 Go 包设计、重构和代码审查。
• 关注 API 边界、状态建模和流程分解。
• 在选择合适的抽象层级时使用：局部辅助函数、工具包、管理器或构建器。
• 优先采用明确的边界，而非为了方便而导出的内容。

设计原则

1. 每个导出项都是一种承诺——保持公共接口精简且有明确目的。
2. 一个包只负责一件事，并且能用一句话解释清楚。
3. 深度胜于广度——隐藏丰富实现的窄接口，比宽泛浅显的接口更经久耐用。
4. 默认无状态——将可变状态视为负担，除非它能证明其生命周期成本是值得的。
5. 按职责边界拆分，而非按文件大小拆分——每个新边界都必须证明其间接成本合理。
6. 编排负责讲清流程；能力方法负责执行工作。
7. 边界是转换层——在边界处转换错误、类型和协议，而不是在核心逻辑中转换。
8. 选择能解决实际问题的最小抽象；避免过早泛化。
9. 生命周期是首要设计考量——设计启动路径时，也要设计关闭路径。

工作流

1. 定义一个包的职责。
2. 提供一个显而易见的主要入口（类型、接口或函数）。
3. 默认让辅助函数保持在本地；只有确实需要跨包复用时，才提取到 xxxutil。
4. 让传输处理器专注于协议映射，并将行为委托给注入的依赖项。
5. 通过聚焦的函数组合编排流程，并用简短注释说明每个阶段的意图。
6. 当无法再用一句话解释一个包时，重新评估其边界。
7. 合并前，根据参考检查清单重新检查。

主题

主题	指引	参考
模块边界	暴露最小化 API，并区分深接口与宽接口	references/module-boundary.md
状态流	使用无状态函数和一次性状态对象	references/state-flow.md
编排	使用单一公共执行器和内部辅助函数	references/orchestration.md
gRPC 实践	让处理器成为精简的转换器；将传输层与领域逻辑隔离	references/grpc-practices.md
审查清单	合并前快速检查架构是否合理	references/review-checklist.md

参考资料

• 参考文件有意保持简短，并聚焦具体任务。
• 源链接列在每个参考文件的 frontmatter urls 中。