Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-architect

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/object-storage-setup-upload.md

View on GitHub
# Object Storage — S3 Client Setup and Upload Patterns

Practical guide to integrating S3-compatible object storage in Go Gin APIs.

---

## When to Use Object Storage

```
START: Are you storing files > 1MB or binary blobs?
  ├── No  → PostgreSQL BYTEA or local filesystem. Done.
  └── Yes → Do you need CDN delivery?
      ├── Yes → S3 + CloudFront / CDN. Done.
      └── No  → Is it user-uploaded content?
          ├── Yes → S3 with presigned PUT URLs (client uploads directly)
          └── No  → S3 with server-side upload (internal pipelines)
```

**Cost gate:** S3 charges per request + per GB + egress. For internal files rarely downloaded, PostgreSQL BYTEA (< 5 MB) or a mounted volume is simpler. Choose object storage when you expect > 100 MB total data or need CDN/direct-client access.

---

## S3 Client Setup

Dependencies:

```
go get github.com/aws/aws-sdk-go-v2
go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/credentials
go get github.com/aws/aws-sdk-go-v2/service/s3
```

```go
// pkg/storage/s3.go
type S3Client struct {
    client *s3.Client
    bucket string
    logger *slog.Logger
}

// Compatible with AWS S3, MinIO, and Cloudflare R2.
// Pass empty endpoint for real AWS.
func NewS3Client(endpoint, region, accessKey, secretKey, bucket string) (*S3Client, error) {
    optFns := []func(*config.LoadOptions) error{
        config.WithRegion(region),
        config.WithCredentialsProvider(
            credentials.NewStaticCredentialsProvider(accessKey, secretKey, ""),
        ),
    }

    cfg, err := config.LoadDefaultConfig(context.Background(), optFns...)
    if err != nil {
        return nil, fmt.Errorf("storage: load config: %w", err)
    }

    clientOpts := []func(*s3.Options){}
    if endpoint != "" {
        clientOpts = append(clientOpts, func(o *s3.Options) {
            o.BaseEndpoint = aws.String(endpoint)
            o.UsePathStyle = true // required for MinIO
        })
    }

    return &S3Client{
        client: s3.NewFromConfig(cfg, clientOpts...),
        bucket: bucket,
        logger: slog.Default().With("component", "s3"),
    }, nil
}
```

Environment variables:

```
S3_ENDPOINT=http://localhost:9000   # empty for real AWS
S3_REGION=us-east-1
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=myapp
```

---

## Upload: Thin Handler

```go
const maxUploadSize = 100 << 20 // 100 MB

func (h *FileHandler) Upload(c *gin.Context) {
    c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxUploadSize)

    file, header, err := c.Request.FormFile("file")
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "invalid file: " + err.Error()})
        return
    }
    defer file.Close()

    contentType := header.Header.Get("Content-Type")
    if contentType == "" {
        contentType = "application/octet-stream"
    }

    url, err := h.svc.Upload(c.Request.Context(), file, header.Filename, contentType)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "upload failed"})
        return
    }
    c.JSON(http.StatusCreated, gin.H{"url": url})
}
```

## Upload: Service and Storage Method

```go
func (s *fileService) Upload(ctx context.Context, r io.Reader, filename, contentType string) (string, error) {
    key := fmt.Sprintf("uploads/%s%s", uuid.New().String(), filepath.Ext(filename))
    url, err := s.store.PutObject(ctx, key, contentType, r)
    if err != nil {
        return "", fmt.Errorf("file service upload: %w", err)
    }
    return url, nil
}

func (c *S3Client) PutObject(ctx context.Context, key, contentType string, body io.Reader) (string, error) {
    _, err := c.client.PutObject(ctx, &s3.PutObjectInput{
        Bucket:      aws.String(c.bucket),
        Key:         aws.String(key),
        Body:        body,
        ContentType: aws.String(contentType),
    })
    if err != nil {
        return "", fmt.Errorf("s3 put object %q: %w", key, err)
    }
    c.logger.InfoContext(ctx, "object uploaded", "key", key)
    return fmt.Sprintf("s3://%s/%s", c.bucket, key), nil
}
```

---

## See Also

- `object-storage-download-presign.md` — download/streaming, presigned URLs, multipart upload, MinIO Docker Compose
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall