go-backend

Files (1)

• SKILL.md

SKILL.md (first lines)

# Go Backend Skill

## When to use

- Building or changing backend APIs, gRPC endpoints, or REST Gateway surface
- Implementing or updating domain entities, value objects, or business logic
- Adding or changing handlers, services, or repository implementations
- Editing Protocol Buffers or generated gRPC/gateway code workflow
- Fixing backend bugs (follow TDD: failing test first, then fix)

For **migrations** (schema, up/down), use the `database-migrations` skill. For **testing** focus (TDD, mocks, integration), use the `testing` skill.

## Idiomatic Go baseline

Apply Go community best practices **inside** this project's DDD layers (Handler → Service → Domain → Repository). Do not replace encapsulated domain entities or layered architecture with anemic structs.

| Principle | Rule |
|-----------|------|
| **Context** | `ctx context.Context` as first parameter on service, repo, and handler methods; propagate from the request; never use `context.Background()` in handlers |
| **Errors** | Return errors explicitly; wrap with `fmt.Errorf("...: %w", err)`; compare domain/sentinel errors with `errors.Is` / `errors.As` |
| **Packages** | One package per directory; lowercase single-word names; no circular imports; domain imports nothing from infra (no SQL, protobuf, HTTP) |
| **Interfaces** | Small, consumer-defined; **accept interfaces, return structs**; generate mocks against those interfaces |
| **Constructors** | `NewXxx(...) (T, error)` for non-trivial types; validate in constructor or factory |
| **Receivers** | Consistent pointer vs value receivers on a type; prefer value receivers when the method does not mutate state |
| **Naming** | Idiomatic Go: short package names, no stutter (`user.ID` not `user.UserID`), exported API documented with doc comments |
| **Concurrency** | Tie goroutines to `ctx`; use `errgroup` for parallel work; no fire-and-forget goroutines in request paths |
| **Safety** | No `panic` in production request paths; use `defer` for cleanup (`Close`, `Rollback`) |
| **Stdlib first** | Prefer standard library; reach for third-party packages only when stdlib is insufficient |
| **Generated code** | Never edit generated proto/gateway output; change `.proto` and run `make generate` |

## Implementation workflows

### New domain entity

1. Create domain model in `internal/domain/`
2. Add repository interface
3. Implement repository in `internal/repository/`
4. Create service in `internal/service/`
5. Create handler in `internal/handler/`
6. Add proto definition
7. Write tests for each layer
8. Update migrations if needed (see `database-migrations` skill)

### New API endpoint

1. Add proto definition
2. Run `make generate`
3. Implement handler
4. Implement service method
5. Add repository methods if needed
6. Write integration test
7. Test via gRPC and REST Gateway

### Business logic change

1. Move the rule to a domain method when possible
2. Add or update methods on domain entities
3. Update services to orchestrate domain methods (no duplicated rules)
4. Write tests at the domain layer first
5. Update documentation if behavior changed

## Layer-specific patterns

### Domain

Behavior on entities, value objects via constructors, sentinel errors in the domain package.

```go
var ErrInvalidEmail = errors.New("invalid email")

type Email struct {
    value string
}

func NewEmail(value string) (Email, error) {
    if !isValidEmail(value) {
        return Email{}, ErrInvalidEmail
    }
    return Email{value: strings.ToLower(value)}, nil
}

func (u *User) ChangeEmail(newEmail Email) error {
    if u.email == newEmail {
        return ErrEmailUnchanged
    }
    u.email = newEmail
    u.updatedAt = time.Now()
    return nil
}
```

### Service

Authorization via `auth.GetPrincipal(ctx)`; orchestration only—no SQL, no proto types, no business rules that belong in domain.

```go
func (s *EntityService) CreateResource(ctx context.Context, req *CreateResourceRequest) (*domain.Entity, error) {
    principal := auth.GetPrincipal(ctx)
    if principal == nil {
        return nil, errors.ErrUnauthorized
    }
    if principal.UserType != domain.RoleX {
        return nil, errors.ErrForbidden
    }

    entity, err := domain.NewEntity(req.Name, req.OwnerID)
    if err != nil {
        return nil, err
    }
    if err := s.repo.Save(ctx, entity); err != nil {
        return nil, fmt.Errorf("save entity: %w", err)
    }
    return entity, nil
}
```

### Repository

Parameterized queries, map rows to domain entities, pass `ctx` through, map `sql.ErrNoRows` to domain errors.

From pedromsmoreira/ai-configs, MIT.

More from pedromsmoreira/ai-configs