golang-backend-guidelines

name	golang-backend-guidelines
description	指导 Go 后端功能的分层设计、领域实体建模、Service 编排、错误边界、日志与依赖方向。新增或修改 application、model/entity、infrastructure、transport、controller、repository 或 Service 代码时使用。

Go 后端开发规范

实现或审查 Go 后端功能时，遵循本技能的分层、领域模型和错误边界规则。与本技能配套的命名、代码风格、context、安全和 lint 规则见仓库中的相关技能链接。

核心规则

1. 模型尽可能使用充血模型

涉及业务状态和业务规则的实体应优先采用充血模型：把数据、状态变化和与自身相关的约束放进实体本身，不把有明确业务行为的实体退化成只有字段的数据库记录。对于纯 DTO、简单 CRUD 或没有业务不变量的持久化映射，不强行增加领域行为。

• DTO 只负责协议输入输出；实体负责领域状态和行为。
• 外部代码不能直接修改受业务规则保护的状态；通过实体方法完成状态变化。
• 实体方法必须校验当前状态和输入，拒绝非法转换并返回明确错误。
• 复杂跨实体流程仍由 Application Service 编排，但单个实体自身的规则不能散落在 Service 中。
• 持久化映射不应成为绕过实体行为的入口；Repository 负责读写，Service 负责用例编排，实体负责自身不变量。

示例：

type Order struct {
	status OrderStatus
}

func (o *Order) Pay(payment Payment) error {
	if o.status == OrderStatusCanceled {
		return ErrOrderCanceled
	}
	if payment.Amount <= 0 {
		return ErrInvalidPayment
	}

	o.status = OrderStatusPaid
	return nil
}

func (o Order) Status() OrderStatus {
	return o.status
}

调用方应使用 order.Pay(payment)、order.Cancel(reason)、order.Ship(trackingNo)，而不是直接执行 order.status = ...。实体必须保证“已取消不能支付”“未付款不能发货”等不变量。

2. Service 是错误边界

Service 返回给 Controller 的错误必须是 constant/errors.go 定义的 constant.ServiceError，不能把 Repository、数据库、网络或加密库的底层错误直接返回给前端。

• 可向用户解释的输入或领域错误，映射到对应的 ServiceError，例如 constant.ErrBadRequest、constant.ErrUserNotFound。
• 不应暴露的底层错误必须先记录完整日志，再映射为 constant.ErrSystemMalfunction。
• 日志记录底层错误；响应只返回稳定的错误码和用户可见消息。
• 不要把 SQL、文件路径、密钥、堆栈、供应商错误或内部实现细节放进 ServiceError.Message。
• Service 不得直接 return err，除非 err 已明确是允许暴露的 constant.ServiceError。
• 需要判断错误类型时使用 errors.Is 或 errors.As，不要依赖字符串比较。

推荐写法：

user, err := s.userRepository().GetByUsername(ctx, request.Username)
if err != nil {
	s.res.Logger().Error(ctx, "failed to get user by username", err)
	return nil, constant.ErrSystemMalfunction
}

校验错误和领域错误应在 Service 边界映射；底层错误应在日志中保留诊断信息，但不越过 Service 边界。

3. 遵循项目分层和依赖方向

• transport → application → infrastructure，Controller 不得直接访问 Repository。
• Transport 负责协议解析和响应适配；Application Service 负责编排用例；Repository 负责持久化；Entity 负责领域规则。
• 通过项目已有的 Resource、Logger、Validator 和 Infrastructure 接口获取横向能力，不在业务层自行初始化连接或全局资源。
• 新增功能按仓库 AGENTS.md 的标准流程注册 DTO、Repository、Service、Controller、路由和依赖注入。

4. 注释使用中文

• 所有代码注释、包注释、导出符号文档注释和业务说明注释使用中文。
• 代码标识符、API 名称、协议名称、标准库术语和包名可以保留英文。
• 注释应说明必要的意图、约束或行为，不重复显而易见的代码。

5. 正确传播 context 和日志

• 所有需要 context 的 Service、Repository 和外部调用都把 ctx context.Context 放在第一个参数。
• 沿调用链传递同一个 context，不在请求处理中创建新的 context.Background()。
• 需要通过 context.WithValue 传递请求级元数据时，key 常量统一定义在 constant/contextkey.go；禁止在各业务层重复定义 context key。
• context 只携带请求级元数据，不要用它传递普通业务参数、Service、Repository 或可选配置。
• 底层失败时在最接近业务边界的 Service 记录带上下文的结构化日志，再返回服务错误。
• 不在实体中保存 context.Context、Logger、Repository 或 HTTP 对象。

6. 实现后的检查

完成代码后至少执行：

gofmt -w <modified-go-files>
golangci-lint run ./...
go vet ./...
go test ./...

同时检查：实体状态是否只能通过行为修改、Service 是否泄露底层错误、日志是否包含足够诊断上下文，以及错误映射是否覆盖所有失败路径。

配套技能

• golang-naming
• golang-code-style
• golang-context
• golang-safety
• golang-lint
• 项目错误定义
• 项目 Context Key 定义

需要更详细的充血模型和错误边界示例时，读取领域模型与错误边界参考。