Обзор кейсов проектирования

<?php

declare(strict_types=1);

final class LoadEstimation
{
    /**
     * Example: URL Shortener estimation
     */
    public static function estimate(): array
    {
        // Daily Active Users
        $dau = 100_000_000;

        // Each user creates 1 short URL per day on average
        $writesPerDay = $dau * 1;

        // Read/Write ratio = 100:1
        $readsPerDay = $writesPerDay * 100;

        // QPS (Queries Per Second)
        $writeQps = (int) ($writesPerDay / 86400);    // ~1157 QPS
        $readQps = (int) ($readsPerDay / 86400);       // ~115,740 QPS

        // Storage per record: ~500 bytes
        $storagePerDay = $writesPerDay * 500;           // ~50 GB/day
        $storagePerYear = $storagePerDay * 365;         // ~18 TB/year

        // Bandwidth
        $incomingBandwidth = $writeQps * 500;           // ~578 KB/s
        $outgoingBandwidth = $readQps * 500;            // ~57 MB/s

        return [
            'write_qps' => $writeQps,
            'read_qps' => $readQps,
            'storage_per_year' => self::formatBytes($storagePerYear),
            'outgoing_bandwidth' => self::formatBytes($outgoingBandwidth) . '/s',
        ];
    }

    private static function formatBytes(int|float $bytes): string
    {
        $units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
        $i = 0;

        while ($bytes >= 1024 && $i < count($units) - 1) {
            $bytes /= 1024;
            $i++;
        }

        return round($bytes, 2) . ' ' . $units[$i];
    }
}

package estimation

import "fmt"

// LoadEstimation demonstrates back-of-the-envelope estimation
// for a URL Shortener system.
type LoadEstimation struct{}

func (LoadEstimation) Estimate() map[string]string {
	// Daily Active Users
	dau := 100_000_000

	// Each user creates 1 short URL per day on average
	writesPerDay := dau * 1

	// Read/Write ratio = 100:1
	readsPerDay := writesPerDay * 100

	// QPS (Queries Per Second)
	writeQPS := writesPerDay / 86400    // ~1157 QPS
	readQPS := readsPerDay / 86400      // ~115,740 QPS

	// Storage per record: ~500 bytes
	storagePerDay := writesPerDay * 500         // ~50 GB/day
	storagePerYear := float64(storagePerDay) * 365 // ~18 TB/year

	// Bandwidth
	outgoingBandwidth := float64(readQPS) * 500 // ~57 MB/s

	return map[string]string{
		"write_qps":          fmt.Sprintf("%d", writeQPS),
		"read_qps":           fmt.Sprintf("%d", readQPS),
		"storage_per_year":   formatBytes(storagePerYear),
		"outgoing_bandwidth": formatBytes(outgoingBandwidth) + "/s",
	}
}

func formatBytes(bytes float64) string {
	units := []string{"B", "KB", "MB", "GB", "TB", "PB"}
	i := 0
	for bytes >= 1024 && i < len(units)-1 {
		bytes /= 1024
		i++
	}
	return fmt.Sprintf("%.2f %s", bytes, units[i])
}

using System.Globalization;

namespace SysDesign.Estimation;

// LoadEstimation demonstrates back-of-the-envelope estimation
// for a URL Shortener system.
public static class LoadEstimation
{
    private static readonly string[] Units = ["B", "KB", "MB", "GB", "TB", "PB"];

    public static IReadOnlyDictionary<string, string> Estimate()
    {
        // Daily Active Users
        const long dau = 100_000_000;

        // Each user creates 1 short URL per day on average
        const long writesPerDay = dau * 1;

        // Read/Write ratio = 100:1
        const long readsPerDay = writesPerDay * 100;

        // QPS (Queries Per Second)
        const long writeQps = writesPerDay / 86_400;  // ~1157 QPS
        const long readQps = readsPerDay / 86_400;    // ~115,740 QPS

        // Storage per record: ~500 bytes
        const long storagePerDay = writesPerDay * 500;       // ~50 GB/day
        const double storagePerYear = storagePerDay * 365d;  // ~18 TB/year

        // Bandwidth
        const double outgoingBandwidth = readQps * 500d;     // ~57 MB/s

        return new Dictionary<string, string>
        {
            ["write_qps"] = writeQps.ToString(CultureInfo.InvariantCulture),
            ["read_qps"] = readQps.ToString(CultureInfo.InvariantCulture),
            ["storage_per_year"] = FormatBytes(storagePerYear),
            ["outgoing_bandwidth"] = FormatBytes(outgoingBandwidth) + "/s",
        };
    }

    private static string FormatBytes(double bytes)
    {
        var i = 0;

        while (bytes >= 1024 && i < Units.Length - 1)
        {
            bytes /= 1024;
            i++;
        }

        return string.Create(CultureInfo.InvariantCulture, $"{bytes:F2} {Units[i]}");
    }
}

"""Back-of-the-envelope estimation for a URL Shortener system."""

from typing import Final

UNITS: Final[tuple[str, ...]] = ("B", "KB", "MB", "GB", "TB", "PB")

def format_bytes(num_bytes: float) -> str:
    value = float(num_bytes)
    i = 0

    while value >= 1024 and i < len(UNITS) - 1:
        value /= 1024
        i += 1

    return f"{value:.2f} {UNITS[i]}"

def estimate() -> dict[str, str]:
    # Daily Active Users
    dau = 100_000_000

    # Each user creates 1 short URL per day on average
    writes_per_day = dau * 1

    # Read/Write ratio = 100:1
    reads_per_day = writes_per_day * 100

    # QPS (Queries Per Second)
    write_qps = writes_per_day // 86_400  # ~1157 QPS
    read_qps = reads_per_day // 86_400    # ~115,740 QPS

    # Storage per record: ~500 bytes
    storage_per_day = writes_per_day * 500    # ~50 GB/day
    storage_per_year = storage_per_day * 365  # ~18 TB/year

    # Bandwidth
    outgoing_bandwidth = read_qps * 500       # ~57 MB/s

    return {
        "write_qps": str(write_qps),
        "read_qps": str(read_qps),
        "storage_per_year": format_bytes(storage_per_year),
        "outgoing_bandwidth": format_bytes(outgoing_bandwidth) + "/s",
    }

<?php

declare(strict_types=1);

/**
 * Typical API design for a case study
 */
interface SystemApiInterface
{
    // Core CRUD operations
    // POST /api/v1/resources
    public function create(CreateResourceRequest $request): ResourceResponse;

    // GET /api/v1/resources/{id}
    public function get(string $id): ResourceResponse;

    // PUT /api/v1/resources/{id}
    public function update(string $id, UpdateResourceRequest $request): ResourceResponse;

    // DELETE /api/v1/resources/{id}
    public function delete(string $id): void;

    // List with pagination (cursor-based!)
    // GET /api/v1/resources?cursor=xxx&limit=20
    public function list(string $cursor, int $limit): PaginatedResponse;
}

// Always define clear request/response DTOs
final readonly class CreateResourceRequest
{
    public function __construct(
        public string $name,
        public string $type,
        public array $metadata = [],
    ) {}
}

final readonly class ResourceResponse
{
    public function __construct(
        public string $id,
        public string $name,
        public string $type,
        public string $createdAt,
    ) {}
}

final readonly class PaginatedResponse
{
    public function __construct(
        public array $items,
        public ?string $nextCursor,
        public bool $hasMore,
    ) {}
}

package api

import (
	"context"
	"time"
)

// SystemAPI defines the typical CRUD interface for a case study.
type SystemAPI interface {
	Create(ctx context.Context, req CreateResourceRequest) (ResourceResponse, error)
	Get(ctx context.Context, id string) (ResourceResponse, error)
	Update(ctx context.Context, id string, req UpdateResourceRequest) (ResourceResponse, error)
	Delete(ctx context.Context, id string) error
	List(ctx context.Context, cursor string, limit int) (PaginatedResponse, error)
}

// CreateResourceRequest is a request DTO for resource creation.
type CreateResourceRequest struct {
	Name     string            `json:"name"`
	Type     string            `json:"type"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

// UpdateResourceRequest is a request DTO for resource update.
type UpdateResourceRequest struct {
	Name     *string           `json:"name,omitempty"`
	Type     *string           `json:"type,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

// ResourceResponse is a response DTO for a single resource.
type ResourceResponse struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Type      string    `json:"type"`
	CreatedAt time.Time `json:"created_at"`
}

// PaginatedResponse wraps a page of results with cursor-based pagination.
type PaginatedResponse struct {
	Items      []ResourceResponse `json:"items"`
	NextCursor string             `json:"next_cursor,omitempty"`
	HasMore    bool               `json:"has_more"`
}

namespace SysDesign.Api;

// ISystemApi defines the typical CRUD interface for a case study.
// Wire format stays snake_case via
// JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower.
public interface ISystemApi
{
    // POST /api/v1/resources
    Task<ResourceResponse> CreateAsync(CreateResourceRequest request, CancellationToken ct);

    // GET /api/v1/resources/{id}
    Task<ResourceResponse> GetAsync(string id, CancellationToken ct);

    // PUT /api/v1/resources/{id}
    Task<ResourceResponse> UpdateAsync(string id, UpdateResourceRequest request, CancellationToken ct);

    // DELETE /api/v1/resources/{id}
    Task DeleteAsync(string id, CancellationToken ct);

    // List with pagination (cursor-based!)
    // GET /api/v1/resources?cursor=xxx&limit=20
    Task<PaginatedResponse> ListAsync(string? cursor, int limit, CancellationToken ct);
}

// Always define clear request/response DTOs
public sealed record CreateResourceRequest(
    string Name,
    string Type,
    IReadOnlyDictionary<string, string>? Metadata = null);

// null means "field not provided" for a partial update
public sealed record UpdateResourceRequest(
    string? Name = null,
    string? Type = null,
    IReadOnlyDictionary<string, string>? Metadata = null);

public sealed record ResourceResponse(
    string Id,
    string Name,
    string Type,
    DateTimeOffset CreatedAt);

public sealed record PaginatedResponse(
    IReadOnlyList<ResourceResponse> Items,
    string? NextCursor,
    bool HasMore);

from __future__ import annotations

from dataclasses import dataclass, field
from datetime import datetime
from typing import Protocol

# Protocol gives structural typing -- the closest equivalent
# to a Go interface, no explicit implements needed.
class SystemApi(Protocol):
    # POST /api/v1/resources
    async def create(self, request: CreateResourceRequest) -> ResourceResponse: ...

    # GET /api/v1/resources/{id}
    async def get(self, resource_id: str) -> ResourceResponse: ...

    # PUT /api/v1/resources/{id}
    async def update(
        self, resource_id: str, request: UpdateResourceRequest
    ) -> ResourceResponse: ...

    # DELETE /api/v1/resources/{id}
    async def delete(self, resource_id: str) -> None: ...

    # List with pagination (cursor-based!)
    # GET /api/v1/resources?cursor=xxx&limit=20
    async def list(self, cursor: str | None, limit: int) -> PaginatedResponse: ...

# Always define clear request/response DTOs
@dataclass(frozen=True, slots=True)
class CreateResourceRequest:
    name: str
    type: str
    metadata: dict[str, str] = field(default_factory=dict)

@dataclass(frozen=True, slots=True)
class UpdateResourceRequest:
    # None means "field not provided" for a partial update
    name: str | None = None
    type: str | None = None
    metadata: dict[str, str] | None = None

@dataclass(frozen=True, slots=True)
class ResourceResponse:
    id: str
    name: str
    type: str
    created_at: datetime

@dataclass(frozen=True, slots=True)
class PaginatedResponse:
    items: list[ResourceResponse]
    next_cursor: str | None
    has_more: bool

<?php

declare(strict_types=1);

/**
 * Base service pattern used across case studies
 */
abstract class BaseService
{
    public function __construct(
        protected readonly \Redis $redis,
        protected readonly \PDO $db,
        protected readonly LoggerInterface $logger,
    ) {}

    /**
     * Cache-aside pattern (used in most case studies)
     */
    protected function cacheAside(string $key, int $ttl, callable $loader): mixed
    {
        $cached = $this->redis->get($key);

        if ($cached !== false) {
            return json_decode($cached, true);
        }

        $data = $loader();

        $this->redis->setex($key, $ttl, json_encode($data));

        return $data;
    }

    /**
     * Idempotency key pattern (used in payment, booking systems)
     */
    protected function executeIdempotent(
        string $idempotencyKey,
        callable $operation,
    ): mixed {
        $existing = $this->redis->get("idempotency:{$idempotencyKey}");

        if ($existing !== false) {
            return json_decode($existing, true);
        }

        $result = $operation();

        $this->redis->setex(
            "idempotency:{$idempotencyKey}",
            86400, // 24h
            json_encode($result),
        );

        return $result;
    }

    /**
     * Distributed lock pattern (used in booking, inventory)
     */
    protected function withLock(string $resource, int $ttl, callable $callback): mixed
    {
        $lockKey = "lock:{$resource}";
        $lockValue = bin2hex(random_bytes(16));

        $acquired = $this->redis->set(
            $lockKey,
            $lockValue,
            ['NX', 'EX' => $ttl],
        );

        if (!$acquired) {
            throw new \RuntimeException("Failed to acquire lock for: {$resource}");
        }

        try {
            return $callback();
        } finally {
            // Release only if we still own the lock
            $script = <<<'LUA'
                if redis.call("get", KEYS[1]) == ARGV[1] then
                    return redis.call("del", KEYS[1])
                else
                    return 0
                end
            LUA;

            $this->redis->eval($script, [$lockKey, $lockValue], 1);
        }
    }
}

package service

import (
	"context"
	"crypto/rand"
	"database/sql"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"log/slog"
	"time"

	"github.com/redis/go-redis/v9"
)

// BaseService provides common patterns used across case studies.
type BaseService struct {
	Redis  *redis.Client
	DB     *sql.DB
	Logger *slog.Logger
}

// CacheAside implements the cache-aside pattern.
func (s *BaseService) CacheAside(ctx context.Context, key string, ttl time.Duration, loader func() (any, error)) (json.RawMessage, error) {
	cached, err := s.Redis.Get(ctx, key).Bytes()
	if err == nil {
		return cached, nil
	}

	data, err := loader()
	if err != nil {
		return nil, fmt.Errorf("cache aside loader: %w", err)
	}

	encoded, err := json.Marshal(data)
	if err != nil {
		return nil, fmt.Errorf("marshal cache data: %w", err)
	}

	s.Redis.Set(ctx, key, encoded, ttl)
	return encoded, nil
}

// ExecuteIdempotent ensures an operation runs exactly once per idempotency key.
func (s *BaseService) ExecuteIdempotent(ctx context.Context, idempotencyKey string, operation func() (any, error)) (json.RawMessage, error) {
	cacheKey := "idempotency:" + idempotencyKey

	existing, err := s.Redis.Get(ctx, cacheKey).Bytes()
	if err == nil {
		return existing, nil
	}

	result, err := operation()
	if err != nil {
		return nil, err
	}

	encoded, err := json.Marshal(result)
	if err != nil {
		return nil, fmt.Errorf("marshal idempotent result: %w", err)
	}

	s.Redis.Set(ctx, cacheKey, encoded, 24*time.Hour)
	return encoded, nil
}

// WithLock executes a callback under a distributed Redis lock.
func (s *BaseService) WithLock(ctx context.Context, resource string, ttl time.Duration, callback func() error) error {
	lockKey := "lock:" + resource
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return fmt.Errorf("generate lock value: %w", err)
	}
	lockValue := hex.EncodeToString(b)

	ok, err := s.Redis.SetNX(ctx, lockKey, lockValue, ttl).Result()
	if err != nil {
		return fmt.Errorf("acquire lock: %w", err)
	}
	if !ok {
		return fmt.Errorf("failed to acquire lock for: %s", resource)
	}

	defer func() {
		// Release only if we still own the lock
		script := `
			if redis.call("get", KEYS[1]) == ARGV[1] then
				return redis.call("del", KEYS[1])
			else
				return 0
			end`
		s.Redis.Eval(ctx, script, []string{lockKey}, lockValue)
	}()

	return callback()
}

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.Extensions.Logging;
using Npgsql;
using StackExchange.Redis;

namespace SysDesign.Services;

// BaseService provides common patterns used across case studies.
public abstract class BaseService(
    IDatabase redis,
    NpgsqlDataSource db,
    ILogger<BaseService> logger)
{
    protected IDatabase Redis { get; } = redis;
    protected NpgsqlDataSource Db { get; } = db;
    protected ILogger<BaseService> Logger { get; } = logger;

    // Cache-aside pattern (used in most case studies)
    protected async Task<T> CacheAsideAsync<T>(string key, TimeSpan ttl, Func<Task<T>> loader)
    {
        RedisValue cached = await Redis.StringGetAsync(key);

        if (cached.HasValue)
        {
            return JsonSerializer.Deserialize<T>(cached!)!;
        }

        T data = await loader();

        await Redis.StringSetAsync(key, JsonSerializer.Serialize(data), ttl);

        return data;
    }

    // Idempotency key pattern (used in payment, booking systems)
    protected async Task<T> ExecuteIdempotentAsync<T>(
        string idempotencyKey,
        Func<Task<T>> operation)
    {
        string cacheKey = $"idempotency:{idempotencyKey}";

        RedisValue existing = await Redis.StringGetAsync(cacheKey);

        if (existing.HasValue)
        {
            return JsonSerializer.Deserialize<T>(existing!)!;
        }

        T result = await operation();

        await Redis.StringSetAsync(
            cacheKey,
            JsonSerializer.Serialize(result),
            TimeSpan.FromHours(24)); // 24h

        return result;
    }

    // Distributed lock pattern (used in booking, inventory)
    protected async Task<T> WithLockAsync<T>(string resource, TimeSpan ttl, Func<Task<T>> callback)
    {
        string lockKey = $"lock:{resource}";
        string lockValue = Convert.ToHexString(RandomNumberGenerator.GetBytes(16));

        bool acquired = await Redis.StringSetAsync(lockKey, lockValue, ttl, When.NotExists);

        if (!acquired)
        {
            throw new InvalidOperationException($"Failed to acquire lock for: {resource}");
        }

        try
        {
            return await callback();
        }
        finally
        {
            // Release only if we still own the lock
            const string script = """
                if redis.call("get", KEYS[1]) == ARGV[1] then
                    return redis.call("del", KEYS[1])
                else
                    return 0
                end
                """;

            await Redis.ScriptEvaluateAsync(script, [lockKey], [lockValue]);
        }
    }
}

from __future__ import annotations

import json
import logging
import secrets
from collections.abc import Awaitable, Callable
from typing import Any, TypeVar

import asyncpg
import redis.asyncio as redis

T = TypeVar("T")

# Release only if we still own the lock
_RELEASE_LOCK_SCRIPT = """
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end
"""

class BaseService:
    """Base service pattern used across case studies."""

    def __init__(
        self,
        redis_client: redis.Redis,
        db: asyncpg.Pool,
        logger: logging.Logger,
    ) -> None:
        self._redis = redis_client
        self._db = db
        self._logger = logger

    # Cache-aside pattern (used in most case studies)
    async def cache_aside(
        self,
        key: str,
        ttl: int,
        loader: Callable[[], Awaitable[Any]],
    ) -> Any:
        cached = await self._redis.get(key)

        if cached is not None:
            return json.loads(cached)

        data = await loader()

        await self._redis.setex(key, ttl, json.dumps(data))

        return data

    # Idempotency key pattern (used in payment, booking systems)
    async def execute_idempotent(
        self,
        idempotency_key: str,
        operation: Callable[[], Awaitable[Any]],
    ) -> Any:
        cache_key = f"idempotency:{idempotency_key}"

        existing = await self._redis.get(cache_key)

        if existing is not None:
            return json.loads(existing)

        result = await operation()

        await self._redis.setex(
            cache_key,
            86400,  # 24h
            json.dumps(result),
        )

        return result

    # Distributed lock pattern (used in booking, inventory)
    async def with_lock(
        self,
        resource: str,
        ttl: int,
        callback: Callable[[], Awaitable[T]],
    ) -> T:
        lock_key = f"lock:{resource}"
        lock_value = secrets.token_hex(16)

        acquired = await self._redis.set(lock_key, lock_value, nx=True, ex=ttl)

        if not acquired:
            raise RuntimeError(f"Failed to acquire lock for: {resource}")

        try:
            return await callback()
        finally:
            await self._redis.eval(_RELEASE_LOCK_SCRIPT, 1, lock_key, lock_value)