go-backend-microservices

微服务的 Go 后端开发

核心原则

• 应用整洁架构，清晰划分处理器、服务、仓库和领域模型
• 优先采用接口驱动开发，并显式注入依赖
• 编写简短、聚焦且职责单一的函数
• 确保安全使用 goroutine，并通过 channel 或 sync 原语保护共享状态

项目结构

维护模块化的项目结构，并清晰划分目录：

project/
├── cmd/           # Application entry points
├── internal/      # Private application code
├── pkg/           # Public library code
├── api/           # API definitions (OpenAPI, protobuf)
├── configs/       # Configuration files
└── test/          # Additional test utilities

错误处理

• 始终显式检查并处理错误
• 使用包装错误以便追踪：fmt.Errorf("context: %w", err)
• 为特定领域的错误创建自定义错误类型
• 在调用栈中向上返回错误，并附上适当的上下文
• 在适当的级别记录错误，并提供充足的上下文

上下文传播

• 使用上下文传播请求范围内的值、截止时间和取消信号
• 将 context 作为函数的第一个参数传递
• 在长时间运行的操作中遵循上下文取消信号
• 为外部调用设置适当的超时时间

可观测性

使用 OpenTelemetry 实现全面的可观测性：

分布式追踪

• 为重要操作添加 span
• 在服务边界之间传播追踪上下文
• 在 span 中包含相关属性

指标

• 为业务操作实现自定义指标
• 使用标准指标类型（计数器、仪表、直方图）
• 以 Prometheus 格式导出指标

结构化日志

• 使用结构化日志，并保持字段名称一致
• 在日志条目中包含追踪 ID
• 在适当的级别记录日志（调试、信息、警告、错误）

安全

• 严格验证所有外部输入
• 为 JWT 令牌和 cookie 使用安全默认值
• 实施适当的身份验证和授权
• 在记录日志之前清理数据，避免泄露敏感信息
• 对数据库查询使用预处理语句

测试

单元测试

• 编写覆盖充分的表驱动单元测试
• 在安全的情况下并行执行测试
• 使用接口模拟外部依赖
• 专注于测试业务逻辑

集成测试

• 将集成测试与单元测试分开
• 使用测试容器来提供数据库和服务依赖
• 测试实际的 API 端点和响应

并发

• 适当地使用 goroutine 执行并发操作
• 通过 channel 或 sync 原语保护共享状态
• 实现妥善的优雅关闭
• 使用工作池限制并发数量

文档

• 使用 GoDoc 风格的注释编写文档
• 随代码变更及时更新注释
• 充分记录公共 API
• 在有帮助时，在文档中提供示例

CI/CD 集成

• 保持 CI 集成，以运行代码检查和测试
• 使用 golangci-lint 进行全面的代码检查
• 在每个拉取请求上运行测试
• 包含代码覆盖率报告